建立 Google Workspace 訂閱方案

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

本頁麵包含下列建立 Google Workspace 訂閱項目的步驟：

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

必要條件

Apps Script

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

    gcloud init
    

• 訂閱項目的目標資源：
  • 如要訂閱 Google Chat 聊天室，已驗證的使用者所屬的 Chat 聊天室為成員。使用者必須是透過 Google Workspace 或 Google 帳戶加入聊天室成員 (不支援透過 Google 群組加入聊天室的使用者)。
  • 如要訂閱 Google Meet 會議聊天室，這類會議中已驗證的使用者為擁有者。如要建立聊天室，請參閱 Google Meet 說明文件中的「使用會議空間」。
  • 如要訂閱 Google Meet 使用者，請使用 Cloud Identity API 的 user ID
• 已啟用計費功能的 Google Cloud 專案。如要訂閱 Chat 應用程式，您還必須在 Cloud 專案中啟用 Chat API，並設定「應用程式名稱」、「顯示圖片」和「說明」欄位。詳情請參閱「建構 Google Chat 應用程式」。
• 必須透過為應用程式設定 OAuth 同意畫面的使用者進行驗證。設定同意畫面時，您必須指定支援訂閱項目各事件類型的範圍。如要設定同意畫面並找出所需範圍，請參閱「選擇範圍」一文。

• Apps Script 專案：
  • 請使用 Google Cloud 專案，而非 Apps Script 自動建立的預設專案。
  • 針對新增用來設定 OAuth 同意畫面的所有範圍，您也必須將範圍新增至 Apps Script 專案的 appsscript.json 檔案中。 例如：

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

  • 啟用 Google Workspace Events 進階服務。

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 Chat 聊天室，已驗證的使用者所屬的 Chat 聊天室為成員。使用者必須是透過 Google Workspace 或 Google 帳戶加入聊天室成員 (不支援透過 Google 群組加入聊天室的使用者)。
  • 如要訂閱 Google Meet 會議聊天室，這類會議中已驗證的使用者為擁有者。如要建立聊天室，請參閱 Google Meet 說明文件中的「使用會議空間」。
  • 如要訂閱 Google Meet 使用者，請使用 Cloud Identity API 的 user ID
• 已啟用計費功能的 Google Cloud 專案。如要訂閱 Chat 應用程式，您還必須在 Cloud 專案中啟用 Chat API，並設定「應用程式名稱」、「顯示圖片」和「說明」欄位。詳情請參閱「建構 Google Chat 應用程式」。
• 必須透過為應用程式設定 OAuth 同意畫面的使用者進行驗證。設定同意畫面時，您必須指定支援訂閱項目各事件類型的範圍。如要設定同意畫面並找出所需範圍，請參閱「選擇範圍」一文。

設定環境

下一節說明如何在建立 Google Workspace 訂閱項目之前設定環境。

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

使用 Google API 前，請先在 Google Cloud 專案中啟用這些 API。您可以在單一 Google Cloud 專案中啟用一或多個 API。

Google Cloud 控制台

在 Google Cloud 控制台中，開啟應用程式的 Google Cloud 專案，並啟用 Google WorkspaceEvents 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 Event API 和 Google Cloud Pub/Sub API：

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

建立 OAuth 用戶端 ID 憑證

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

如需建立 OAuth 用戶端 ID 的具體操作說明，請選擇「應用程式類型」：

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

網頁應用程式

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

   前往「憑證」頁面

2. 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
3. 依序點選「應用程式類型」>「網頁應用程式」。
4. 在「名稱」欄位中，輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 新增與應用程式相關的已授權 URI：
   • 用戶端應用程式 (JavaScript)：在「已授權的 JavaScript 來源」下方，按一下「新增 URI」。然後輸入瀏覽器要求要使用的 URI。此屬性可識別應用程式可從哪些網域向 OAuth 2.0 伺服器傳送 API 要求。
   • 伺服器端應用程式 (Java、Python 等)：在「授權的重新導向 URI」下方，按一下「新增 URI」。然後輸入端點 URI，OAuth 2.0 伺服器可將回應傳送至這個 URI。
6. 點選「建立」。畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID 與用戶端密鑰。

   記下「用戶端 ID」。用戶端密鑰不可用於網頁應用程式。

7. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

Android

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

   前往「憑證」頁面

2. 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
3. 依序按一下「應用程式類型」>「Android」。
4. 在「名稱」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 在「Package name」欄位中，輸入 AndroidManifest.xml 檔案中的套件名稱。
6. 在「SHA-1 憑證指紋」欄位中，輸入產生的 SHA-1 憑證指紋。
7. 點選「建立」。畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID。
8. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

iOS

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

   前往「憑證」頁面

