推送通知

本页介绍了如何将推送通知与 Reseller API 搭配使用。

概览

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

前提条件

为您的 Google Cloud 项目启用 Pub/Sub API。
在云项目中向您的服务账号授予 Pub/Sub IAM 角色。建议授予 roles/pubsub.editor 角色，但您也可以使用更具体的 Pub/Sub 权限。

创建主题

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

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 dependent 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 商务 Starter 版和保险柜，升级到包含保险柜的商务 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 来拉取当前状态。