建立 Google Workspace 訂閱方案

本頁面說明如何使用 Google Workspace Events API 建立 Google Workspace 資源訂閱項目。Google Workspace 訂閱項目可讓應用程式接收 Google Workspace 事件的相關資訊，這些事件代表 Google Workspace 資源的變更。如要瞭解 Google Workspace Events API 支援哪些資源和事件類型，請參閱「Google Workspace Events API 總覽」。

本頁面包含建立 Google Workspace 訂閱方案的下列步驟：

1. 設定環境。
2. 建立並訂閱 Google Cloud Pub/Sub 主題。請將這份文件做為接收 Google Workspace 事件的端點。
3. 在 Subscription 資源上呼叫 Google Workspace Events API 的 create 方法。
4. 測試 Google Workspace 訂閱項目，確認 Pub/Sub 主題會收到您訂閱的事件。
5. 您也可以視需要設定如何將事件推送至應用程式的端點，讓應用程式處理事件，並在必要時採取行動。

必要條件

Apps Script

• 如要使用本指南中的 Google Cloud CLI 指令，請按照下列步驟操作：
  1. 安裝 Google Cloud CLI。
  2. 如要 初始化 gcloud CLI，請執行下列程式碼：

    gcloud init
    

• Apps Script 專案：
  • 使用您的 Google Cloud 雲端專案，而非 Apps Script 自動建立的預設專案。
  • 對於您在設定 OAuth 同意畫面時新增的所有範圍，您也必須將這些範圍新增至 Apps Script 專案中的 appsscript.json 檔案。舉例來說，如果您指定 chat.messages 範圍，請新增下列內容：

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages"
  ]
      

  • 啟用 Google Workspace Events 進階服務。

• 已啟用計費功能的 Google Cloud 專案。如要訂閱 Chat，您還必須在雲端專案中啟用 Chat API，並設定「應用程式名稱」、「顯示圖片網址」和「說明」欄位。詳情請參閱「建構 Google Chat 應用程式」。
• 需要驗證，且訂閱項目中的每個事件類型都必須具備適當的授權範圍：
  • 通常需要使用者透過為應用程式設定的 OAuth 同意畫面進行驗證。設定同意畫面時，您必須指定範圍，支援訂閱項目的各個事件類型。如要設定同意畫面並找出必要範圍，請參閱「選擇範圍」。
  • 如要以 Chat 擴充應用程式的身分訂閱 Chat 事件，必須透過一次性管理員核准進行應用程式驗證。

Python

• Python 3.6 以上版本
• pip 套件管理工具
• 最新版 Python 專用 Google 用戶端程式庫。如要安裝或更新，請在指令列介面中執行下列指令：

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
    

• 如要使用本指南中的 Google Cloud CLI 指令，請按照下列步驟操作：
  1. 安裝 Google Cloud CLI。
  2. 如要 初始化 gcloud CLI，請執行下列程式碼：

    gcloud init
    

• 已啟用計費功能的 Google Cloud 專案。如要訂閱 Chat，您還必須在雲端專案中啟用 Chat API，並設定「應用程式名稱」、「顯示圖片網址」和「說明」欄位。詳情請參閱「建構 Google Chat 應用程式」。
• 需要驗證，且訂閱項目中的每個事件類型都必須具備適當的授權範圍：
  • 通常需要使用者透過為應用程式設定的 OAuth 同意畫面進行驗證。設定同意畫面時，您必須指定範圍，支援訂閱項目的各個事件類型。如要設定同意畫面並找出必要範圍，請參閱「選擇範圍」。
  • 如要以 Chat 擴充應用程式的身分訂閱 Chat 事件，必須透過一次性管理員核准進行應用程式驗證。

設定環境

下一節將說明如何在建立 Google Workspace 訂閱方案前設定環境。

啟用 Google Workspace Events API 和 Google Cloud Pub/Sub API

您必須先在 Google Cloud 專案中啟用 Google API，才能使用。您可以在單一 Google Cloud 專案中啟用一或多個 API。

Google Cloud 控制台

在 Google Cloud 控制台中，開啟應用程式的 Google Cloud 專案，並啟用 Google Workspace Events API 和 Pub/Sub API：

啟用 API

gcloud

1. 在目前使用的目錄中登入 Google 帳戶：

   gcloud auth login

