本頁說明如何使用 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 用戶端 ID」下方。
iOS
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「iOS」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 在「軟體包 ID」欄位中,輸入應用程式
Info.plist
檔案中列出的軟體包 ID。 - 選用:如果您的應用程式已在 Apple App Store 上架,請輸入 App Store ID。
- 選用:在「團隊 ID」欄位中,輸入 Apple 產生並指派給您團隊的專屬字串 (共 10 個字元)。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。
Chrome 應用程式
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「Chrome 擴充功能」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 在「項目 ID」欄位中,輸入應用程式的專屬 32 字元 ID 字串。您可以在應用程式的 Chrome 線上應用程式商店網址和 Chrome 線上應用程式商店開發人員資訊主頁中找到這個 ID 值。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。
電腦版應用程式
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「電腦應用程式」。
- 在「Name」(名稱) 欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。
電視和受限制的輸入裝置
- 前往 Google Cloud 控制台,依序點選「選單」圖示 > >「用戶端」。
- 按一下「建立用戶端」。
- 依序點選「應用程式類型」>「電視和輸入受限的裝置」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。
通用 Windows 平台 (UWP)
下載用戶端密鑰 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 |
訂閱項目只會接收授權訂閱的使用者相關事件。使用者無法代表其他使用者授權訂閱。 |
找出雲端硬碟的目標資源
目標資源 | 格式 | 限制 (如適用) |
---|---|---|
檔案 |
//drive.googleapis.com/files/FILE
其中 FILE 是 Drive API |
授權訂閱的使用者必須具備訂閱項目中檔案的權限,才能訂閱事件。 |
共用雲端硬碟 |
//drive.googleapis.com/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 說明文件。