Pub/Sub 通知

• 請務必完成 API 設定程式碼研究室，設定Google Cloud 專案並建立服務帳戶，以便呼叫 Cloud Channel API。

• 建議您使用測試合作夥伴銷售資訊主控台進行本程式碼研究室。

• 熟悉 Pub/Sub 概念。

總覽

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

這項功能特別適合以下情況：

• 在自家系統中反映直接在 Partner Sales Console 中所做的變更 (例如支援團隊人員取消 Google Workspace 授權)。
• 偵測由轉售客戶觸發的重要事件。例如：
  • Google Workspace 客戶接受《服務條款》。
  • Google Workspace 客戶驗證網域。
  • Google Workspace 客戶在彈性授權中新增使用者。
  • Google Workspace 客戶轉移至其他服務。

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

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

2. 建立 Pub/Sub 主題。這個主題由 Channel Services 擁有，您將指定可建立訂閱項目的服務帳戶。

3. 建立 Pub/Sub 訂閱。這個訂閱項目可以使用 webhook (建議方法) 或提取推送。

如要訂閱推播，您必須代管 webhook，以便接收頻道服務發出的事件：

通知格式

以下是 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 並準備服務帳戶

如要執行本程式碼研究室，您需要符合以下條件：

• 專案中服務帳戶的電子郵件地址。這個地址的格式如下：[e-mail]。
• 經銷商網域超級管理員帳戶的存取權 (最好是測試版 Partner Sales Console)。
• 您的帳戶 ID。您可以在 Partner Sales Console 的「設定」中找到這項資訊。

如要準備服務帳戶，請按照下列步驟操作：

• 前往 Google Cloud 控制台的「API 資料庫」專區，並啟用 Pub/Sub API。
• 將 Pub/Sub IAM 角色授予服務帳戶。授予 roles/pubsub.editor (角色名稱 =「Pub/Sub Editor」) 就足以應付本程式碼研究室，但您可能會想在實際工作環境整合中使用更精細的權限。您可以在 Pub/Sub 存取權控管頁面上查看完整的 IAM 角色詳細資料。
• 如果您選擇改為套用自訂角色，則需要授予該角色 pubsub.subscriptions.create 權限，才能建立訂閱項目。

將這些角色和權限套用至帳戶後，可能會出現延遲。

注意： 如果服務帳戶沒有 IAM 角色，您會收到 403 錯誤。

步驟 2：為帳戶建立主題

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

1. 前往 accounts.register 說明文件，然後按一下「試試看」。
2. 在 account 欄位中輸入 accounts/ACCOUNT_ID，並將 ACCOUNT_ID 替換為您的帳戶 ID。
3. 按一下「Add request body parameters」，選取 serviceAccount，然後輸入服務帳戶的電子郵件地址。
4. 按一下「執行」，並確認以經銷商網域的超級管理員身分登入。

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

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

這是事件發布時會使用的 Pub/Sub 主題。

注意： 您需要在步驟 3b 中使用這個值。

步驟 3：訂閱主題

建立 Pub/Sub 主題後，您需要設定應用程式如何使用變更事件。您可以採用兩種方法：

• 推播訂閱：您提供 HTTP POST 回呼。Pub/Sub 會使用這項資訊，通知應用程式有新事件發生。
• 提取訂閱：應用程式會定期發出 HTTP 呼叫，取得排入佇列的變更。

在本程式碼研究室中，我們會使用 Push，並將所有事件傳送至 Cloud Run 函式，以便在 Cloud Logging 中記錄。

步驟 3a：建立 Cloud Run 函式

在這個步驟中，我們將建立 Cloud Run 函式，用於記錄收到的訊息。

1. 前往Google Cloud 控制台的「Cloud Run functions」專區。您可能需要啟用 Cloud Run functions API。
2. 按一下「Create Function」。
3. 在「設定」畫面中：
   1. 變更函式名稱。您也可以選擇其他區域。
   2. 在 HTTP 觸發事件中，將「Authentication」(驗證) 變更為「Allow unauthenticated invocations」(允許未經驗證的叫用)，然後按一下「Save」(儲存)。
   3. 請記下「觸發網址」。在下一步中將會用到。
   4. 點按「Next」。

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 Run 函式部署期間，您可以繼續進行後續步驟。

步驟 3b：建立訂閱項目

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

您可以使用程式碼，透過服務帳戶憑證呼叫 Pub/Sub API 來執行這項操作。請勿冒用經銷商網域的超級管理員身分，因為在呼叫 Cloud Channel API 時，必須使用此身分。

在本程式碼研究室中，您將在 Cloud Shell 上使用 gcloud CLI 工具。

1. 按一下 Google Cloud console頂端的「啟用 Cloud Shell」。

2. 殼層準備就緒後，請執行下列指令。將 SERVICE_ACCOUNT 的值替換為服務帳戶的電子郵件地址、TOPIC 替換為步驟 2 中建立的主題，以及 PUSH_ENDPOINT 替換為步驟 3a 中建立的 Cloud Run 函式觸發事件網址：

   SERVICE_ACCOUNT=[e-mail]
   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 訂閱項目部分。

產生一些資料

完成上述步驟後，您就可以開始接收資料。

最簡單的方法是在 Partner Sales Console 中建立客戶，然後提供產品。如果您已完成端對端 Workspace 佈建程式碼研究室，可以執行範例程式碼，為 Google Workspace 建立客戶。

前往 Google Cloud 控制台的函式，然後開啟「Logs」分頁。以下是您應該會看到的範例。

注意： 在少數情況下，Pub/Sub 訂閱可能需要幾分鐘的時間，才能開始接收主題的事件。

清除所用資源

• 刪除 Cloud Run 函式
• 刪除訂閱

當主題沒有任何訂閱者時，系統會自動清除該主題。

後續步驟

本程式碼研究室將逐步說明 Channel Services 如何運用 Pub/Sub，讓您以回應式方式建構大規模的整合作業。

事件參考資料

如要查看 Channel Services 產生的事件清單，請參閱 RPC 參考資料。

API 參考資料

本程式碼研究室會使用 Google Cloud 控制台，但您可以透過程式碼執行這些步驟。方法如下：

• 使用 accounts.register 建立主題。
• 使用 Pub/Sub API 的 subscriptions.create 建立 Pub/Sub 訂閱項目。
• 如要瞭解可在整合中使用的其他端點，請參閱 accounts.listSubscribers 和 accounts.unregister。

Pub/Sub 保證與最佳做法

我們無法保證事件發生與通知發送之間的延遲時間。同樣地，我們無法保證通知的順序。最後，訊息可能會重複傳送。

推送端點最佳做法：

• 由於訊息可能會延遲、傳送順序不正確或重複傳送，因此端點應為冪等，並使用 customers.get 和 entitlements.get。

• 雖然推送的預設 Pub/Sub 逾時時間為 10 秒 (可透過 Pub/Sub 訂閱的 ackDeadline 增加)，但建議您使用以訊息為基礎的架構，並盡可能讓端點快速回應。

• 如果端點無法運作或傳回 5xx 錯誤，Pub/Sub 會重試。如要進一步瞭解如何透過推播接收訊息，請參閱 Pub/Sub 說明文件。

如果您偏好使用提取，請參閱 Pub/Sub 說明文件，瞭解如何透過提取接收訊息。

事件篩選

由於 Channel Services 的通知包含 attributes，您可以使用 Pub/Sub 篩選器建立特定的 Pub/Sub 訂閱項目，以便建立精細的訂閱項目。

舉例來說，您可以使用 attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" 篩選條件，追蹤所有 Google Workspace 座位變更。