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 包含下列三個步驟：

啟用 Pub/Sub API 並準備您的服務帳戶。
建立 Pub/Sub 主題。這個主題由 Channel Services 提供，且您可指定可用來建立訂閱項目的服務帳戶。
建立 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 方法。這個方法會將服務帳戶電子郵件當做參數。只有透過這個方法授權的服務帳戶可以訂閱您的新主題。

前往 accounts.register 說明文件，然後按一下 [Try it!]。
在 account 欄位中輸入 accounts/ACCOUNT_ID，並將 ACCOUNT_ID 替換成您的帳戶 ID。
按一下 [Add request body parameters] (新增要求主體參數)，選取 serviceAccount，然後輸入您的服務帳戶電子郵件地址。
按一下 [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 函式以記錄接收的訊息。

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

在「Code」(程式碼) 畫面中：

挑選任何 Node.js 執行階段
將「Entry point」(進入點) 變更為 log
在 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 工具。

按一下 Google Cloud Console 頂端的 [Activate Cloud Shell] (啟用 Cloud Shell)。
殼層準備就緒後，請執行下列指令。將 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
```

在殼層中啟用服務帳戶：

gcloud iam service-accounts keys create sa-keys.json \
    --iam-account=$SERVICE_ACCOUNT
gcloud auth activate-service-account --key-file=sa-keys.json

建立訂閱項目：

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，但您可以透過程式執行這些步驟。方法如下：

使用 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 接收訊息的方式，請參閱這篇說明文章。

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

事件篩選

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

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