此页面由 Cloud Translation API 翻译。

推送通知

概览

Reseller API 使用 Pub/Sub API 传送有关不同 Google Workspace 订阅事件的推送通知。例如，您可以设置推送通知，以便在客户的订阅状态发生变化时收到通知。

前提条件

为您的 Google Cloud 项目启用 Pub/Sub API。
向 Cloud 项目中的服务账号授予 Pub/Sub IAM 角色。授予 roles/pubsub.editor 角色是一个不错的折衷方案（简单且范围不太广），但您可能需要使用更具体的 Pub/Sub 权限。

创建主题

如需创建主题，您需要使用 resellernotify.register 方法向 Reseller API 注册。resellernotify.register 方法将服务账号电子邮件地址作为参数。只有通过此方法获得授权的服务账号才能订阅您新创建的主题。

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

成功的响应会返回 HTTP 200 状态代码和包含您的 Pub/Sub 主题名称的 JSON 响应。

以下是一个示例响应：

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

如需向其他服务账号授权使用您的主题，您可以再次调用 resellernotify.register。

撤消服务账号的访问权限

Reseller API 还支持使用 resellernotify.unregister 端点取消注册服务账号：

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

订阅主题

创建 Pub/Sub 主题后，您需要设置应用使用更改事件的方式。选择以下一个选项：

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

以下是订阅主题的请求示例：

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

替换以下内容：

PROJECT：您的 Google Cloud 项目。
SUBSCRIPTION_NAME：订阅的标识名称。
TOPIC_NAME：您之前创建的 Pub/Sub 主题。
PUSH_NOTIFICATION_ENDPOINT：您的推送通知处理程序端点。

成功的响应会返回 HTTP 200 状态代码。以下是一个示例响应：

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

通知格式

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

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

以下是解码后的示例 message.data 对象：

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

事件类型

以下列表包含所有可能的事件类型：

NEW_SUBSCRIPTION_CREATED：创建了新订阅。
SUBSCRIPTION_TRIAL_ENDED：订阅的试用期已结束。
PRICE_PLAN_SWITCHED：客户从弹性方案转换为包年套餐。如果客户在续订过程中从承诺型方案转换为弹性方案，系统不会触发此事件。
COMMITMENT_CHANGED：包年承诺增加或减少。
SUBSCRIPTION_RENEWED：包年订阅已续订。
SUBSCRIPTION_SUSPENDED：订阅已暂停。请参阅 subscription_suspension_reasons 字段。
SUBSCRIPTION_SUSPENSION_REVOKED：撤消了之前暂停的订阅。
SUBSCRIPTION_CANCELLED：订阅已取消。请参阅 subscription_cancellation_reason 字段。也可用于检测转移。
SUBSCRIPTION_CONVERTED：订阅已转换。此事件的一些示例情况如下：
- 将直接订阅转换为转销商订阅。
- 将付费订阅转换为宽限期优惠。
- 将在线订阅转换为线下订阅。
SUBSCRIPTION_UPGRADE：订阅 SKU 已升级。例如，订阅从 Google Workspace 商务新手版升级到了商务标准版。
SUBSCRIPTION_DOWNGRADE：订阅 SKU 已降级。例如，订阅从 Google Workspace 商务标准版降级为商务新手版。
LICENSE_ASSIGNMENT_CHANGED：向用户分配或从用户撤消许可。您可以使用此事件以响应方式跟踪弹性订阅的座位数变化。

订阅取消原因

当 event_type 为 SUBSCRIPTION_CANCELLED 时，系统会填充订阅取消原因。可能的取消原因如下：

TRANSFERRED_OUT：客户已改用直接结算或其他转销商。
PURCHASE_OF_SUBSUMING_SKU：客户已升级到会覆盖其他 SKU 的 SKU。例如，如果订阅了 Google Workspace 商务入门版和 Google 保险柜的客户升级到 Google Workspace 商务 Plus 版，则保险柜订阅会被包含在 Google Workspace 商务 Plus 版中。
RESELLER_INITIATED：转销商取消了订阅。
OTHER：订阅因上述原因以外的原因而取消。

订阅中止原因

当 event_type 为 SUBSCRIPTION_SUSPENDED 时，系统会填充订阅中止原因。以下是账号中止的可能原因：

PENDING_TOS_ACCEPTANCE：客户尚未登录并接受《Google Workspace 转售服务条款》。
RENEWAL_WITH_TYPE_CANCEL：客户的合同到期，其服务在到期后被取消。
RESELLER_INITIATED：转销商手动暂停了订阅。
TRIAL_ENDED：客户的试用期已过，但未选择非试用方案。
OTHER：客户因 Google 内部原因（例如滥用行为）而被中止。

Pub/Sub 限制

我们无法保证推送通知的顺序。消息可能会多次传送，在极端情况下，可能根本不会传送。我们建议对所有更改的订阅使用 reseller.subscriptions.get 来拉取当前状态。