2. 將專案設為應用程式的 Cloud 專案：

   gcloud config set project PROJECT_ID

   將 PROJECT_ID 替換為應用程式 Cloud 專案的專案 ID。

3. 啟用 Google Workspace Events API 和 Google Cloud Pub/Sub API：

   gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

建立 OAuth 用戶端 ID 憑證

注意： 如果您使用 Apps Script，可以略過這個步驟。

選擇應用程式類型，查看建立 OAuth 用戶端 ID 的具體操作說明：

注意： 如要執行本指南中的程式碼範例，請選擇「Desktop app」(電腦版應用程式)，然後按照操作說明進行。

網頁應用程式

1. 在 Google Cloud 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google Auth 平台) >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「Application type」(應用程式類型) >「Web application」(網頁應用程式)。
4. 在「Name」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台。
5. 新增與應用程式相關的授權 URI：
   • 用戶端應用程式 (JavaScript)：在「已授權的 JavaScript 來源」下方，按一下「新增 URI」。接著，輸入要用於瀏覽器要求的 URI。這會識別應用程式可從哪些網域傳送 API 要求至 OAuth 2.0 伺服器。
   • 伺服器端應用程式 (Java、Python 等)：在「已授權的重新導向 URI」下方，點選「新增 URI」。接著，輸入 OAuth 2.0 伺服器可傳送回應的端點 URI。
6. 選用：如果應用程式是代表使用者採取行動的 AI 代理，請選取「讓 AI 輔助代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
7. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

   請注意，用戶端密鑰不適用於網頁應用程式。

Android

1. 在 Google Cloud 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google Auth 平台) >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「Application type」(應用程式類型) >「Android」。
4. 在「Name」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台。
5. 在「Package name」欄位中，輸入 AndroidManifest.xml 檔案中的套件名稱。
6. 在「SHA-1 certificate fingerprint」欄位中，輸入產生的 SHA-1 憑證指紋。
7. 選用：如果應用程式是代表使用者採取行動的 AI 代理，請選取「讓 AI 輔助代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
8. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

iOS

1. 在 Google Cloud 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google Auth 平台) >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「Application type」(應用程式類型) >「iOS」。
4. 在「Name」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台。
5. 在「Bundle ID」欄位中，輸入應用程式 Info.plist 檔案中列出的軟體包 ID。
6. 選用：如果應用程式已在 Apple App Store 上架，請輸入 App Store ID。
7. 選用：在「團隊 ID」欄位中，輸入 Apple 產生並指派給團隊的 10 個字元專屬字串。
8. 選用：如果應用程式是代表使用者採取行動的 AI 代理，請選取「讓 AI 輔助代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
9. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

Chrome 應用程式

1. 在 Google Cloud 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google Auth 平台) >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「Application type」(應用程式類型) >「Chrome Extension」(Chrome 擴充功能)。
4. 在「Name」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台。
5. 在「項目 ID」欄位中，輸入應用程式專屬的 32 個字元 ID 字串。您可以在應用程式的 Chrome 線上應用程式商店網址和 Chrome 線上應用程式商店開發人員資訊主頁中找到這個 ID 值。
6. 選用：如果應用程式是代表使用者採取行動的 AI 代理，請選取「讓 AI 輔助代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
7. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

電腦版應用程式

1. 在 Google Cloud 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google Auth 平台) >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「Application type」(應用程式類型) >「Desktop app」(電腦版應用程式)。
4. 在「Name」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台。
5. 選用：如果應用程式是代表使用者採取行動的 AI 代理，請選取「讓 AI 輔助代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
6. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

電視和受限制的輸入裝置

1. 在 Google Cloud 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google Auth 平台) >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「應用程式類型」>「電視和輸入受限的裝置」。
4. 在「Name」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台。
5. 選用：如果應用程式是代表使用者採取行動的 AI 代理，請選取「讓 AI 輔助代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
6. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

通用 Windows 平台 (UWP)

1. 在 Google API 控制台中，依序前往「Menu」(選單) > >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「Application type」(應用程式類型) >「Universal Windows Platform (UWP)」(通用 Windows 平台 (UWP))。
4. 在「名稱」欄位中輸入憑證名稱。這個名稱只會顯示在 Google API 控制台中。
5. 在「商店 ID」欄位中，輸入應用程式專屬的 12 個字元 Microsoft Store ID 值。您可以在應用程式的 Microsoft Store 網址和合作夥伴中心找到這個 ID。
6. 選用：如果應用程式是代表使用者採取行動的 AI 代理，請選取「讓 AI 輔助代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
7. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