2. 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
3. 依序點選「應用程式類型」>「iOS」。
4. 在「名稱」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 在「Bundle ID」欄位中，輸入應用程式 Info.plist 檔案中列出的軟體包 ID。
6. 選用：如果應用程式出現在 Apple App Store，請輸入 App Store ID。
7. 選用：在「團隊 ID」欄位中，輸入 Apple 產生並指派給團隊的不重複 10 個字元字串。
8. 點選「建立」。畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID 與用戶端密鑰。
9. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

Chrome 應用程式

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

   前往「憑證」頁面

2. 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
3. 依序按一下「應用程式類型」>「Chrome 應用程式」。
4. 在「名稱」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 在「應用程式 ID」欄位中，輸入應用程式專屬的 32 個字元 ID 字串。您可以在應用程式的 Chrome 線上應用程式商店網址和 Chrome 線上應用程式商店開發人員資訊主頁中找到這個 ID 值。
6. 點選「建立」。畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID 與用戶端密鑰。
7. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

電腦版應用程式

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

   前往「憑證」頁面

2. 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
3. 依序按一下「應用程式類型」>「電腦版應用程式」。
4. 在「名稱」欄位中，輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 點選「建立」。畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID 與用戶端密鑰。
6. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

電視和受限制的輸入裝置

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

   前往「憑證」頁面

2. 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
3. 依序點選「應用程式類型」>「電視和有限輸入裝置」。
4. 在「名稱」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 點選「建立」。畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID 與用戶端密鑰。
6. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

通用 Windows 平台 (UWP)

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

   前往「憑證」頁面

2. 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
3. 依序點選「應用程式類型」>「通用 Windows 平台 (UWP)」。
4. 在「名稱」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 在「商店 ID」欄位中，輸入應用程式不重複的 Microsoft Store ID 值，長度為 12 個字元。您可以在應用程式的 Microsoft Store 網址和合作夥伴中心找到這個 ID。
6. 點選「建立」。畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID 與用戶端密鑰。
7. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

下載用戶端密鑰 JSON 檔案

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

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

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

   前往「憑證」頁面

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

3. 按一下「Download JSON」。

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

建立及訂閱 Pub/Sub 主題

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

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

如何建立及訂閱 Pub/Sub 主題：

Google Cloud 控制台

1. 前往 Google Cloud 控制台中的「Pub/Sub」頁面：

   前往 Google Cloud Pub/Sub

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

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

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

3. 點選「建立」。完整主題名稱的格式為 projects/PROJECT_ID/topics/TOPIC_ID。您會在後續步驟中使用這個名稱。

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

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

gcloud

1. 請在 Cloud 專案中執行下列指令，建立主題：

   gcloud pubsub topics create TOPIC_ID
   

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

   輸出內容會顯示完整的主題名稱，格式為 projects/PROJECT_ID/topics/TOPIC_ID。請記下名稱，並確認 PROJECT_ID 的值是應用程式的 Cloud 專案 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 的事件，請使用 [e-mail]。
     • 如要接收 Meet 的事件，請使用 [e-mail]。

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

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

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME
   

   更改下列內容：

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

建立 Google Workspace 訂閱方案

在本節中，您會使用 Google Workspace Event API 的 subscriptions.create() 方法建立 Subscription 資源，請指定下列欄位：

• targetResource：用來監控事件 (例如 Chat 聊天室) 的 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 資源，並採用其完整的資源名稱格式。舉例來說，如要訂閱 Google Chat 聊天室 (聊天室 ID 為 AAAABBBB)，請使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：您想在目標資源中訂閱的一或多個事件類型。請採用 'google.workspace.chat.message.v1.created' 等字串陣列的格式。
   • TOPIC_NAME：您在 Cloud 專案中建立的 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('client_secrets.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 資源，並採用其完整的資源名稱格式。舉例來說，如要訂閱 Google Chat 聊天室 (聊天室 ID 為 AAAABBBB)，請使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：您想在目標資源中訂閱的一或多個事件類型。請採用 'google.workspace.chat.message.v1.created' 等字串陣列的格式。
   • TOPIC_NAME：您在 Cloud 專案中建立的 Pub/Sub 主題全名。採用 projects/PROJECT_ID/topics/TOPIC_ID 格式。

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

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

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

   python3 create_subscription.py
   

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

測試 Google Workspace 訂閱方案

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

如要測試 Google Workspace 訂閱方案：

Google Cloud 控制台

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

2. 前往 Google Cloud 控制台中的「Pub/Sub」頁面：

   前往 Pub/Sub

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

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

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

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

6. 按一下「提取」。事件可能需要幾分鐘的時間才能產生 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/SUBSCRIPTION_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 專案，您必須將指令碼發布為網頁應用程式。

相關主題

• 教學課程：使用 Python 和 Google Meet REST API 觀察會議活動
• 訂閱
• 列出訂閱項目
• 更新或續訂訂閱項目
• 修正錯誤並重新啟用訂閱項目
• 刪除訂閱項目