配置用户控制的账号 - API 开发者指南

本文档将介绍与使用 Provisioning API 创建新的 Google Analytics（分析）账号相关的重要概念。

简介

Provisioning API 可用于大规模地创建新的 Google Analytics（分析）账户并为您的客户启用 Google Analytics（分析）。Provisioning API 专供符合条件的服务提供商和大型合作伙伴使用。请参阅 Provisioning API 概览以了解 Provisioning API。

开始之前

所有 Google Analytics（分析）API 的访问方法都基本相同。在开始使用 Provisioning API 之前，您应该：

  • 访问客户端库页面，查看与该 API 配合使用的编程语言客户端库的完整列表。
  • 参阅参考指南，熟悉该 API 的界面，并了解如何在没有客户端库的情况下访问数据。

每个客户端库提供单个分析服务对象来访问 Provisioning API。要创建服务对象，您通常需要完成以下步骤：

  1. 在 Google API 控制台中注册您的应用。
  2. 授权创建新的 Google Analytics（分析）账号。
  3. 创建 Google Analytics（分析）服务对象。

如果您尚未完成上述步骤，请停止操作，并阅读 Google Analytics（分析）API 入门教程。此教程将会向您逐一介绍构建 Google Analytics（分析）API 应用的初始步骤。完成这些步骤后，您将了解如何访问 Google Analytics（分析）API 以执行实际任务。

概览

在使用 Provisioning API 创建 Google Analytics（分析）账户时，需要考虑以下两个相互独立的流程：

  • 技术流程：以程序化方式为用户配置 Google Analytics（分析）账户的端到端流程
  • 用户流程：您需要从用户角度考虑的与账户创建流程相关的实现注意事项。

本文档将介绍每种流程的简略步骤和相关要求。

技术流程

要使用 Provisioning API 创建新的账户，并将其与 Google Analytics（分析）相集成，请按照以下简要步骤操作：

  1. 提示用户使用 OAuth 2.0 验证身份并授权应用/服务。
  2. 使用 Provisioning API 创建账户 Ticket。
  3. 引导用户接受 Google Analytics（分析）服务条款 (TOS) 并处理响应。
  4. （可选）配置账户和集成选择。

如果您成功完成以上步骤，则系统会为用户创建 Google Analytics（分析）账户，而您将获得该新账户的账户 ID、媒体资源 ID 和数据视图（配置文件）ID。

在介绍这些步骤时，本文将从每个步骤的完成要求、结果以及的技术流程说明三个方面入手。

1. 身份验证与授权

每个用户都需要授权您的应用并许可其代为配置 Google Analytics（分析）账户。我们建议使用 OAuth 2.0 Web Server 应用流程来执行此步骤。

完成此步骤需要：

此步骤的结果

完成 OAuth 2.0 流程后，用户就会授权您的应用代为配置账户，您将获得用户的访问令牌。

关于令牌和范围的注意事项：

  • 在账户创建完成后，如果您希望就用户账户配置或报告数据发出其他请求，则您可在此步骤中授权其他范围。例如，readonly 或 edit 范围。
  • 访问令牌的生命周期是有限的。如果您的应用需要访问的 Google Analytics（分析）API 超出了单个访问令牌的生命周期，则您还可以通过设置 access_type=offline 来请求刷新令牌。每个用户的刷新令牌都应保存在安全的长期存储空间中，因为您的应用可通过该令牌获取新的访问令牌。如需了解更多详情，请参阅离线访问功能。

此步骤的技术流程

您需要获得用户的访问令牌。根据 OAuth 2.0 Web Server 中所述的流程，将用户发送到 Google 帐号服务，然后在完成身份验证流程后将用户重定向回您的服务时处理响应。

构建供用户访问的 OAuth 2.0 网址

当用户点击了“开始使用”或“创建账户”按钮或链接后，该链接应指向 OAuth 2.0 流程的开端，以便要求用户授予配置权限。例如：

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
从 Google Accounts Service 处理响应

当用户决定向您的应用授予访问权限后，系统会将他们重定向到您构建的网址中指定的 redirect_uri，该网址中包含包含授权代码的查询参数。如果用户批准了请求，可以向 Google Accounts API 发出 POST 请求，从而使用授权代码响应将授权代码换成访问令牌。

