推送通知

概览

Reseller API 使用 Pub/Sub API 提供推送功能 关于不同 Google Workspace 的通知 订阅事件。例如，您可以设置推送 以便在客户对商品或服务产生兴趣时订阅状态 更改。

前提条件

  • 启用 Pub/Sub API Google Cloud 项目的配额。
  • 将 Pub/Sub IAM 角色授予您的 Cloud 项目中。授予 roles/pubsub.editor 角色是一个很好的折衷方案（简单且不过于宽泛）， 但您也可以使用更具体的提示 Pub/Sub 权限。

创建主题

如需创建主题，您需要注册 Reseller API 使用 resellernotify.register 方法。 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 使用 来通知您的应用有关新事件的信息。
  • 拉取订阅：您的应用会定期向 获取所有已加入队列的更改。
。

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

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 会替换另一个规则举例来说，如果 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 拉取 状态