本頁說明如何使用 Google Workspace Events API 訂閱 Google Workspace 資源。Google Workspace 訂閱項目可讓應用程式接收 Google Workspace 事件的相關資訊,這些事件代表 Google Workspace 資源的變更。如要瞭解 Google Workspace Events API 支援哪些資源和事件類型,請參閱 Google Workspace Events API 總覽。
這個頁面包含下列建立 Google Workspace 訂閱方案的步驟:
- 設定環境。
- 建立並訂閱 Google Cloud Pub/Sub 主題。您可以使用這個主題做為端點,接收 Google Workspace 事件。
- 在
Subscription
資源上呼叫 Google Workspace Events API 的create
方法。 - 測試 Google Workspace 訂閱項目,確認 Pub/Sub 主題會收到您訂閱的事件。
- 您可以視需要設定如何將事件推送至應用程式的端點,讓應用程式處理事件並視需要採取行動。
必要條件
Apps Script
- 如要在本指南中使用 Google Cloud CLI 指令,請完成下列步驟:
- 安裝 Google Cloud CLI。
- 如要
初始化
gcloud
CLI,請執行下列程式碼:
gcloud init
- 啟用計費功能的 Google Cloud 專案。如要訂閱 Chat,您也必須在 Cloud 專案中啟用 Chat API,並設定「應用程式名稱」、「顯示圖片網址」和「說明」欄位。詳情請參閱「建構 Google Chat 應用程式」。
- 需要透過為應用程式設定的 OAuth 同意畫面進行使用者驗證。設定同意畫面時,您必須指定範圍,才能支援訂閱的各個事件類型。如要設定同意畫面並找出必要範圍,請參閱「選擇範圍」。
- Apps Script 專案:
- 使用 Google Cloud 專案,而非 Apps Script 自動建立的預設專案。
- 如要設定 OAuth 同意畫面,您新增的任何範圍也必須新增至 Apps Script 專案的
appsscript.json
檔案。例如: - 啟用
Google Workspace Events
進階服務。
"oauthScopes": [ "https://www.googleapis.com/auth/chat.messages.readonly" ]
Python
- Python 3.6 以上版本
- pip 套件管理工具
- 最新版 Python 適用的 Google 用戶端程式庫。如要安裝或更新這些工具,請在指令列介面中執行下列指令:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- 如要在本指南中使用 Google Cloud CLI 指令,請完成下列步驟:
- 安裝 Google Cloud CLI。
- 如要
初始化
gcloud
CLI,請執行下列程式碼:
gcloud init
- 啟用計費功能的 Google Cloud 專案。如要訂閱 Chat,您也必須在 Cloud 專案中啟用 Chat API,並設定「應用程式名稱」、「顯示圖片網址」和「說明」欄位。詳情請參閱「建構 Google Chat 應用程式」。
- 需要透過為應用程式設定的 OAuth 同意畫面進行使用者驗證。設定同意畫面時,您必須指定範圍,才能支援訂閱的各個事件類型。如要設定同意畫面並找出必要範圍,請參閱「選擇範圍」。
設定環境
下一節說明如何設定環境,然後再建立 Google Workspace 訂閱方案。
啟用 Google Workspace Events API 和 Google Cloud Pub/Sub API
使用 Google API 前,請先在 Google Cloud 專案中啟用這些 API。您可以在單一 Google Cloud 專案中啟用一或多個 API。Google Cloud 控制台
在 Google Cloud 控制台中,開啟應用程式的 Google Cloud 專案,然後啟用 Google Workspace Events API 和 Pub/Sub API:
gcloud
在工作目錄中登入 Google 帳戶:
gcloud auth login
將專案設為應用程式的 Cloud 專案:
gcloud config set project PROJECT_ID
將
PROJECT_ID
替換為應用程式的 Cloud 專案專案 ID。啟用 Google Workspace Events API 和 Google Cloud Pub/Sub API:
gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com
建立 OAuth 用戶端 ID 憑證
請選擇應用程式類型,查看如何建立 OAuth 用戶端 ID 的具體操作說明:
網頁應用程式
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「網頁應用程式」。
- 在「Name」(名稱) 欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 新增與應用程式相關的授權 URI:
- 用戶端應用程式 (JavaScript):在「已授權的 JavaScript 來源」下方,按一下「新增 URI」。然後輸入要用於瀏覽器要求的 URI。這會識別應用程式可從哪些網域將 API 要求傳送至 OAuth 2.0 伺服器。
- 伺服器端應用程式 (Java、Python 等):按一下「已授權的重新導向 URI」下方的「新增 URI」。然後輸入端點 URI,OAuth 2.0 伺服器可將回應傳送至該 URI。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」下方。
記下用戶端 ID。網頁應用程式不會使用用戶端密鑰。
Android
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「Android」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 在「套件名稱」欄位中,輸入
AndroidManifest.xml
檔案中的套件名稱。 - 在「SHA-1 憑證指紋」欄位中,輸入產生的 SHA-1 憑證指紋。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」(OAuth 2.0 用戶端 ID) 下方。
iOS
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「iOS」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 在「軟體包 ID」欄位中,輸入應用程式
Info.plist
檔案中列出的軟體包 ID。 - 選用:如果您的應用程式在 Apple App Store 中上架,請輸入 App Store ID。
- 選用:在「團隊 ID」欄位中,輸入 Apple 產生並指派給您團隊的專屬字串 (共 10 個字元)。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」(OAuth 2.0 用戶端 ID) 下方。
Chrome 應用程式
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「Chrome 擴充功能」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 在「項目 ID」欄位中,輸入應用程式的專屬 32 字元 ID 字串。您可以在應用程式的 Chrome 線上應用程式商店網址和 Chrome 線上應用程式商店開發人員資訊主頁中找到這個 ID 值。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」(OAuth 2.0 用戶端 ID) 下方。
電腦版應用程式
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「電腦應用程式」。
- 在「Name」(名稱) 欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」(OAuth 2.0 用戶端 ID) 下方。
電視和受限制的輸入裝置
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「電視和輸入受限的裝置」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」(OAuth 2.0 用戶端 ID) 下方。
通用 Windows 平台 (UWP)
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「通用 Windows 平台 (UWP)」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 在「商店 ID」欄位中,輸入應用程式專屬的 12 個字元 Microsoft Store ID 值。您可以在應用程式的 Microsoft Store 網址和合作夥伴中心中找到這個 ID。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」(OAuth 2.0 用戶端 ID) 下方。
下載用戶端密鑰 JSON 檔案
用戶端密鑰檔案是 OAuth 用戶端 ID 憑證的 JSON 表示法,應用程式提供憑證時可以參考這個檔案。
在 Google Cloud 控制台中,依序前往「選單」圖示 >「API 和服務」 >「憑證」。
在「OAuth 2.0 Client IDs」下方,按一下您建立的用戶端 ID。
按一下「下載 JSON」。
將檔案儲存為
credentials.json
。
建立及訂閱 Pub/Sub 主題
在本節中,您將建立 Pub/Sub 主題和該主題的訂閱項目。您的 Pub/Sub 主題會做為通知端點,Google Workspace 訂閱項目會在此接收事件。
如要進一步瞭解如何建立及管理 Pub/Sub 主題,請參閱 Pub/Sub 說明文件。
如要建立及訂閱 Pub/Sub 主題,請按照下列步驟操作:
Google Cloud 控制台
在 Google Cloud 控制台中,前往 Pub/Sub 頁面:
確認已選取應用程式的 Cloud 專案。
按一下「建立主題」
,然後執行下列操作:- 輸入主題名稱,例如
workspace-events-topic
。 - 保留已選取的「新增預設訂閱項目」。Pub/Sub 會將這個預設訂閱項目命名為類似主題名稱的名稱,例如
workspace-events-topic-sub
。 - 選用:更新或設定主題的其他屬性。
- 輸入主題名稱,例如
按一下「建立」,完整主題名稱的格式為
projects/PROJECT_ID/topics/TOPIC_ID
。您將在後續步驟中使用這個全名。授予將 Pub/Sub 訊息發布至主題的權限:
- 在主題頁面中,前往側邊面板並開啟「權限」分頁。
- 按一下「新增主體」。
- 在「新增主體」欄位中,新增 Google Workspace 應用程式的服務帳戶,該應用程式會將事件傳送至您的訂閱項目:
- 如果是 Chat 活動,
chat-api-push@system.gserviceaccount.com
。 - 開發人員預覽版:適用於雲端硬碟事件。
drive-api-event-push@system.gserviceaccount.com
- 如果是 Meet 活動,請參閱
meet-api-event-push@system.gserviceaccount.com
。
- 如果是 Chat 活動,
- 在「指派角色」選單中,選取
Pub/Sub Publisher
。 - 按一下 [儲存]。更新主題權限可能需要幾分鐘。
gcloud
在 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 訂閱項目。授予將訊息發布到主題的權限:
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
。 - 開發人員預覽版:如要接收雲端硬碟的事件,請使用
drive-api-event-push@system.gserviceaccount.com
。 - 如要接收 Meet 的事件,請使用
meet-api-event-push@system.gserviceaccount.com
。
- 如要接收 Chat 的事件,請使用
更新主題權限可能需要幾分鐘。
為主題建立 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 的目標資源
目標資源 | 格式 | 限制 |
---|---|---|
空格 |
其中 SPACE 是 Chat API |
授權訂閱的 Chat 使用者必須透過 Google Workspace 或 Google 帳戶成為聊天室成員。 |
使用者的所有空間 |
|
訂閱項目只會接收使用者透過 Google Workspace 或 Google 帳戶加入的聊天室活動。 |
使用者 |
其中 USER 是 Chat API |
訂閱項目只會接收授權訂閱的使用者相關事件。使用者無法代表其他使用者授權訂閱。 |
找出雲端硬碟的目標資源
目標資源 | 格式 | 限制 (如適用) |
---|---|---|
檔案 | //googleapis.com/drive/v3/files/FILE
其中 FILE 是 Drive API |
授權訂閱的使用者必須具備訂閱事件相關檔案的權限。 |
共用雲端硬碟 | //googleapis.com/drive/v3/drives/DRIVE
其中 DRIVE 是 Drive API |
訂閱項目只會接收共用雲端硬碟中項目的事件,使用者必須透過 Google Workspace 帳戶或 Google 帳戶成為該共用雲端硬碟的成員。 |
找出 Meet 的目標資源
目標資源 | 格式 | 限制 (如適用) |
---|---|---|
會議空間 | //meet.googleapis.com/spaces/SPACE
其中 SPACE 是 Meet REST API |
|
使用者 | //cloudidentity.googleapis.com/users/USER
其中 USER 是 Meet REST API |
訂閱項目會接收會議空間的相關事件,而使用者必須符合下列條件之一:
|
建立 Google Workspace 訂閱方案
如要建立訂閱項目,請使用 Google Workspace Events API 的 subscriptions.create
方法建立 Subscription
資源。指定下列欄位:
targetResource
:您在上一節中識別的 Google Workspace,格式為完整資源名稱。eventTypes
:您要接收資源相關事件類型的一或多個陣列。舉例來說,如果應用程式只需要瞭解發布到 Chat 聊天室的新訊息,應用程式可以只訂閱有關建立訊息的事件。notificationEndpoint
:Google Workspace 訂閱方案傳送事件的通知端點。您可以使用上一節建立的 Pub/Sub 主題。payloadOptions
:指定要在事件酬載中納入多少資源資料的選項。這項設定會影響訂閱方案的到期時間。詳情請參閱「事件資料」。
如要建立 Google Workspace 訂閱方案,請按照下列步驟操作:
Apps Script
在 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
的 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
:排除資源資料。
如要建立 Google Workspace 訂閱項目,請在 Apps Script 專案中執行
createSubscription
函式。
Python
在工作目錄中,建立名為
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
的 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
:排除資源資料。
如要建立 Google Workspace 訂閱項目,請在終端機中執行下列指令:
python3 create_subscription.py
Google Workspace Events API 會傳回已完成的長時間執行作業,其中包含您建立的 Subscription
資源例項。
測試 Google Workspace 訂閱方案
如要測試是否能接收 Google Workspace 事件,您可以觸發事件,並將訊息提取至 Pub/Sub 訂閱項目。
如要測試 Google Workspace 訂閱方案,請按照下列步驟操作:
Google Cloud 控制台
在 Google Workspace 訂閱方案的目標資源中,觸發一或多種事件。舉例來說,如果你已訂閱 Chat 聊天室中的新訊息,請在該聊天室中張貼訊息。
在 Google Cloud 控制台中,前往 Pub/Sub 頁面:
確認已選取應用程式的 Cloud 專案。
在「Pub/Sub」選單中,按一下「Subscriptions」。
在表格中找出主題的 Pub/Sub 訂閱項目,然後按一下訂閱項目名稱。
按一下「Messages」(訊息) 分頁標籤。
按一下「Pull」(提取)。事件最多可能需要幾分鐘的時間,才會產生 Pub/Sub 訊息。
gcloud
在 Google Workspace 訂閱方案的目標資源中,觸發一或多種事件。舉例來說,如果你已訂閱 Chat 聊天室中的新訊息,請在該聊天室中張貼訊息。
執行下列指令:
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 說明文件。