下載用戶端密鑰 JSON 檔案

注意： 如果您使用 Apps Script，可以略過這個步驟。

用戶端密鑰檔案是 OAuth 用戶端 ID 憑證的 JSON 表示法，應用程式在提供憑證時可參照該檔案。

1. 在 Google API 控制台中，依序點選「選單」圖示 >「API 和服務」>「憑證」。

   前往「憑證」

2. 在「OAuth 2.0 Client IDs」下方，按一下您建立的用戶端 ID。

3. 按一下「Download JSON」(下載 JSON)。

4. 將檔案儲存為 credentials.json。

建立及訂閱 Pub/Sub 主題

在本節中，您將建立 Pub/Sub 主題和主題訂閱項目。Pub/Sub 主題會做為通知端點，Google Workspace 訂閱項目會在此接收事件。

如要進一步瞭解如何建立及管理 Pub/Sub 主題，請參閱 Pub/Sub 說明文件。

注意： Google Workspace Events API 會使用排序金鑰，讓應用程式按照發布順序接收訊息。建議您避免使用訊息儲存政策。如果發布事件的主題含有這類政策，則發布作業可能會失敗，因為政策中的區域可能與事件來源不符。

如要建立及訂閱 Pub/Sub 主題，請按照下列步驟操作：

Google API 控制台

1. 在 Google API 控制台中，前往 Pub/Sub 頁面：

   前往 Google Cloud Pub/Sub

   確認已選取應用程式的雲端專案。

2. 按一下 「Create topic」(建立主題)，然後執行下列操作：

   1. 輸入主題名稱，例如 workspace-events-topic。
   2. 保留「Add a default subscription」(新增預設訂閱) 選項。Pub/Sub 會將這個預設訂閱項目命名為與主題名稱類似的名稱，例如 workspace-events-topic-sub。
   3. 選用：更新或設定主題的其他屬性。

3. 按一下「建立」，完整主題名稱的格式為 projects/PROJECT_ID/topics/TOPIC_ID。後續步驟會用到這個全名。

4. 授予將 Pub/Sub 訊息發布至主題的權限：

   1. 在主題頁面中，前往側邊面板，然後開啟「Permissions」(權限) 分頁。
   2. 按一下「新增主體」。
   3. 在「Add principals」(新增主體) 欄位中，新增 Google Workspace 應用程式的服務帳戶，以便將事件傳送至訂閱項目：
      1. 如要瞭解 Chat 事件，請參閱[e-mail]。
      2. 雲端硬碟事件： [e-mail]。
      3. 如果是 Meet 活動， [e-mail]。
   4. 在「指派角色」選單中，選取「Pub/Sub Publisher」。
   5. 按一下 [儲存]。主題權限可能需要幾分鐘才會更新。

gcloud

1. 在雲端專案中，執行下列指令來建立主題：

   gcloud pubsub topics create TOPIC_ID

   將 TOPIC_ID 替換為主題的專屬 ID，例如 workspace-events-topic。

   輸出內容會顯示完整主題名稱，格式為 projects/PROJECT_ID/topics/TOPIC_ID。記下名稱，並確認 PROJECT_ID 的值是應用程式的雲端專案 ID。在後續步驟中使用主題名稱，並在稍後建立 Google Workspace 訂閱項目。

2. 授予將訊息發布至主題的權限：

   gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

   更改下列內容：

   • TOPIC_NAME：完整主題名稱，也就是上一個步驟的輸出內容。格式為 projects/PROJECT_ID/topics/TOPIC_ID。

   • GOOGLE_WORKSPACE_APPLICATION：必須將事件傳送至訂閱項目的 Google Workspace 應用程式：

     • 如要接收 Chat 的事件，請使用下列其中一個服務帳戶：
       • 如果是 Chat 擴充應用程式 (建構為擴充 Chat 的 Google Workspace 外掛程式)，請使用 Chat API 設定頁面上的服務帳戶電子郵件地址。詳情請參閱「建構使用 Pub/Sub 的 Google Chat 應用程式」。
       • 如果 Chat 擴充應用程式不是外掛程式，請使用 [e-mail]。詳情請參閱「建構使用 Pub/Sub 的 Google Chat 應用程式」。
     • 如要接收來自雲端硬碟的事件，請使用 [e-mail]。
     • 如要接收 Meet 的事件，請使用 [e-mail]。

   主題權限可能需要幾分鐘才會更新。