保存刷新令牌（如果有）

访问令牌将在下一步中使用，只需临时存储即可。如果您还请求了用户的刷新令牌，则应将其安全地保存起来以供长期使用。刷新令牌长期有效，可用于获取新的访问令牌。

2. 使用 Provisioning API 创建账户 Ticket

获得获授权用户的访问令牌后，您就可以使用它向 Provisioning API 发出请求，以便为该用户创建帐号 Ticket。帐号 Ticket 是为用户创建帐号的第一步。

完成此步骤需要：

身份验证和授权部分提及的获授权用户的访问令牌以及以下配置详细信息：

  • 重定向 URI
    • 定义了用户在访问 Google Analytics（分析）服务条款 (TOS) 页面后将被重定向到的位置。可以不同于 OAuth 2.0 授权流程中指定的重定向 URI。
    • 重定向 URI 参数的值必须与在 Google Developers Console 中注册的某个值完全匹配（包括 http 或 https 架构、大小写、结尾反斜杠“/”）。
  • 帐号字段
    • 帐号必须指定 name 属性。
  • “网络媒体资源”相关字段
    • 必须为该属性指定 name 属性。
    • websiteUrl 为必需属性。
  • 个人资料字段
    • 配置文件必须指定 name 属性。
    • 可以选择提供 timezone。默认值为 America/Los_Angeles。

在创建账户 Ticket 时，仅可以设置上述基本字段。在账户创建完毕后，可以使用 Management API 更改媒体资源或数据视图（配置文件）的其他配置。

请参阅账户、媒体资源和数据视图（配置文件）的 API 参考，了解关于上述字段的详细信息。

此步骤的结果

向 Provisioning API 成功发出请求后，您将获得用户的账户 Ticket，不过只能在短期内使用。账户 Ticket ID 将在最后一步中使用，用于提示用户接受服务条款 (TOS) 并激活账户。用户接受 TOS 后，账户方可使用。

此步骤的技术流程

使用在身份验证和授权过程中获得的用户访问令牌，向 Provisioning API 发出 HTTP POST 请求。

请求 Provisioning API 创建账户 Ticket

请参阅 Provisioning API 参考文档中的 createAccountTicket 方法，详细了解如何发出请求。

来自 Provisioning API 的响应

如果请求成功，Provisioning API 会返回 200 响应。响应正文包含只能在短期内使用的账户 Ticket。账户 Ticket 由 Ticket ID 和新账户树状视图的详细信息组成。

请参阅 Provisioning API 参考文档中的 Account Ticket resource，详细了解该响应。

错误响应同样需要由应用处理。

3. 用户接受 Google Analytics（分析）服务条款 (TOS)

获得用户的账户 Ticket ID 后，即可将其用于 TOS 请求，以便提示用户接受 Google Analytics（分析）服务条款。

完成此步骤需要：

获授权用户的账户 Ticket ID。

此步骤的结果

使用账户 Ticket ID 成功完成 TOS 流程后，系统就会创建账户、媒体资源和数据视图（配置文件）。用户的账号将会生效。来自 TOS 页面的响应会包含账号 ID、媒体资源 ID 和数据视图（配置文件）ID。

此步骤的技术流程

使用账户 Ticket ID 将用户重定向至 Google Analytics（分析）TOS 页面（用户可在此接受 TOS），然后您需要处理来自 API 的响应。

构建供用户访问的 TOS 网址

将用户重定向至 TOS 页面，并将账户 Ticket ID 添加到网址中：

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
处理 TOS 响应

用户在 TOS 页面执行操作后，将被重定向回创建帐号工单期间指定的 redirectUri。来自 TOS 页面的响应将被添加到查询字符串中。

成功的响应将返回关于新创建的帐号结构以及原始 accountTicketId 的数据：

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

例如，如果应用的 TOS 处理程序位于 http://www.your-app.com/gaTOS，则应在创建帐号工单时将其设置为 redirectUri。当帐号 Ticket 有效且用户已接受 TOS 时，应用的 TOS 处理程序应预见并正确处理包含 accountId、webPropertyId、profileId 和 accountTicketId 查询参数的 HTTP GET 请求。

