總覽
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，以擷取目前狀態。