3. 為主題建立 Pub/Sub 訂閱項目：

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

   更改下列內容：

   • SUBSCRIPTION_NAME：訂閱項目的名稱，例如 workspace-events-subscription。
   • TOPIC_NAME：您在上一個步驟中建立的主題名稱。

注意：如果您使用 VPC Service Controls，可能需要在 service perimeter 設定輸入規則，允許服務帳戶存取 Pub/Sub。詳情請參閱「輸入和輸出規則」。

訂閱 Google Workspace 資源

在本節中，您將訂閱要監控事件的 Google Workspace 資源。

選擇並找出目標資源

在 Google Workspace 訂閱中，「目標資源」是指您監控事件的 Google Workspace 資源。目標資源會以訂閱項目的 targetResource 欄位表示，並使用完整資源名稱格式。舉例來說，如果訂閱項目監控 Chat 聊天室 (spaces/AAAABBBBBBB)，targetResource 的值會是 //chat.googleapis.com/spaces/AAAABBBBBBB。

注意： 訂閱項目的到期時間上限，取決於事件酬載是否包含資源資料。如要進一步瞭解到期時間，請參閱「Google Workspace 事件的事件資料」。

找出 Chat 的目標資源

目標資源	格式	限制
空格鍵	//chat.googleapis.com/spaces/SPACE 其中 SPACE 是 Chat API space 資源 資源名稱中的 ID。您可以從聊天室網址或使用 spaces.list() 方法取得 ID。	授權訂閱項目的 Chat 使用者或 Chat 擴充應用程式，必須是透過 Google Workspace 或 Google 帳戶加入聊天室的成員。支援： 使用者驗證 應用程式驗證 (須經管理員核准)
使用者的所有聊天室	//chat.googleapis.com/spaces/-	訂閱項目只會接收使用者透過 Google Workspace 或 Google 帳戶加入的聊天室事件。僅支援使用者驗證。
User	//cloudidentity.googleapis.com/users/USER 其中 USER 是 Chat API user 資源 資源名稱中的 ID。詳情請參閱「識別及指定 Google Chat 使用者」。	訂閱項目只會接收與授權訂閱的使用者相關的事件。使用者無法代表其他使用者授權訂閱。僅支援使用者驗證。
客戶	//admin.googleapis.com/customers/CUSTOMER 其中 CUSTOMER 是客戶 ID。您也可以使用 my_customer 別名，代表 Chat 應用程式的客戶網域。	訂閱項目會接收客戶網域管理的所有聊天室和使用者事件。僅支援需要管理員核准的應用程式驗證。

找出雲端硬碟的目標資源

開發人員預覽版：加入 Google Workspace 開發人員預覽版計畫，即可搶先體驗特定功能。

目標資源	格式	限制 (如適用)
檔案	//drive.googleapis.com/files/FILE 其中 FILE 是 Drive API files 資源 資源名稱中的 ID。您可以從檔案網址或使用 files.list 方法取得 ID。	授權訂閱的使用者必須具備訂閱項目中檔案的權限，才能訂閱事件。
共用雲端硬碟	//drive.googleapis.com/drives/DRIVE 其中 DRIVE 是 Drive API drives 資源 資源名稱中的 ID。您可以從雲端硬碟的網址取得 ID，也可以使用 drives.list 方法。	訂閱項目只會接收共用雲端硬碟中項目的事件，且使用者必須透過 Google Workspace 帳戶或 Google 帳戶成為該雲端硬碟的成員。

找出 Meet 的目標資源

目標資源	格式	限制 (如適用)
會議空間	//meet.googleapis.com/spaces/SPACE 其中 SPACE 是 Meet REST API spaces 資源 資源名稱中的 ID。詳情請參閱「Meet 如何識別會議空間」。
使用者	//cloudidentity.googleapis.com/users/USER 其中 USER 是 Meet REST API participants 資源 signedinUser.user 欄位中的 ID。詳情請參閱「與參與者合作」。	訂閱項目會接收使用者為會議空間擁有者的所有會議空間事件。一般來說，會議空間擁有者也是與會議空間相關聯的 Google 日曆活動發起人。

