Provisioning API - 授权

本指南介绍应用如何向对 Provisioning 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.provision 创建新的 Google Analytics(分析)帐户及其默认媒体资源和数据视图

要通过 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 个令牌失效,依此类推。