本文档介绍了应用如何获得向跟踪代码管理器 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 个令牌失效，依此类推。