此页面由 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，以拉取当前状态。