推播通知

總覽

經銷商 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 來提取目前狀態。