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