推播通知

總覽

Reseller API 會使用 Pub/Sub API 傳送推送訊息 關於不同 Google Workspace 的通知 訂閱事件。例如，您可以設定 通知，以便在客戶訂閱狀態 變更。

必要條件

  • 啟用 Pub/Sub API 管理 Google Cloud 專案所需的資源
  • 將 Pub/Sub 身分與存取權管理角色授予服務帳戶： Cloud 專案授予 roles/pubsub.editor 角色具有良好效用 (簡單明瞭，不會過於廣泛) 但建議你使用 Pub/Sub 權限。

建立主題

如要建立主題，請先透過 Reseller API 註冊 方法是使用 resellernotify.register 方法。 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 的用途 此回呼通知應用程式有新事件。
  • 提取訂閱項目：應用程式會定期向 可取得所有排入佇列的變更
，瞭解如何調查及移除這項存取權。

以下是訂閱主題的範例：

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 標準。

  • 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，以便提取 目前狀態