Analytics Reporting API - 授权

本指南介绍应用如何向对 Analytics Reporting API 的请求进行授权。

给请求授权

用户必须首先登录 Google 账号,然后才能在 Google Analytics(分析)网站上查看他们的账号信息。同样,当用户首次访问您的应用时,他们需要授权您的应用访问他们的数据。

您的应用向 Google Analytics(分析)API 发出的每个请求都必须包含授权令牌。Google 也可通过此令牌来识别您的应用。

关于授权协议

您的应用必须使用 OAuth 2.0 向请求授权,其他任何授权协议均不受支持。如果您的应用使用使用 Google 账号登录,系统会代您执行授权方面的某些操作。

使用 OAuth 2.0 向请求授权

向 Google Analytics(分析)API 发出的所有请求均须由经过身份验证的用户授权。

根据您所编写的应用的类型,OAuth 2.0 的具体授权流程可能会有所不同。下面是适用于所有应用类型的大致流程:

  1. 开发应用时,您需要使用 Google API 控制台注册该应用。然后,Google 会提供您稍后需要用到的信息,例如客户端 ID 和客户端密钥。
  2. 在 Google API 控制台中激活 Google Analytics(分析)API。(如果 API 控制台中未列出该 API,请跳过这一步。)
  3. 当您的应用需要访问用户数据时,它会请求 Google 提供特定范围的访问权限。
  4. Google 会向相应用户显示权限请求页面,让用户授权您的应用请求他们的某些数据。
  5. 待该用户同意后,Google 会为您的应用提供一个时效很短的访问令牌
  6. 您的应用会请求获取用户数据,并在请求中附上该访问令牌。
  7. 如果 Google 确定您的请求及令牌有效,就会返回您所请求的数据。

有些流程还包含其他步骤,例如使用刷新令牌获取新的访问令牌。如需详细了解适用于各类应用的不同流程,请参阅 Google 的 OAuth 2.0 文档

以下是 Google Analytics(分析)API 的 OAuth 2.0 作用域信息:

范围 含义
https://www.googleapis.com/auth/analytics.readonly Google Analytics(分析)API 的只读访问权限。

要通过 OAuth 2.0 请求访问权限,您的应用需要范围信息,以及 Google 在您注册应用时提供的相关信息(如客户端 ID 和客户端密钥)。

提示:Google API 客户端库可帮您处理部分授权流程,并且支持多种编程语言;有关详情,请参阅库和示例页面

常见的 OAuth 2.0 流程

下面列出了特定 OAuth 2.0 流程的常见用例:

网络服务器

该流程适用于自动、离线或定期访问用户的 Google Analytics(分析)数据。

例如:

  • 使用最新的 Google Analytics(分析)数据自动更新用户信息中心。

客户端

如果用户直接与应用互动,以通过浏览器访问其 Google Analytics(分析)数据,那么此流程是应用的理想选择。此流程对服务器端功能不再有要求,不过不能再自动、离线或定期生成报告。

例如:

已安装的应用

此流程适用于以软件包形式分发并由用户安装的应用。它需要应用或用户具有浏览器访问权限,才能完成身份验证流程。

示例:

  • PC 或 Mac 上的桌面微件。
  • 内容管理系统插件 - 与网络服务器或客户端相比,此流程的优势在于可对您的应用使用单个 API 控制台项目,从而为用户提供经过汇总的报告,并简化安装。

服务账号

服务账号适合于对您账号的 Google Analytics(分析)数据的自动、离线或定期访问。例如,为您的 Google Analytics(分析)数据创建实时信息中心,并与其他用户共享。

要开始使用 Google Analytics(分析)API,您需要先使用设置工具,该工具会引导您在 Google API 控制台中创建项目、启用 API 以及创建凭据。

要开设新的服务账号,请按以下步骤操作:

  1. 点击创建凭据 > 服务账号密钥
  2. 选择要下载哪种格式的服务账号公钥/私钥文件,是标准的 P12 文件还是可由 Google API 客户端库加载的 JSON 文件。

接下来系统就会为您生成新的公钥/私钥对并将其下载到您的计算机;这对密钥仅此一份,您应负责妥善存储。

问题排查

在以下情况下,您的授权会失败:

  • 如果您的 access_token 已过期,或者您对 API 使用了错误的范围,您会收到 401 状态代码。

  • 如果已获授权的用户无权访问数据视图(配置文件),您会收到 403 状态代码。请务必将权限授予适当的用户,并确保他们拥有您所选的数据视图(配置文件)。

OAuth 2.0 Playground

此工具可用于通过网页界面完成整个授权流程。它还会显示进行授权查询所需的所有 HTTP 请求标头。如果您在自己的应用中无法完成授权,您应该尝试通过 OAuth 2.0 Playground 来完成授权。然后,您可以将该 Playground 的 HTTP 标头和请求与您的应用发送给 Google Analytics(分析)的标头和请求进行对比。这项检查便于确保所使用的请求格式正确无误。

授权无效

当您尝试使用刷新令牌时,以下情况会返回 invalid_grant 错误:

应用可以请求多个刷新令牌来访问一个 Google Analytics(分析)账号。

例如,当用户想要在多台机器上安装某个应用,并访问同一个 Google Analytics(分析)账号时,那么每台机器都需要一个单独的令牌。当刷新令牌的数量超出上限时,较早的令牌便会失效。如果应用尝试使用失效的刷新令牌,系统会返回 invalid_grant 错误响应。

每个唯一的 OAuth 2.0 客户端和 Google Analytics(分析)账号对的刷新令牌数量上限为 25。如果应用不断请求同一客户端和账号对的刷新令牌,在第 26 个令牌发出之后,之前发出的第 1 个令牌将失效。第 27 个请求的刷新令牌会使之前发出的第 2 个令牌失效,依此类推。