總覽
經銷商 API 會使用 Pub/Sub API 傳送有關不同 Google Workspace 訂閱事件的推播通知。例如,您可以設定推播通知,在客戶的訂閱狀態變更時收到通知。
必要條件
- 為您的 Google Cloud 專案啟用 Pub/Sub API。
- 將 Pub/Sub 身分與存取權管理角色授予 Cloud 專案的服務帳戶。授予
roles/pubsub.editor
角色是很好的妥協,不會太廣泛,但也建議您使用更特定的 Pub/Sub 權限。
建立主題
如要建立主題,您需要使用 resellernotify.register
方法向經銷商 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
。
撤銷服務帳戶的存取權
經銷商 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_type
為 SUBSCRIPTION_CANCELLED
時,系統會填入訂閱取消原因。以下為取消可能的原因:
TRANSFERRED_OUT
:客戶已轉移至直接帳單或其他經銷商。PURCHASE_OF_SUBSUMING_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
來提取目前狀態。