本文档介绍了应用如何获得向 Tag Manager API 发出请求的授权。
向请求授权
用户要在任意 Google 网站上查看其帐号信息,必须先使用 Google 帐号登录。同样,当用户首次访问您的应用时,他们需要授权您的应用访问他们的数据。
您的应用向 Tag Manager API 发送的每个请求都必须包括授权令牌。Google 也可通过此令牌来识别您的应用。
关于授权协议
您的应用必须使用 OAuth 2.0 来给请求授权。其他任何授权协议均不受支持。如果您的应用使用 Google+ 登录,则系统会代您执行授权方面的某些操作。
使用 OAuth 2.0 向请求授权
向 Tag Manager API 发出的所有请求都必须由经过身份验证的用户授权。
根据您所开发的应用的类型,OAuth 2.0 的具体授权流程可能会有所不同。下面是适用于所有应用类型的通用流程:
- 创建应用时,您需要使用 Google API 控制台注册应用。然后,Google 会提供您稍后需要用到的信息,例如客户端 ID 和客户端密钥。
- 在 Google API 控制台中启用 Tag Manager API(如果 API 控制台中未列出该 API,请跳过这一步)。
- 当您的应用需要访问用户数据时,它会请求 Google 提供特定作用域的访问权限。
- Google 会向相应用户显示同意屏幕,让用户授权您的应用请求他/她的某些数据。
- 待该用户批准后,Google 会为您的应用提供一个短时效访问令牌。
- 您的应用会请求获取用户数据,并在请求中随附访问令牌。
- 如果 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 以及创建凭据。
要开设新的服务帐号,请按以下步骤操作:
- 点击创建凭据 > 服务帐号密钥。
- 选择要下载哪种格式的服务帐号公钥/私钥文件,是标准的 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
错误响应,则该错误可能是由以下一项或两项原因导致的:
- 您的服务器的时钟与 NTP 不同步。
- 刷新令牌数超出了上限。
应用可以请求多个刷新令牌来访问单个 Google 跟踪代码管理器帐号。例如,当用户想要在多台机器上安装某个应用,并访问同一个 Google 跟踪代码管理器帐号时,这种方法非常有用。这种情况下,需要两个刷新令牌,用于在不同机器上安装的应用。当刷新令牌的数量超出上限时,较早的令牌便会失效。如果应用试图使用失效的刷新令牌,系统将会返回invalid_grant
错误响应。每个唯一客户端 ID/帐号对最多可以有 25 个刷新令牌(请注意,此上限随时可能更改)。如果应用不断请求同一个客户端 ID/帐号对的刷新令牌,则在第 26 个令牌发出之后,发出的第 1 个刷新令牌将失效。第 27 个请求的刷新令牌会使发出的第 2 个令牌失效,依此类推。