推播通知

本頁說明如何搭配使用 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 狀態碼和 JSON 回應，其中包含 Pub/Sub 主題名稱。

回應範例：

{
  "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 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 升級至 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 擷取異動訂閱項目的目前狀態。