Pub/Sub 通知

• 请务必完成 API 设置 Codelab，以设置 Google Cloud 项目并创建服务账号以调用 Cloud Channel API。

• 我们建议您在此 Codelab 中使用测试 Partner Sales Console。

• 熟悉 Pub/Sub 概念。

概览

Cloud Channel API 使用 Pub/Sub 传送有关各种客户和使用权事件的通知。

这对以下各方特别有用：

• 在您自己的系统中反映直接在 Partner Sales Console 中进行的更改（例如，支持团队的某位成员取消了 Google Workspace 使用权）。
• 检测由转售客户触发的重大事件。例如：
  • Google Workspace 客户接受服务条款。
  • 正在验证域名的 Google Workspace 客户。
  • Google Workspace 客户使用弹性方案添加用户。
  • 转移 Google Workspace 客户。

设置 Pub/Sub 包括以下三个步骤：

1. 启用 Pub/Sub API 并准备好您的服务账号。

2. 创建 Pub/Sub 主题。此主题归 Channel Services 所有，您需要指定一个可以创建订阅的服务账号。

3. 创建 Pub/Sub 订阅。此订阅可以使用 webhook（首选方法）进行推送或拉取。

对于推送订阅，您将托管一个 webhook，用于接收渠道服务发出的事件：

通知格式

以下是 Pub/Sub 通知示例。消息数据以 base64 编码的 JSON 字符串的形式传输。

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

这是经过解码的同一消息数据：

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

第 1 步：启用 Pub/Sub API 并准备好服务账号

如需运行此 Codelab，您需要具备以下条件：

• 您项目中服务账号的电子邮件地址。此地址将如下所示：[e-mail]。
• 对转销商网域超级用户账号的访问权限（最好是您的测试 Partner Sales Console）。
• 您的账号 ID。您可以在 Partner Sales Console 的“设置”中找到此信息。

如需准备服务账号，请执行以下操作：

• 前往 Google Cloud 控制台中的 API 库部分，然后启用 Pub/Sub API。
• 向您的服务账号授予项目的 Pub/Sub IAM 角色。 授予 roles/pubsub.editor（角色名称 =“Pub/Sub Editor”）的权限对本 Codelab 来说已经足够，但您可能需要在生产环境集成中使用更精细的权限。您可以在 Pub/Sub 访问权限控制页面上找到完整的 IAM 角色详细信息。
• 如果您选择改为应用自定义角色，则需要向该角色授予创建订阅的 pubsub.subscriptions.create 权限。

将这些角色和权限应用到您的账号后，可能需要等待一段时间。

注意 ：如果服务账号没有 IAM 角色，您会收到 403 错误。

第 2 步：为您的账号创建主题

如需创建 Pub/Sub 主题，您需要使用 accounts.register 方法。此方法将服务账号电子邮件地址作为参数。只有通过此方法授权的服务账号才能订阅您的新主题。

1. 前往 accounts.register 文档，然后点击试用。
2. 在 account 字段中，输入 accounts/ACCOUNT_ID，将 ACCOUNT_ID 替换为您的账号 ID。
3. 点击 Add request body parameters（添加请求正文参数），选择 serviceAccount，然后输入您的服务账号电子邮件地址。
4. 点击执行，并确保以转销商网域的超级用户身份登录。

您应该会收到 200 响应，如下所示：

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

这是事件将发布到的 Pub/Sub 主题。

注意 ：第 3b 步需要此值。

第 3 步：订阅主题

创建 Pub/Sub 主题后，您需要设置应用使用更改事件的方式。您可以采用以下两种方法：

• 推送订阅：您提供 HTTP POST 回调。Pub/Sub 将使用此 ID 通知您的应用有新事件。
• 拉取订阅：您的应用会定期发出 HTTP 调用，以获取队列中的更改。

在本 Codelab 中，我们将使用推送，并将所有事件发送到将在 Cloud Logging 中记录日志的 Cloud Run 函数。

第 3a 步：创建 Cloud Run 函数

在此步骤中，我们将创建一个 Cloud Run 函数，用于记录收到的消息。

1. 前往 Google Cloud 控制台的 Cloud Run functions 部分。您可能需要启用 Cloud Run functions API。
2. 点击 创建函数。
3. 在配置界面中：
   1. 更改函数的名称。（可选）选择其他区域。
   2. 在 HTTP 触发器中，将身份验证更改为允许未通过身份验证的调用，然后点击保存。
   3. 记下触发器网址。下一步操作将会用到该地址。
   4. 点击下一步。

