推播通知

總覽

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 Business Starter 升級至 Business Standard。

  • SUBSCRIPTION_DOWNGRADE：訂閱 SKU 已降級。舉例來說，訂閱方案從 Google Workspace Business Standard 降級至 Business Starter。

  • LICENSE_ASSIGNMENT_CHANGED：授權已指派給使用者或從使用者撤銷。您可以使用這項事件，主動追蹤彈性訂閱方案的座位數變更。

取消訂閱的原因

取消訂閱原因會在 event_typeSUBSCRIPTION_CANCELLED時填入。可能的原因如下：

  • TRANSFERRED_OUT：客戶已轉移至直接計費或另一位經銷商。
  • PURCHASE_OF_SUBSUMING_SKU：客戶已升級至會覆寫其他 SKU 的 SKU。舉例來說，如果客戶原本訂閱 Google Workspace Business Starter 和 Google 保管箱，升級至 Google Workspace Business Plus 後，系統會自動取消保管箱訂閱方案，因為 Google Workspace Business 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，以擷取目前狀態。