建立 Google Workspace 訂閱方案

如要建立訂閱項目，請使用 Google Workspace Events API 的 subscriptions.create 方法建立 Subscription 資源。指定下列欄位：

• targetResource：您在上一節中識別的 Google Workspace，格式為完整資源名稱。
• eventTypes：陣列，包含一或多個您想接收的資源相關事件類型。舉例來說，如果應用程式只需要知道 Chat 聊天室中張貼的新訊息，則只需訂閱與建立訊息相關的事件。
• notificationEndpoint：Google Workspace 訂閱項目傳送事件的通知端點。使用您在上一節建立的 Pub/Sub 主題。
• payloadOptions：指定事件酬載中要包含多少資源資料的選項。這項設定會影響訂閱項目的到期時間。詳情請參閱「事件資料」。

如要建立 Google Workspace 訂閱方案，請按照下列步驟操作：

Apps Script

1. 在 Apps Script 專案中，建立名為 createSubscription 的新指令碼檔案，並加入下列程式碼：

   function createSubscription() {
     // The Google Workspace resource to monitor for events.
     const targetResource = 'TARGET_RESOURCE';
   
     // The types of events to receive.
     const eventTypes = [EVENT_TYPES];
   
     // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
     const pubsubTopic = 'TOPIC_NAME';
   
     // Whether to include resource data or not.
     const resourceData = RESOURCE_DATA;
   
     // Call the Workspace Events API using the advanced service.
     const response = WorkspaceEvents.Subscriptions.create({
       targetResource: targetResource,
       eventTypes: eventTypes,
       notificationEndpoint: {
         pubsubTopic: pubsubTopic,
       },
       payloadOptions: {
         includeResource: resourceData
       }
     });
     console.log(response);
   }
   

   更改下列內容：

   • TARGET_RESOURCE：您訂閱的 Google Workspace 資源，格式為完整資源名稱。舉例來說，如要訂閱 ID 為 AAAABBBB 的 Chat 聊天室，請使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：要在目標資源中訂閱的一或多個事件類型。格式為字串陣列，例如 'google.workspace.chat.message.v1.created'。
   • TOPIC_NAME：您在雲端專案中建立的 Pub/Sub 主題全名。格式為 projects/PROJECT_ID/topics/TOPIC_ID。

   • RESOURCE_DATA：布林值，指定訂閱項目是否在酬載中包含資源資料：

     • True：包含所有資源資料。如要限制包含的欄位，請新增 fieldMask 欄位，並為變更的資源指定至少一個欄位。只有訂閱 Chat 資源時，才能加入資源資料。
     • False：排除資源資料。

2. 如要建立 Google Workspace 訂閱項目，請在 Apps Script 專案中執行 createSubscription 函式。

Python

1. 在目前使用的目錄中，建立名為 create_subscription.py 的檔案，並加入下列程式碼：

   """Create subscription."""
   
   from google_auth_oauthlib.flow import InstalledAppFlow
   from googleapiclient.discovery import build
   
   # Specify required scopes.
   SCOPES = [SCOPES]
   
   # Authenticate with Google Workspace and get user authentication.
   flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
   CREDENTIALS = flow.run_local_server()
   
   # The Google Workspace resource to monitor for events.
   TARGET_RESOURCE = 'TARGET_RESOURCE'
   
   # The types of events to receive.
   EVENT_TYPES = [EVENT_TYPES]
   
   # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
   TOPIC = 'TOPIC_NAME'
   
   # Call the Workspace Events API using the service endpoint.
   service = build(
       'workspaceevents',
       'v1',
       credentials=CREDENTIALS,
   )
   
   BODY = {
       'target_resource': TARGET_RESOURCE,
       'event_types': EVENT_TYPES,
       'notification_endpoint': {'pubsub_topic': TOPIC},
       'payload_options': {'include_resource': RESOURCE_DATA},
   }
   response = service.subscriptions().create(body=BODY).execute()
   print(response)
   

   更改下列內容：

   • SCOPES：一或多個 OAuth 範圍，支援訂閱項目的各個事件類型。格式為字串陣列。如要列出多個範圍，請以半形逗號分隔。例如：'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'。
   • TARGET_RESOURCE：您訂閱的 Google Workspace 資源，格式為完整資源名稱。舉例來說，如要訂閱 ID 為 AAAABBBB 的 Chat 聊天室，請使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：要在目標資源中訂閱的一或多個事件類型。格式為字串陣列，例如 'google.workspace.chat.message.v1.created'。
   • TOPIC_NAME：您在雲端專案中建立的 Pub/Sub 主題全名。格式為 projects/PROJECT_ID/topics/TOPIC_ID。

   • RESOURCE_DATA：布林值，指定訂閱項目是否在酬載中包含資源資料：

     • True：包含所有資源資料。如要限制包含的欄位，請新增 fieldMask 欄位，並為變更的資源指定至少一個欄位。只有訂閱 Chat 資源時，才能加入資源資料。
     • False：排除資源資料。