4. 在代码屏幕中：

   1. 选择任何 Node.js 运行时
   2. 将入口点更改为 log
   3. 在 index.js 文件中，将示例代码替换为：

   exports.log = (req, res) => {
     if (req.body && req.body.message) {
       console.log(req.body);
       const message = req.body.message;
       // data is base64-encoded JSON
       const data = new Buffer.from(message.data, 'base64').toString();
       console.log(data);
     }
     res.status(200).send('OK');
   };
   

在 Cloud Run 函数部署期间，您可以继续执行下一步。

第 3b 步：创建订阅

只有已注册“渠道服务”主题的服务账号（请参阅第 2 步）才能创建订阅。

您可以使用代码通过服务账号凭据调用 Pub/Sub API 来实现此目的。请确保您不会冒充转销商网域的超级用户（调用 Cloud Channel API 时需要）。

在本 Codelab 中，您将在 Cloud Shell 中使用 gcloud CLI 工具。

1. 点击 Google Cloud 控制台顶部的激活 Cloud Shell。

2. 当 shell 准备就绪后，运行以下命令。将 SERVICE_ACCOUNT 的值替换为您的服务账号的电子邮件地址，将 TOPIC 替换为在第 2 步中创建的主题，并将 PUSH_ENDPOINT 替换为在第 3a 步中创建的 Cloud Run 函数的触发器网址：

   SERVICE_ACCOUNT=[e-mail]
   TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
   PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
   

3. 在 Shell 中激活服务账号：

   gcloud iam service-accounts keys create sa-keys.json \
       --iam-account=$SERVICE_ACCOUNT
   gcloud auth activate-service-account --key-file=sa-keys.json
   

4. 创建订阅：

   gcloud pubsub subscriptions create channel-pubsub-test \
       --topic=$TOPIC \
       --push-endpoint=$PUSH_ENDPOINT
   

您可以前往 Pub/Sub 订阅部分，确认订阅是否已设置完毕。

生成一些数据

完成上述步骤后，您就可以接收数据了。

最简单的方法是在 Partner Sales Console 中创建客户并预配商品。如果您已完成端到端 Workspace 预配 Codelab，则可以通过运行示例代码创建 Google Workspace 客户。

在 Google Cloud 控制台中，前往您的函数，然后打开日志标签页。您应该会看到以下内容。

注意 ：在极少数情况下，Pub/Sub 订阅可能需要几分钟才能开始从主题接收事件。

清理

• 删除 Cloud Run functions 函数
• 删除订阅

当主题没有任何剩余订阅者时，系统会自动清理该主题。

后续步骤

在此 Codelab 中，您将了解 Channel Services 如何利用 Pub/Sub 让您以响应式方式大规模构建集成。

事件参考文档

如需查看 Channel Services 生成的事件列表，请参阅 RPC 参考文档。

API 参考文档

本 Codelab 使用 Google Cloud 控制台，但您也可以通过编程方式执行这些步骤。为此，请执行以下操作：

• 使用 accounts.register 创建主题。
• 使用 Pub/Sub API 的 subscriptions.create 创建 Pub/Sub 订阅。
• 如需了解您可以在集成中使用的其他端点，请参阅 accounts.listSubscribers 和 accounts.unregister。

Pub/Sub 保证和最佳实践

我们无法保证事件与其通知之间的延迟时间。同样，我们无法保证通知的顺序。最后，消息可能会多次传送。

推送端点最佳实践：

• 由于消息可能会延迟、发送无序或多次发送，因此您的端点应具有幂等性，并使用 customers.get 和 entitlements.get

• 虽然 Pub/Sub 的默认推送超时时间为 10 秒（可通过 Pub/Sub 订阅的 ackDeadline 进行延长），但建议您使用基于消息的架构，并让端点尽快响应。

• 如果您的端点处于关闭状态或返回 5xx 错误，Pub/Sub 会重试。如需详细了解如何通过推送接收消息，请参阅 Pub/Sub 文档。

如果您更喜欢使用拉取，可以在 Pub/Sub 文档中了解如何通过拉取接收消息。

事件过滤

由于渠道服务的通知包含 attributes，因此您可以通过使用 Pub/Sub 过滤创建特定的 Pub/Sub 订阅，从而创建精细的订阅。

例如，使用 attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" 过滤可让您跟踪所有 Google Workspace 座位数更改。