建立 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. 呼叫 Google Workspace Event API 的 create() 方法 Subscription 資源。
  4. 測試 Google Workspace 訂閱項目,確保 Pub/Sub 主題會收到您訂閱的事件。
  5. (選用) 設定如何將事件推送至應用程式的端點, 應用程式可處理該事件,並在必要時採取行動。

必要條件

Apps Script

  • 如要使用本指南中的 Google Cloud CLI 指令,請按照下列指示操作:
    1. 安裝 Google Cloud CLI
    2. 收件者: 初始化 gcloud CLI,請執行下列指令:
    3.   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,請執行下列指令:
    3.   gcloud init
        
  • Google Cloud 專案 並啟用計費功能。如要訂閱 Chat,您必須: 您也會在 Cloud 專案中啟用 Chat API 設定「應用程式名稱」、「顯示圖片網址」和「說明」。 只要使用來自這些領域的 小型資料集訓練即可詳情請參閱 建構 Google Chat 應用程式
  • 需要透過已設定 OAuth 同意畫面進行使用者驗證 應用程式設定同意畫面時,您必須指定 支援每個事件類型。設定同意聲明 找出所需的範圍 選擇範圍

設定環境

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

啟用 Google Workspace 事件 API 和 Google Cloud Pub/Sub API

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

Google Cloud 控制台

在 Google Cloud 控制台中,開啟應用程式的 Google Cloud 專案,並啟用 Google Workspace 事件 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 憑證

選擇您的應用程式類型,瞭解建立 OAuth 用戶端 ID 的具體操作說明:

網頁應用程式

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

    前往「憑證」

  2. 依序點選「建立憑證」>「OAuth 用戶端 ID」
  3. 依序點選「應用程式類型」>「網頁應用程式」
  4. 在「名稱」欄位中輸入憑證的名稱。這個名稱只會顯示在 Google Cloud 控制台中。
  5. 新增與應用程式相關的已授權 URI:
    • 用戶端應用程式 (JavaScript):按一下「授權的 JavaScript 來源」下方的「新增 URI」。然後輸入瀏覽器要求的 URI。可識別應用程式可以從哪些網域傳送 API 要求至 OAuth 2.0 伺服器。
    • 伺服器端應用程式 (Java、Python 等):按一下「已授權的重新導向 URI」下方的「新增 URI」。然後輸入端點 URI,讓 OAuth 2.0 伺服器傳送回應。
  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」中] 欄位中輸入應用程式的唯一 12 個字元 Microsoft Store ID 值。您可以在應用程式的 Microsoft Store 網址和合作夥伴中心找到這個 ID。
  6. 按一下「建立」,系統隨即會顯示已建立 OAuth 用戶端的畫面,並顯示您的新用戶端 ID 和用戶端密鑰。
  7. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」之下。

下載用戶端密鑰 JSON 檔案

用戶端密鑰檔案是 OAuth 用戶端 ID 的 JSON 表示法 。

  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 說明文件 ,直接在 Google Cloud 控制台實際操作。

如要建立並訂閱 Pub/Sub 主題,請按照下列步驟操作:

Google Cloud 控制台

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

    前往 Google Cloud Pub/Sub

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

  2. 按一下「建立主題」圖示 ,然後 :

    1. 輸入主題名稱,例如 workspace-events-topic
    2. 保持選取「新增預設訂閱項目」。Pub/Sub 會將這個名稱 和主題名稱相似的預設訂閱項目,例如 workspace-events-topic-sub
    3. 選用步驟:更新或設定其他屬性 找出適合您主題的網站
  3. 按一下「建立」,完整主題名稱的格式為 projects/PROJECT_ID/topics/TOPIC_ID。 您將在後續步驟中使用這個全名。

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

    1. 在你的主題頁面中,前往側邊面板並開啟 「權限」分頁。
    2. 按一下「新增主體」
    3. 在「新增主體」欄位中,新增要啟用哪個服務帳戶的服務帳戶。 是一種 Google Workspace 應用程式,可將事件傳送到 訂閱:
      1. 在 Chat 事件中, chat-api-push@system.gserviceaccount.com
      2. 針對 Meet 活動, meet-api-event-push@system.gserviceaccount.com
    4. 在「指派角色」選單中選取 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:您建立的主題名稱

