建立 Google Workspace 訂閱方案

Apps Script

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

    gcloud init
    

• 啟用計費功能的 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 Cloud 專案。如要訂閱 Chat，您還必須在 Cloud 專案中啟用 Chat API，並設定 應用程式名稱、顯示圖片網址和說明欄位。詳情請參閱「建構 Google Chat 應用程式」。
• 需要使用者驗證，並透過為應用程式設定的 OAuth 同意畫面進行驗證。設定同意畫面時，您必須指定範圍，以便支援訂閱的每個事件類型。如要設定同意畫面並找出必要範圍，請參閱「選擇範圍」。

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

Google Cloud 控制台

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

   前往 Google Cloud Pub/Sub

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

2. 按一下 add_box「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. 授予發布至主題的權限：

   1. 在主題頁面上，前往側邊面板並開啟「Permissions」分頁標籤。
   2. 按一下「新增主體」。
   3. 在「新增主體」欄位中，新增服務帳戶，以便將事件傳送至訂閱項目的 Google Workspace 應用程式：
      1. 如為即時通訊事件，請使用 chat-api-push@system.gserviceaccount.com。
      2. 如為 Meet 活動，請meet-api-event-push@system.gserviceaccount.com。
   4. 在「Assign roles」(指派角色) 選單中，選取 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 的事件，請使用 chat-api-push@system.gserviceaccount.com。
     • 如要接收 Meet 的事件，請使用 meet-api-event-push@system.gserviceaccount.com。

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

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

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

   更改下列內容：

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

Apps Script

1. 在 Apps 指令碼專案中，建立名為 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 的 Google Chat 聊天室，請使用 //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 資源，格式為完整資源名稱。舉例來說，如要訂閱 ID 為 AAAABBBB 的 Google Chat 聊天室，請使用 //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 Cloud 控制台

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

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

   前往 Pub/Sub

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

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

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/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID。
   • MESSAGE_COUNT：您要擷取的 Pub/Sub 訊息數量上限。

   事件產生 Pub/Sub 訊息最多可能需要幾分鐘的時間。