2. 如要建立 Google Workspace 訂閱項目，請在終端機中執行下列指令：

   python3 create_subscription.py

Google Workspace Events API 會傳回已完成的長時間執行作業，其中包含您建立的 Subscription 資源執行個體。

測試 Google Workspace 訂閱方案

如要測試是否能收到 Google Workspace 事件，您可以觸發事件，並將訊息提取至 Pub/Sub 訂閱項目。

如要測試 Google Workspace 訂閱方案，請按照下列步驟操作：

Google API 控制台

1. 在 Google Workspace 訂閱方案的目標資源中，觸發一或多種類型的事件。舉例來說，如果您訂閱了 Chat 聊天室的新訊息，請在聊天室中張貼訊息。

2. 在 Google API 控制台中，前往 Pub/Sub 頁面：

   前往「Pub/Sub」頁面

   確認已選取應用程式的雲端專案。

3. 在「Pub/Sub」選單中，按一下「Subscriptions」(訂閱項目)。

4. 在表格中找出主題的 Pub/Sub 訂閱項目，然後按一下訂閱項目名稱。

5. 按一下「Messages」(訊息) 分頁標籤。

6. 按一下「Pull」(提取)。事件最多可能需要幾分鐘才能產生 Pub/Sub 訊息。

gcloud

1. 在 Google Workspace 訂閱方案的目標資源中，觸發一或多種類型的事件。舉例來說，如果您訂閱了 Chat 聊天室的新訊息，請在聊天室中張貼訊息。

2. 執行下列指令：

   gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

   更改下列內容：

   • PUBSUB_SUBSCRIPTION_NAME：Pub/Sub 訂閱項目的全名，格式為 projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID。
   • MESSAGE_COUNT：要提取的 Pub/Sub 訊息數量上限。

   事件可能需要幾分鐘才能產生 Pub/Sub 訊息。

每當您觸發 Google Workspace 事件，系統就會將包含該事件的訊息傳送至 Pub/Sub 訂閱項目。詳情請參閱「以 Google Cloud Pub/Sub 訊息形式接收事件」。

設定應用程式接收事件的方式

您建立的 Pub/Sub 訂閱項目是以提取為基礎。測試 Pub/Sub 訂閱項目後，您可以更新推送類型，變更應用程式接收事件的方式。舉例來說，您可以將 Pub/Sub 訂閱項目設為推送傳遞類型，讓應用程式直接在端點接收事件。

如要瞭解如何設定 Pub/Sub 訂閱項目，請參閱 Pub/Sub 說明文件。

注意： 您無法在 Pub/Sub 中將 Apps Script 專案設為推送傳遞端點。如要將 Pub/Sub 訊息推送至 Apps Script 專案，您必須將指令碼發布為網頁應用程式。

以 Google Chat 應用程式的身分訂閱 Chat 聊天室事件

Chat 擴充應用程式可以訂閱所屬聊天室的 Chat 事件。Chat 擴充應用程式無法訂閱使用者事件。

編寫呼叫 Google Workspace Events API 的指令碼

如要建立 Chat 聊天室事件訂閱項目，並使用應用程式驗證和管理員核准，請按照下列步驟操作：

1. 如有需要，請建構 Chat 擴充應用程式。

