Pub/Sub 通知

透過集合功能整理內容 你可以依據偏好儲存及分類內容。
  • 請務必完成 API 設定程式碼研究室,以設定 Google Cloud 專案並建立服務帳戶,以呼叫 Cloud Channel API。

  • 建議您使用這個 Test Channel Services Console 來使用這個程式碼研究室。

  • 熟悉 Pub/Sub 概念

總覽

Cloud Channel API 使用 Pub/Sub 傳送有關各種客戶和授權事件的通知。

這特別有用:

  • 直接反映您系統中 Channel Services Console 所做的變更,例如支援團隊支援團隊取消 Google 工作區授權。
  • 偵測經銷商客戶觸發的重要事件。例如:
    • 接受《服務條款》的 Google 工作區客戶。
    • Google 工作區客戶正在驗證網域。
    • 擁有彈性授權的 Google 工作區客戶。
    • Google 工作區客戶轉移給客戶。

設定 Pub/Sub 包含下列三個步驟:

  1. 啟用 Pub/Sub API 並準備您的服務帳戶。

  2. 建立 Pub/Sub 主題。這個主題由 Channel Services 提供,且您可指定可用來建立訂閱項目的服務帳戶。

  3. 建立 Pub/Sub 訂閱項目。您可以使用 Webhook (建議使用) 或 pull推送這個訂閱項目。

push 訂閱中,您將託管一個 Webhook,以接收 Channel Services 發送的事件:

Channel Services 的推播通知

通知格式

以下是 Pub/Sub 通知範例。訊息資料會採用 base64 編碼的 JSON 字串格式。

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

以下是相同的資料資料進行解碼:

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

步驟 1:啟用 Pub/Sub API 並準備您的服務帳戶

如要執行這個程式碼研究室,您需要下列項目:

  • 專案服務帳戶的電子郵件地址。這個地址如下所示:service-account@project.iam.gserviceaccount.com。
  • 具備經銷商網域超級管理員帳戶的存取權 (建議使用 Test Channel Services Console)。
  • 您的帳戶 ID。您可以在 Channel Services Console 的「Settings」(設定) 中找到這項資訊。

如何準備您的服務帳戶:

  • 前往 Google Cloud Console 的「API Library」(API 資料庫) 區段,並啟用 Pub/Sub API。
  • 將專案的 Pub/Sub IAM 角色授予您的服務帳戶。 對這個程式碼研究室來說,roles/pubsub.editor 是不錯的選擇,但您可能需要在實際工作環境整合功能中使用更精細的權限。您可以在 Pub/Sub 存取權控管頁面找到完整參考資料。

步驟 2:為您的帳戶建立主題

如要建立 Pub/Sub 主題,您必須使用 accounts.register 方法。這個方法會將服務帳戶電子郵件當做參數。只有透過這個方法授權的服務帳戶可以訂閱您的新主題。

  1. 前往 accounts.register 說明文件,然後按一下 [Try it!]
  2. account 欄位中輸入 accounts/ACCOUNT_ID,並將 ACCOUNT_ID 替換成您的帳戶 ID。
  3. 按一下 [Add request body parameters] (新增要求主體參數),選取 serviceAccount,然後輸入您的服務帳戶電子郵件地址。
  4. 按一下 [Execute] (執行),請務必以經銷商網域的超級管理員身分登入。

您應該會收到類似以下的 200 回應:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

此為發布事件的 Pub/Sub 主題。

步驟 3:訂閱主題

建立 Pub/Sub 主題後,您必須設定應用程式使用變更事件的方式。您可以採用兩種方法:

  • 推送訂閱:您提供 HTTP POST 回呼。Pub/Sub 會使用這個 API 通知您的應用程式新事件。
  • 提取訂閱項目:您的應用程式會定期呼叫 HTTP 呼叫來取得佇列中的變更。

在這個程式碼研究室中,我們將使用 Push 並將所有事件傳送至 Cloud Logging 中的 Cloud 函式。

將 Channel Services 通知推送至 Cloud 函式

步驟 3a:建立 Cloud 函式

