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 主题。此主题归渠道服务所有 并指定一个可创建订阅的服务账号。

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。您可以在合作伙伴销售控制台的“设置”中找到此信息。

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

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

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

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

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

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

1. 前往 accounts.register 文档并点击 Try it!。
2. 在 account 字段中，输入 accounts/ACCOUNT_ID，将 ACCOUNT_ID 替换为您的账号 ID。
3. 点击添加请求正文参数，选择 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. 前往 Cloud Run 函数部分 Google Cloud 控制台。您可能需要启用 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 函数
• 删除订阅

如果主题中没有任何内容，系统会自动清除主题 剩余订阅者。

后续步骤

此 Codelab 带您了解了渠道服务如何利用 Pub/Sub 可让您以被动方式构建集成， 。

事件参考文档

请参阅 RPC 参考文档 查看渠道服务生成的事件列表。

API 参考文档

此 Codelab 使用 Google Cloud 控制台，但 以编程方式完成操作为此，请执行以下操作：

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

Pub/Sub 保证和最佳实践

我们无法保证事件与通知之间的延迟时间。同样，我们无法保证通知的顺序。最后，在 Google Cloud 中 。

推送端点最佳实践：

• 由于邮件可能会延迟、不按顺序发送或发送多次，因此您的 端点应具有幂等性，并使用 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 座位数更改。