訂閱 Google Workspace 資源

在本節中,您將訂閱下列 Google Workspace 資源: 可讓您監控事件的三種類型

選擇並找出目標資源

在 Google Workspace 訂閱方案中,目標資源是 您監控活動所監控的 Google Workspace 資源。目標 資源會顯示在訂閱項目的 targetResource 欄位中,格式為 完整資源名稱。舉例來說,如果訂閱項目會監控 Google Chat 聊天室 (spaces/AAAABBBBBBB),targetResource的值為 //chat.googleapis.com/spaces/AAAABBBBBBB

建立訂閱項目前,請參閱下列章節瞭解如何 識別及設定目標資源的格式。

找出 Chat 目標資源

目標資源 格式 限制
空格

//chat.googleapis.com/spaces/SPACE

其中 SPACE Chat API space 資源的資源名稱。 您可以從聊天室網址或使用 spaces.list() 方法,增加圍繞地圖邊緣的邊框間距。

授權訂閱的 Chat 使用者必須 透過 Google Workspace 或 Google 加入聊天室成員 。
使用者的所有聊天室

//chat.googleapis.com/spaces/-

訂閱項目只會收到使用者所屬聊天室的事件 成員透過 Google Workspace 或 Google 帳戶註冊
使用者

//cloudidentity.googleapis.com/users/USER

其中 USER Chat API user 資源的資源名稱。 詳情請參閱 識別與指定 Google Chat 使用者

訂閱項目只會收到與使用者相關的事件 授權訂閱使用者無法授權給 代表其他使用者

找出 Meet 目標資源

目標資源 格式 限制 (如適用)
會議空間 //meet.googleapis.com/spaces/SPACE

其中 SPACE Meet REST API space 資源的資源名稱。 詳情請參閱 做法 Meet 會識別會議空間

使用者 //cloudidentity.googleapis.com/users/USER

其中 USER Meet REST API participant 資源的 signedinUser.user 欄位。 詳情請參閱 與參與者合作

訂閱項目會收到與會議空間相關的事件, 就是下列其中一項:

  • 會議空間的擁有者。
  • 主辦人 輸入與會議空間相關的 Google 日曆活動。

建立 Google Workspace 訂閱方案

如要建立訂閱項目,請使用 Google Workspace Events API 的 透過 subscriptions.create() 方法建立 Subscription 資源。請指定以下欄位:

  • targetResource:您在 上一節,使用完整資源名稱格式化。
  • 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_RESOURCEGoogle Workspace 資源 訂閱項目的完整資源名稱,格式為完整資源名稱。適用對象 例如,若要使用聊天室 ID 訂閱 Google Chat 聊天室 AAAABBBB,使用 //chat.googleapis.com/spaces/AAAABBBB
    • EVENT_TYPES:一或多個事件類型 您要在目標資源中訂閱的節點。採用 字串陣列,例如 'google.workspace.chat.message.v1.created'
    • TOPIC_NAME:Pub/Sub 主題的全名 建立 Deployment採用格式 projects/PROJECT_ID/topics/TOPIC_ID
    • RESOURCE_DATA:布林值,用來指定 訂閱包含酬載中的資源資料:

      • True:包含所有資源資料。限制 已納入,請將 fieldMask ] 欄位,然後為已變更的資源指定至少一個欄位。僅限 訂閱 Chat 資源支援,包括 資源資料
      • False:排除資源資料。
  2. 如要建立 Google Workspace 訂閱,請執行函式 createSubscription 位於 Apps Script 專案中。

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_RESOURCEGoogle Workspace 資源 訂閱項目的完整資源名稱,格式為完整資源名稱。適用對象 例如,若要使用聊天室 ID 訂閱 Google Chat 聊天室 AAAABBBB,使用 //chat.googleapis.com/spaces/AAAABBBB
    • EVENT_TYPES:一或多個事件類型 您要在目標資源中訂閱的節點。採用 字串陣列,例如 'google.workspace.chat.message.v1.created'
    • TOPIC_NAME:Pub/Sub 主題的全名 建立 Deployment採用格式 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 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 說明文件