在這個步驟中,我們將建立 Cloud 函式以記錄接收的訊息。

  1. 前往 Google Cloud Console 的「Cloud Functions」區段。您可能需要啟用 Cloud Functions API。
  2. 按一下 [建立函式]
  3. 在「Configuration」(設定) 畫面中:
    1. 變更函式名稱。您也可以選擇其他地區。
    2. 在 HTTP 觸發條件中,將「Authentication」(驗證) 變更為 [Allow unauthenticated invocations] (允許未經驗證的叫用),然後按一下 [Save] (儲存)
    3. 記下「觸發條件網址」。在下一步中將會用到。
    4. 按一下 [下一步]。
  4. 在「Code」(程式碼) 畫面中:

    1. 挑選任何 Node.js 執行階段
    2. 將「Entry point」(進入點) 變更為 log
    3. index.js 檔案中,將範例程式碼替換為:
    exports.log = (req, res) => {
      if (req.body && req.body.message) {
        console.log(req.body);
        const message = req.body.message;
        // data is base64-encoded JSON
        const data = new Buffer.from(message.data, 'base64').toString();
        console.log(data);
      }
      res.status(200).send('OK');
    };
    

在 Cloud 函式部署期間,您可以繼續進行下一步。

步驟 3b:建立訂閱項目

只有已註冊 Channel Services 主題的服務帳戶 (請參閱步驟 2) 能建立訂閱項目。

您可以使用服務帳戶憑證呼叫 Pub/Sub API,透過程式碼進行更新。請勿驗證經銷商網域的超級管理員,因為呼叫 Cloud Channel API 需要這項權限。

為進行本程式碼研究室,您需要在 Cloud Shell 中使用 gcloud 工具。

  1. 按一下 Google Cloud Console 頂端的 [Activate Cloud Shell] (啟用 Cloud Shell)

  2. 殼層準備就緒後,請執行下列指令。將 SERVICE_ACCOUNT 的值改為您服務帳戶的電子郵件地址,將 TOPIC 建立於步驟 2 建立的主題,並將 PUSH_ENDPOINT 替換為 Cloud 的觸發條件網址步驟 3a 建立的函式:

    SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
    TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
    PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
    
  3. 在殼層中啟用服務帳戶:

    gcloud iam service-accounts keys create sa-keys.json \
        --iam-account=$SERVICE_ACCOUNT
    gcloud auth activate-service-account --key-file=sa-keys.json
    
  4. 建立訂閱項目:

    gcloud pubsub subscriptions create channel-pubsub-test \
        --topic=$TOPIC \
        --push-endpoint=$PUSH_ENDPOINT
    

您可以前往 Pub/Sub 訂閱項目區段,確認訂閱項目已完成。

產生一些資料

完成上述步驟後,您就可以接收資料了。

最簡單的方式是在 Channel Services Console 中建立客戶,並佈建產品。如果您已完成端對端工作區佈建程式碼研究室,您可以執行程式碼範例來建立 Google 工作區客戶。

在 Google Cloud Console 中前往函式,然後開啟 [Logs] (記錄) 分頁標籤。以下是應看到的範例。

Pub/Sub 事件的記錄範例

清除

  • 刪除 Cloud 函式
  • 刪除訂閱項目

如果主題沒有任何剩餘訂閱者,系統就會自動清除主題。

後續步驟

本程式碼研究室可引導您逐步瞭解 Channel Services 如何使用 Pub/Sub,以被動方式大規模進行整合作業。

事件參考資料

如需 Channel Services 產生的事件清單,請參閱 RPC 參考資料

API 參考資料

這個程式碼研究室會使用 Google Cloud Console,但您可以透過程式執行這些步驟。方法如下:

Pub/Sub 保證和最佳做法

我們無法保證事件及其通知的延遲時間。同樣地,我們也無法保證通知順序。最後,訊息可能會重複傳送。

推送端點最佳做法:

  • 由於訊息可能會延遲、傳送失敗或多次傳送,您的端點應為 等,且使用 customers.getentitlements.get

  • 雖然推送的預設 Pub/Sub 逾時值為 10 秒 (透過 Pub/Sub 訂閱項目的 ackDeadline 可以增加),但我們仍建議您使用訊息型架構,端點盡快回應。

  • 如果您的端點已中斷,或傳回 5xx 錯誤,Pub/Sub 將重試。如需進一步瞭解透過 Pub/Sub 接收訊息的方式,請參閱這篇說明文章

如果您偏好使用 pull,則可參閱 Pub/Sub 說明文件中的透過提取方式接收訊息的相關資訊。

事件篩選

由於 Channel Services 的通知包含 attributes,您可以透過 Pub/Sub 篩選建立特定的 Pub/Sub 訂閱項目,建立精細訂閱項目。

舉例來說,使用 attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" 進行篩選,即可追蹤所有的 Google 工作區容量變更。