Core Reporting API - 授权

本文档介绍应用如何获取授权,以向 Core Reporting API 发送请求。

给请求授权

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

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

关于授权协议

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

使用 OAuth 2.0 给请求授权

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

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

  1. 创建应用时,您需要使用 Google Developers Console 进行注册。然后,Google 会提供您稍后需要用到的信息,例如客户端 ID 和客户端密钥。
  2. 在 Google Developers Console 中激活 Google Analytics(分析)API。(如果 Developers Console 中未列出该 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 上的桌面小部件。
  • 内容管理系统插件 - 与网络服务器或客户端相比,该流程的优势在于可以让您的应用使用单个 Developers Console 项目。这样便可为用户提供汇总报告和简化的安装过程。

服务帐户

该流程非常适合于对您帐户的 Google Analytics(分析)数据的自动/离线/定期访问。例如,为您的 Google Analytics(分析)数据创建实时信息中心,并与其他用户共享。

您需要按照以下步骤配置服务帐户,以使用 Google Analytics(分析):

要开始使用 Google Analytics(分析)API,您首先需要在 Google Developers Console 中创建或选择项目并启用该 API。访问该链接,了解相关流程以及如何自动激活 Google Analytics(分析)API。

此外,您还可以按照以下步骤在 Developers Console 中手动激活 Google Analytics(分析)API:

  1. 打开“凭据”页面

无论您采用哪种方式,最终都会到达凭据页面,并可以在此页面上创建项目凭据。

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

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

您的新公钥/私钥对已生成并下载到您的计算机;您可以将其用作该密钥的唯一副本。您负责安全存储该密钥。

问题排查

如果您在验证身份时遇到问题,并且收到 401403 状态代码,则可以执行以下几个步骤,来排查问题:

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

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

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

OAuth 1.0 Playground。该 Playground 与 OAuth 2.0 Playground 类似,但仅适用于旧版 OAuth。

授权无效

如果您在尝试使用刷新令牌时收到 invalid_grant 错误响应,导致该错误的原因可能如下:

  1. 您的服务器的时钟与 NTP 不同步。
  2. 刷新令牌数量超出上限。
    应用可以请求多个刷新令牌来访问一个 Google Analytics(分析)帐户。在某些情况下,这样做很有用,例如,当用户想要在多台机器上安装某个应用,并访问同一个 Google Analytics(分析)帐户时。这种情况下,需要两个刷新令牌,用于在不同机器上安装的应用。当刷新令牌的数量超出上限时,较早的令牌便会失效。如果应用试图使用失效的刷新令牌,系统将会返回 invalid_grant 错误响应。每个唯一的 OAuth 2.0 客户端和 Google Analytics(分析)帐户对的刷新令牌数量上限为 25(注意,该限制可能会发生变化)。如果应用不断请求同一对客户端/帐户的刷新令牌,在第 26 个令牌发出之后,之前发出的第 1 个令牌将失效。第 27 个请求的刷新令牌会使之前发出的第 2 个令牌失效,依此类推。