Provisioning 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 流程后，用户就会授权您的应用代为配置帐户，您将获得用户的访问令牌。

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

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

此步骤的技术流程

您需要获得用户的访问令牌。按照 OAuth 2.0 Web Server 中规定的流程，将用户发送到 Google Accounts Service，并在其完成身份验证流程、被重定向至您的服务后处理响应。

构建供用户访问的 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 参考中的帐户 Ticket 资源，了解该响应的详细信息。

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

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://www.google.com/analytics/web/?provisioningSignup=false#management/TermsOfService//?
  api.accountTicketId={account_ticket_id}
处理 TOS 响应

用户在 TOS 页面执行操作后，将被重定向至创建帐户 Ticket 过程中指定的 redirectUri。来自 TOS 页面的响应将被添加到查询字符串中。

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

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

例如，如果您的应用的 TOS 处理程序位于 http://www.your-app.com/gaTOS，则该网址应在创建帐户 Ticket 过程中设置为 redirectUri。您的应用的 TOS 处理程序应接收并正确处理 HTTP GET 请求。在帐户 Ticket 有效且用户已接受 TOS 的情况下，该请求会包含 accountId、webPropertyId、profileId 以及 accountTicketId 查询参数。

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

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（分析）帐户，并提供有关该帐户及其访问方式的详细信息。

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

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

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