推播通知

總覽

Reseller API 會使用 Pub/Sub API 傳送有關不同 Google Workspace 訂閱事件的推播通知。舉例來說，您可以設定推播通知，以便在客戶的訂閱狀態變更時收到通知。

必要條件

  • 為 Google Cloud 專案啟用 Pub/Sub API。
  • 將 Pub/Sub IAM 角色授予 Cloud 專案中的服務帳戶。授予 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_type 為 SUBSCRIPTION_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，以便擷取目前狀態。