未成功的响应将包含错误响应。

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

您的 TOS 处理程序还应正确处理包含 error 查询参数的 HTTP GET 请求，该参数表示出现了问题。该查询参数的值可用于采取进一步措施，也可以用于向用户显示消息。

  • error=user_cancel - 用户未接受服务条款。
  • error=max_accounts_reached - 用户已达到 Google Analytics（分析）账号数量上限。
  • error=backend_error - 常规错误。服务器返回的错误不属于以上类型。

4. （可选）集成选择

如果您已按照上述技术流程执行操作，那么您将为用户创建一个账户并获得相应的账户 ID、媒体资源 ID 和数据视图（配置文件）ID。如果您还请求了其他权限，您还将获得用户的刷新令牌。以上数据可用于：

用户流程

本部分将从用户角度出发，介绍与账户创建流程步骤相关的实现注意事项

该流程从用户通过以下两种选项之一启用媒体资源分析开始：

  1. 创建 Google Analytics（分析）账户
  2. 使用现有 Google Analytics（分析）账户。（注意：本文档未涉及此流程。请参阅 Management API，详细了解如何访问用户的 Google Analytics（分析）配置数据。）

在创建新的 Google Analytics（分析）账户时，您必须将某些信息（例如账户名称、媒体资源名称等）随配置请求一起发送。在用户点击“创建账户”后发起用户流程的主要选项有 3 种，请根据您所掌握的用户信息以及您希望向用户展示的首选流程来做出选择。

获得授权后索要账户详细信息

在这种情况下，用户需要在流程中提供账户详细信息。该流程如下所示：

  1. 用户被重定向至 Google Account Service 以执行 OAuth 2.0 流程。 如果用户没有 Google 账户或尚未登录，则系统会要求用户创建账户或进行登录。
  2. 系统将提示用户授权应用“创建 Google Analytics（分析）账户”。
  3. 用户接受应用的权限请求。
  4. 用户被重定向至服务提供商。请注意，即使用户拒绝授权，仍将被重定向至服务提供商。
  5. 系统会向用户显示一个表单，以此收集待创建账户的详细信息（例如，账户名称、媒体资源名称、配置文件名称、时区、网站网址等）。
  6. 用户填写并提交该表单后，系统会将用户重定向至 Google 或显示 Google Analytics（分析）服务条款 (TOS)。
  7. 用户接受 TOS。
  8. 用户被重定向至服务提供商，并将收到一些成功消息。此类消息表明用户已成功创建 Google Analytics（分析）账户，并提供有关该账户及其访问方式的详细信息。请注意，即使用户未接受 TOS，仍会被重定向至服务提供商。

获得授权前索要账户详细信息

在这种情况下，用户需要先行提供待创建账户的配置详细信息。该流程如下所示

  1. 服务提供商网站会向用户显示一个表单，以此收集待创建账户的详细信息（例如，账户名称、媒体资源名称、配置文件名称、时区、网站网址）。
  2. 用户填写该表单并点击提交后，将被重定向至 Google Account Service，以便执行 OAuth 2.0 流程。如果用户没有 Google 账户或尚未登录，则系统会要求用户创建账户或进行登录。
  3. 系统将提示用户授权应用“创建 Google Analytics（分析）账户”。
  4. 用户接受应用权限请求。
  5. 用户被重定向至服务提供商。
  6. 系统将用户重定向至 Google 或显示 Google Analytics（分析）服务条款。
  7. 用户接受 TOS。
  8. 用户被重定向至服务提供商，并将收到一些成功消息。此类消息表明用户已成功创建 Google Analytics（分析）账户，并提供有关该账户及其访问方式的详细信息。

预填写账户详细信息或跳过填写表单步骤

在已获得用户账户信息（如网站网址、网站名称、时区等）的情况下，可采用以下步骤来简化上述两种选择：

  • 预填写表单并允许用户进行更改。
  • 跳过填写表单步骤，使用现有信息自动创建账户。