2. 訂閱 Chat 資源，但：

   1. 請以 Chat 擴充應用程式的身分進行驗證，並取得管理員的一次性核准，而非使用者驗證。

   2. 指定授權範圍，允許 Chat 擴充應用程式訂閱 Chat 事件。這些授權範圍一律以 chat.app 開頭，並包含下列項目：

      • https://www.googleapis.com/auth/chat.app.memberships：訂閱 Chat 聊天室成員事件。
      • https://www.googleapis.com/auth/chat.app.memberships.readonly：訂閱 Chat 聊天室成員事件。
      • https://www.googleapis.com/auth/chat.app.messages.readonly：訂閱 Chat 聊天室訊息和回應事件。
      • https://www.googleapis.com/auth/chat.app.spaces：訂閱 Chat 聊天室事件。
      • https://www.googleapis.com/auth/chat.app.spaces.readonly：訂閱 Chat 聊天室事件。

下列程式碼範例會訂閱指定 Chat 聊天室中的訊息事件：

Python

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  TOPIC = 'TOPIC_NAME'

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1',
      credentials=CREDENTIALS,
  )

  BODY = {
      'target_resource': TARGET_RESOURCE,
      'event_types': EVENT_TYPES,
      'notification_endpoint': {'pubsub_topic': TOPIC},
      'payload_options': {'include_resource': RESOURCE_DATA},
  }
  response = service.subscriptions().create(body=BODY).execute()
  print(response)

更改下列內容：

• SPACE_ID：聊天室名稱，可透過 Chat API 的 spaces.list 方法或聊天室網址取得。
• TOPIC_NAME：您在雲端專案中建立的 Pub/Sub 主題全名。格式為 projects/PROJECT_ID/topics/TOPIC_ID。

• RESOURCE_DATA：布林值，指定訂閱項目是否在酬載中包含資源資料：

  • True：包含所有資源資料。如要限制包含的欄位，請新增 fieldMask 欄位，並為變更的資源指定至少一個欄位。只有訂閱 Chat 資源時，才能加入資源資料。
  • False：排除資源資料。

以 Google Chat 應用程式的身分，訂閱 Google Workspace 組織中的所有 Chat 事件

Chat 擴充應用程式可透過客戶訂閱項目，監控整個 Google Workspace 組織的聊天室事件和使用者事件。

如要進一步瞭解如何傳送客戶訂閱項目的事件，包括在外部組織管理的聊天室中傳送事件，請參閱「客戶訂閱項目限制和傳送行為」。

需求條件和限制

• 驗證：以 Chat 應用程式身分驗證，並取得管理員一次性核准
• SKU：Google Workspace 組織必須至少有一個 Enterprise SKU 授權。
• 不重複性：Chat 擴充應用程式只能為特定 Google Workspace 機構建立一個客戶訂閱項目。一個 Google Workspace 機構最多可有五個客戶訂閱項目 (由不同 Chat 應用程式建立)。
• 範圍：視您要接收的事件類型而定，需要下列一或多個範圍：
  • https://www.googleapis.com/auth/chat.app.all.spaces.readonly：接收聊天室相關事件。
  • https://www.googleapis.com/auth/chat.app.all.memberships.readonly：接收成員資格相關事件。
  • https://www.googleapis.com/auth/chat.app.all.messages.readonly： 接收訊息和回應相關事件。
  • https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly：接收使用者已讀狀態的事件。

建立客戶訂閱

如要建立客戶訂閱項目，請呼叫 subscriptions.create 方法。

下列 Python 程式碼範例會建立客戶訂閱項目：

Python

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}

response = service.subscriptions().create(body=BODY).execute()
print(response)

更改下列內容：

• CUSTOMER_ID：客戶 ID。您也可以使用 my_customer 別名，代表 Chat 擴充應用程式的 Google Workspace 機構。
• TOPIC_NAME：您在雲端專案中建立的 Pub/Sub 主題全名。格式為 projects/PROJECT_ID/topics/TOPIC_ID。
• RESOURCE_DATA：布林值，指定訂閱項目是否在酬載中包含資源資料：
  • True：包含所有資源資料。如要限制包含的欄位，請新增 fieldMask 欄位，並為變更的資源指定至少一個欄位。只有訂閱 Chat 資源時，才能納入資源資料。
  • False：排除資源資料。

相關主題

• 教學課程：使用 Python 和 Meet REST API 觀測會議事件
• 訂閱方案
• 列出訂閱項目
• 更新或續訂方案
• 解決錯誤並重新啟用訂閱方案
• 刪除訂閱項目