Tag Manager API 授权

本文档介绍了应用如何获得向 Tag Manager API 发出请求的授权。

向请求授权

用户要在任意 Google 网站上查看其帐号信息,必须先使用 Google 帐号登录。同样,当用户首次访问您的应用时,他们需要授权您的应用访问他们的数据。

您的应用向 Tag Manager API 发送的每个请求都必须包括授权令牌。Google 也可通过此令牌来识别您的应用。

关于授权协议

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

使用 OAuth 2.0 向请求授权

向 Tag Manager API 发出的所有请求都必须由经过身份验证的用户授权。

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

  1. 创建应用时,您需要使用 Google API 控制台注册应用。然后,Google 会提供您稍后需要用到的信息,例如客户端 ID 和客户端密钥。
  2. 在 Google API 控制台中启用 Tag Manager API(如果 API 控制台中未列出该 API,请跳过这一步)。
  3. 当您的应用需要访问用户数据时,它会请求 Google 提供特定作用域的访问权限。
  4. Google 会向相应用户显示同意屏幕,让用户授权您的应用请求他/她的某些数据。
  5. 待该用户批准后,Google 会为您的应用提供一个短时效访问令牌
  6. 您的应用会请求获取用户数据,并在请求中随附访问令牌。
  7. 如果 Google 确定您的请求及令牌有效,就会返回您所请求的数据。

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

以下是 Tag Manager API 的 OAuth 2.0 作用域信息:

作用域 含义
https://www.googleapis.com/auth/tagmanager.readonly 查看您的 Google 跟踪代码管理器容器。
https://www.googleapis.com/auth/tagmanager.edit.containers 管理您的 Google 跟踪代码管理器容器。
https://www.googleapis.com/auth/tagmanager.delete.containers 删除您的 Google 跟踪代码管理器容器。
https://www.googleapis.com/auth/tagmanager.edit.containerversions 管理您的 Google 跟踪代码管理器容器版本。
https://www.googleapis.com/auth/tagmanager.publish 发布您的 Google 跟踪代码管理器容器。
https://www.googleapis.com/auth/tagmanager.manage.users 管理用户对您的 Google 跟踪代码管理器数据的使用权限。
https://www.googleapis.com/auth/tagmanager.manage.accounts 管理您的 Google 跟踪代码管理器帐号。

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

开始使用

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

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

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

您的新公钥/私钥对已生成并下载到您的计算机;该密钥仅此一份,您应负责妥善存储。

常见的 OAuth 2.0 流程

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

网络服务器

此流程适用于自动/离线/定期访问用户的 Google 跟踪代码管理器帐号。

示例:
  • 从服务器自动更新跟踪代码管理器信息。

客户端

如果用户直接与应用互动,以通过浏览器访问其 Google 跟踪代码管理器帐号,那么此流程是理想选择。此流程对服务器端功能不再有要求,不过不能再自动/离线/定期生成报告。

示例:
  • 基于浏览器的自定义配置工具。

安装的应用

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

示例:
  • PC 或 Mac 上的桌面微件。
  • 内容管理系统的插件。与网络服务器或客户端相比,此流程的优势在于可以让您的应用使用单个 API 控制台项目。这样便可以为用户提供更简单的安装过程。

服务帐号

此流程适用于自动/离线/定期访问您自己的 Google 跟踪代码管理器帐号。例如,构建可监控您自己的 Google 跟踪代码管理器帐号的自定义工具,并与其他用户共享。

问题排查

如果您的 access_token 已过期,或者您对特定 API 调用使用了错误的作用域,则会在响应中收到 401 状态代码。

如果已获授权的用户无权访问 Google 跟踪代码管理器帐号或容器,您会在响应中收到 403 状态代码。请务必将权限授予适当的用户,并确保他们已获得访问跟踪代码管理器帐号或容器的权限

OAuth 2.0 Playground

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

授权无效

如果您在尝试使用刷新令牌时收到 invalid_grant 错误响应,则该错误可能是由以下一项或两项原因导致的:

  1. 您的服务器的时钟与 NTP 不同步。
  2. 刷新令牌数超出了上限。
    应用可以请求多个刷新令牌来访问单个 Google 跟踪代码管理器帐号。例如,当用户想要在多台机器上安装某个应用,并访问同一个 Google 跟踪代码管理器帐号时,这种方法非常有用。这种情况下,需要两个刷新令牌,用于在不同机器上安装的应用。当刷新令牌的数量超出上限时,较早的令牌便会失效。如果应用试图使用失效的刷新令牌,系统将会返回 invalid_grant 错误响应。每个唯一客户端 ID/帐号对最多可以有 25 个刷新令牌(请注意,此上限随时可能更改)。如果应用不断请求同一个客户端 ID/帐号对的刷新令牌,则在第 26 个令牌发出之后,发出的第 1 个刷新令牌将失效。第 27 个请求的刷新令牌会使发出的第 2 个令牌失效,依此类推。