整合您的支持服务

本页面描述了您打算提供支持作为产品的一部分时的支持工作流程。

您的系统需要与 Google 集成，以便您可以通过 Google 向购买您产品的客户提供支持。此集成基于 Google，向您提供以下各项：

密钥；您将在用户注册过程中使用该密钥来验证用户的支持资格。
API (Subscriptions API)；您可以向 API (Subscriptions API) 传递该密钥，以定期轮询用户支持资格的状态。

获取用户的支持 ID

支持集成侧重于外部帐号 ID，您的用户将其视为其支持 ID。

如需获取用户的支持 ID，请创建一个支持工作流，并在工作流的开头提供一个网址。Google 随后会在网址中向您发送外部帐号 ID。

如果您实现支持工作流，则必须接受将外部帐号 ID 作为网址的一部分。外部帐号 ID 可以是网址路径的一部分，也可以是查询参数值，如以下示例所示：

# External account ID in path
http://example.com/mysupportpage/{external_account_id}?someparameter=yes

# External account ID as a query parameter
http://example.com/mysupportpage?eid={external_account_id}&something_else

网址中的文本 {external_account_id} 被替换为外部帐号 ID。如果您在 Google Cloud Marketplace 中发布了多个产品，则可能需要添加查询参数以标识采用该网址的产品。

使用 Subscriptions API

在您获得用户的外部帐号 ID 后，您可以随时使用 Google 提供的 Subscriptions API 来验证其帐号的支持资格。通过检查称为订阅的实体来跟踪资格。

每个订阅都有一个唯一的订阅 ID 编号，并且系统会为 Cloud Marketplace 中列出的每个产品的每个客户创建唯一的订阅，因此您还可以按订阅 ID 查询订阅，以详细了解有关您产品的客户历史记录，例如开始日期、结束日期等等。

访问 Subscriptions API

Subscription API 为非公共 API，因此需要访问权限的开发者和项目必须列入许可名单。

如需列入许可名单并进行设置，请按照以下步骤执行操作：

向您的 Google Cloud Marketplace 合作伙伴工程师或 cloud-partner-onboarding@google.com 发送需要访问 API 文档的开发人员的电子邮件地址列表。这些电子邮件地址必须是这些开发人员用于登录 http://console.developers.google.com 的确切电子邮件地址。这些开发人员将添加到授权访问 Subscriptions API 的文档的组中。
将您的产品的项目 ID 发送给您的 Google Cloud Marketplace 合作伙伴工程师，并请求授予其调用 API 的权限。如果需要，可以将多个项目列入许可名单。
要启用 Cloud Billing API，请展开靠近 https://console.developers.google.com 左上角的菜单，单击 API 和服务，然后搜索并启用 Cloud Billing API。
创建与您的项目相关联的 OAuth2 服务帐号，并将此帐号的电子邮件地址发送给您的 Google Cloud Marketplace 合作伙伴工程师。此用户将列入许可名单以读取您的所有订阅，并且将用来向所有请求授权，但通过使用 OAuth 对话框请求客户权限来发出的那些请求除外。

由于 Subscriptions API 不是公共 API，因此默认情况下它不包含在 Python 客户端库中。如果您打算将 Python 客户端库与此 API 一起使用，则还必须与 Google 合作伙伴工程师联系，以获取访问发现文件的帮助。

在下面的示例初始化中，发现文件名设置为所下载发现文件的目标路径。

   # Load the local copy of the discovery document
   f = file(os.path.join(os.path.dirname(__file__),
         "cloudbilling-subscriptions_discovery.json"), "r")
   discovery = f.read()
   f.close()

   # Construct a service from the local documents
   service = build_from_document(discovery,
         base="https://www.googleapis.com/",
         http=http)

客户端库还支持使用客户凭据和 OAuth2 服务帐号进行 OAuth 身份验证。如需了解详情，请参阅 Python 版 Google API 客户端库中的 OAuth 2.0文档。

查询 Subscriptions API

要获得访问订阅数据的权限，您需要创建 OAuth2 服务帐号并告诉我们您打算用来授权 API 请求的帐号。Google 随后会授予该服务帐号访问权限，为所有客户读取您的订阅。如需了解详情，请参阅针对服务器对服务器应用使用 OAuth 2.0。

该 API 是一个用于返回订阅资源的只读 RESTful API，可用于获取以下信息：

name - 单个订阅资源的标识符。
externalAccountId - 单个结算帐号的标识符。
version - 每次修改记录时更新的版本号。这可用于轻松检测自上次读取以来的任何更改。
status - 以下值之一：
- 活动 - 订阅当前处于活动状态，客户应该能够获得您的支持。如果帐号在过去 30 天内具有活动虚拟机，则订阅被视为处于活动状态。
- COMPLETE - 订阅不再处于活动状态，因为客户在过去 30 天内没有与您的产品一起运行的任何活动虚拟机。
subscribedResources - 此订阅涵盖的资源列表。
startDate - 订阅开始的日期，以 RFC 3339 格式进行格式化的字符串。
endDate - 订阅结束的日期（如果已结束），以 RFC 3339 格式进行格式化的字符串。
最后检测信号时间戳的标签（含有键） - 该标签的值指示运行该产品的任何虚拟机的最后检测信号时间戳。例如： cloudmarketplacepartner.googleapis.com/last_heartbeat_us

当客户点击链接以从 Google Cloud Console 访问您的网站时，您需要发出以下请求来验证客户是否有权使用该链接：

列出外部帐号 ID 的订阅
查找产品的有效订阅
使用订阅 ID 获取订阅信息

如果客户是授权用户，则请求将成功。如果客户不是订阅的授权用户，则呼叫将返回未经授权错误代码 (HTTP 403)。

这将要求您在客户注册过程中使用标准 OAuth 请求流来请求客户读取其订阅数据的权限。

稍后刷新订阅数据的请求使用您先前创建的服务帐号。

客户支持注册流程

客户通过 Cloud Marketplace 或 Compute Engine API 部署您的产品后，Google Cloud Console 会显示指向您网站的链接，以完成支持注册。此链接将包含用于该帐号的外部帐号 ID。

您的网站应该允许客户创建帐号并提供他们所需的任何联系信息；Google 不会向您提供有关客户的任何个人身份信息。您有责任维护其帐号与 Google 提供的外部帐号 ID 之间的映射。