本頁說明 Google Chat 應用程式如何接收及回應 Google Chat 中的事件。
Google Chat 事件代表 Chat 中的活動或變更，例如聊天室中的新訊息。Chat 應用程式可透過事件瞭解發生了什麼事，並採取行動或以有意義的方式回應使用者。
以下列舉幾個事件的用途：
- 監控及回覆聊天室中的新訊息，例如檢查關鍵字或詞組。
- 在使用者加入聊天室時傳送歡迎訊息，說明聊天室規範或分享有效使用 Chat 應用程式的訣竅。
- 追蹤及分析 Chat 活動。舉例來說，您可以傳送新成員的月報，或是獲得最多回應或回覆的訊息。
- 透過訊息平台進行通訊。舉例來說，使用者不必離開 Chat，就能與其他訊息平台的使用者互傳訊息。
活動的運作方式
每當 Google Chat 發生事件時，系統就會建立、更新或刪除 Google Chat API 資源。Chat 會使用事件將資訊傳送至 Chat 應用程式，說明發生的活動類型和受影響的 Chat API 資源。
Message 資源。然後，Chat 會建立包含新訊息資料的事件。Chat 會依類型分類事件。事件類型可協助您篩選及接收所需資訊，並以相同方式處理類似活動。
下表說明 Chat 中的活動如何影響相關的 Chat API 資源，以及 Chat 應用程式收到的事件類型：
| 活動 | Chat API 資源 | 事件類型 |
|---|---|---|
| 使用者在 Chat 聊天室中張貼訊息 | 已建立 Message 資源。 |
新訊息 |
| 使用者成為聊天室管理員。 | 更新 Membership 資源。 |
已更新會員方案 |
| 使用者回應訊息。 | 已建立 Reaction 資源。 |
新回應 |
| 使用者離開聊天室。 | Membership 資源已刪除。 |
已刪除會員 |
接收 Google Chat 事件
如要接收事件，Chat 應用程式可以採取下列任一做法：
- 使用 Google Workspace Events API 訂閱事件，即可在事件發生時收到通知。
- 呼叫 Chat API，查詢近期事件。
下表說明查詢或訂閱事件的差異和原因：
| 訂閱事件 | 查詢活動 | |
|---|---|---|
| 用途 |
|
|
| API | Google Workspace Events API | Chat API |
| 事件來源 | 即時通訊空間、使用者和 Google Workspace 機構 ( 開發人員預覽版) | 僅限聊天室 |
| 支援的事件 |
如需支援的事件類型清單，請參閱 Google Workspace Events API 說明文件中的「 建立訂閱項目的事件類型」。 |
如需支援的事件類型清單，請參閱 Chat API 參考文件中的 spaceEvents 資源。
|
| 事件格式 | Google Cloud Pub/Sub 訊息，格式符合 CloudEvent 規格。詳情請參閱「Google Workspace 事件結構」。 |
Chat API 資源
(
spaces.spaceEvent)
|
| 事件資料 | Base64 編碼字串，可包含或不包含資源資料。如需有效負載範例，請參閱「事件資料」。 | 包含資源資料的 JSON 酬載。部分事件類型只會包含特定資源欄位。如需有效負載範例，請參閱 參考文件。 |
例：查詢或訂閱聊天室中與成員資格相關的事件
在這個範例中，Chat 應用程式想要接收有關 Chat 聊天室成員變更的資訊。在空間中，會發生下列成員活動：
- 使用者加入聊天室，系統會建立
Membership資源並觸發新成員事件。 - 使用者成為聊天室管理員，這會更新使用者的
Membership資源，並觸發更新的成員事件。 - 使用者離開空間，系統會刪除該使用者的
Membership資源，並觸發成員刪除事件。
訂閱會員事件
如要即時接收事件，Chat 應用程式會呼叫 Google Workspace Events API subscriptions.create() 方法，訂閱所有類型的成員資格事件。建立訂閱項目後，Chat 應用程式即可開始接收成員事件。
如圖 2 所示，Chat 應用程式已有效訂閱聊天室，因此只要聊天室成員資格有異動，應用程式就會收到事件。接著，Chat 應用程式就能即時處理或回應任何活動，例如向加入聊天室的成員發布私人歡迎訊息。
如要瞭解如何使用 Google Workspace Events API 建立訂閱項目，請參閱 Google Workspace Events API 說明文件。
查詢最近的會員活動
Chat 應用程式不必在成員資格事件發生時接收事件，而是可以呼叫 Chat API，列出與成員資格活動相關的近期聊天室事件。
如圖 3 所示，在所有成員活動發生後，Chat 應用程式會呼叫 Chat API spaces.spaceEvents.list() 方法，並篩選查詢，找出新增、更新及刪除的成員事件。Chat API 會傳回 spaceEvent 資源清單，當中列出每項成員資格變更。然後，Chat 應用程式就能根據近期活動處理或回覆，例如發布每週訊息，當中包含過去 7 天的聊天室成員活動摘要。
如要使用 Chat API 查詢事件，請參閱「列出 Google Chat 聊天室的事件」。
限制和傳送行為
一般限制
- 如要接收成員事件，使用者或 Chat 應用程式必須是聊天室的直接成員。如果使用者是透過 Google 群組間接新增、更新或移除聊天室，訂閱項目不會收到這些成員資格事件。如要瞭解 Google 群組成員資格的運作方式，請參閱「將 Google 群組新增至聊天室」。
使用者訂閱
-
訂閱使用者時，只有在發布第一則訊息後，才會觸發有關即時訊息或未命名群組通訊中新成員的事件 (
google.workspace.chat.membership.v1.created)。
客戶訂閱項目 ( 開發人員預覽版)
客戶訂閱方案有以下限制：
- Google Workspace 機構必須至少有一個 Enterprise SKU 授權。請注意，在開發人員預覽版計畫階段，我們不會嚴格執行這項規定，但日後會強制執行 (另行公告)。
- Chat 應用程式只能為特定 Google Workspace 機構建立一個客戶訂閱項目。Google Workspace 機構最多可有五個客戶訂閱項目 (由不同的 Chat 應用程式建立)。
對於顧客訂閱項目，事件傳送遵循下列一般規則：
- 即時通訊空間活動：只有在 Google Workspace 機構管理的即時通訊空間中發生活動時，才會傳送通知。
- 使用者事件：只有在事件發生時，使用者屬於您的 Google Workspace 機構，才會傳送這類事件。
會員活動是這些規則的唯一例外。您的訂閱項目可以接收貴機構和外部機構管理之聊天室的成員事件，但傳送方式取決於聊天室的管理機構：
由 Google Workspace 機構管理的工作空間
如果 Google Workspace 機構管理的聊天室發生成員異動，系統會以聊天室事件的形式傳送通知。
空間事件的資源名稱格式如下：
spaces/{spaceId}/spaceEvents/{spaceEventId}
由外部機構管理的聊天室
如果外部機構管理的聊天室 (例如外部具名聊天室或外部使用者建立的即時訊息) 中，Google Workspace 機構管理的使用者成員資格有所變更，訂閱項目就會收到這項使用者事件。
使用者事件的資源名稱格式如下：
users/{userId}/userEvents/{userEventId}