本頁面說明 Google Chat 應用程式可使用 Google Workspace Event API 訂閱的 Google Chat 事件。決定好需要的事件類型後，請建立訂閱項目，即可開始從 Google Chat 接收事件。
除了訂閱事件以外，您也可以呼叫 Chat API 查詢事件。呼叫 Chat API 可讓您定期擷取事件，或掌握訂閱因服務中斷而錯過的事件。如要瞭解接收及回應 Chat 事件的方式，請參閱 Chat 說明文件中的「使用 Google Chat 中的事件」。
支援的 Chat 目標資源
Google Workspace Event API 支援下列訂閱：
- 聊天室，以
space資源表示 - 使用者，以 Cloud Identity API
user資源表示
支援的 Chat 事件
Google Workspace 訂閱可讓您在 Chat 中接收下列類型的異動事件：
建立訂閱項目的事件類型
建立訂閱項目時，請使用 eventTypes[] 欄位指定要接收的事件類型。事件類型會根據 CloudEvents 規格 (例如 google.workspace.APPLICATION.RESOURCE.VERSION.ACTION) 設定格式。
舉例來說，如要接收有關使用者加入 Chat 聊天室的事件，您必須將聊天室指定為目標資源，事件類型則指定為 google.workspace.chat.membership.v1.created。如要接收有關特定使用者加入任何空間的事件，請將使用者指定為目標資源，而事件類型為 google.workspace.chat.membership.v1.created。如要進一步瞭解事件的運作方式，請參閱「Google Workspace 事件結構」。
下表列出使用者訂閱聊天室和訂閱項目支援的事件類型。如要瞭解觸發事件的例外狀況，請參閱「限制」一文。
| 事件類型 | 格式 | 資源資料 | ||
|---|---|---|---|---|
| 聊天室訂閱 | ||||
| 訊息已張貼。 |
|
|
||
| 已更新訊息。 |
|
|
||
| 訊息已刪除。 |
|
|
||
| 建立回應。 |
|
|
||
| 已刪除回應。 |
|
|
||
| 一位成員已加入聊天室。 |
|
|
||
| 聊天室中的成員已更新。 |
|
|
||
| 一位成員會從聊天室中移除。 |
|
|
||
| 聊天室已更新。 |
|
|
||
| 聊天室已刪除。 |
|
|
||
| 使用者的訂閱 | ||||
| 使用者將成為聊天室成員。
並非所有新成員都會觸發事件。詳情請參閱「限制」一節 |
|
|
||
| 使用者的聊天室成員資格已更新。 |
|
|
||
| 系統會解除使用者的聊天室直接成員身分。 |
|
|
||
批次事件類型 (僅限輸出)
除了接收您訂閱的事件類型外，Chat 應用程式也可能會接收批次事件。批次事件是一種事件，代表短時間內發生的多個相同類型的事件。批次事件的酬載包含所有變更的資源清單。
舉例來說，如果使用者同時將 20 位使用者加入聊天室，您的 Chat 應用程式可能會收到批次事件 (google.workspace.chat.membership.v1.batchCreated)。事件酬載會包含在使用者將成員新增至聊天室時建立的所有新 Membership 資源清單。
您的訂閱事件類型會收到批次事件，因此建立訂閱項目時不需要指定批次事件。舉例來說，假設您訂閱了新的回應 (google.workspace.chat.reaction.v1.created)，Chat 應用程式會自動設為接收批次回應事件 (google.workspace.chat.reaction.v1.batchCreated)。
下表列出訂閱項目可能的批次事件：
| 批次事件類型 | 格式 |
|---|---|
| 張貼多則訊息。 |
|
| 更新多則訊息。 |
|
| 已刪除多則訊息。 |
|
| 可建立多個回應。 |
|
| 系統會刪除多個回應。 |
|
| 訂閱的聊天室已新增多位成員，或是訂閱的使用者已新增至多個聊天室。 |
|
| 系統會在訂閱的聊天室或已訂閱的使用者中更新多個會籍。 |
|
| 系統會從訂閱的聊天室中移除多位成員，或是將訂閱的使用者從多個聊天室中移除。 |
|
| 聊天室中有多項更新。 |
|
事件資料
本節說明 Chat 事件的事件資料和範例酬載。
當您的 Google Workspace 訂閱收到 Chat 的事件時，data 欄位會包含該事件的酬載。此酬載包含已變更 Google Workspace 資源的相關資訊。舉例來說，如果您已訂閱聊天室中的成員事件，這些事件的酬載會包含變更的 spaces.membership 資源相關資訊。
事件酬載中的資源資料
建立訂閱項目時，您可以指定酬載包含資源的詳細資料，還是只加入資源名稱。舉例來說，如果您想在 Chat 聊天室中接收有關成員的事件，可以指定要在事件酬載中接收成員資源的哪些欄位。
下表提供 Chat 聊天室 spaces/AAAABBBBBB 訂閱項目的 JSON 酬載範例。針對訂閱項目收到的每個事件，酬載會顯示在事件的 data 欄位中：
| 範例 | 事件類型 | JSON 酬載 |
|---|---|---|
使用者在聊天室中張貼了「Hello world」訊息。 |
|
包含資源資料
{
"message":
{
"name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD",
"sender":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "2023-09-07T21:37:36.260127Z",
"text": "Hello world",
"thread":
{
"name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE"
},
"space":
{
"name": "spaces/AAAABBBBBB"
},
"argumentText": "Hello world"
}
}
排除資源資料
{
"message":
{
"name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
}
}
|
| 使用者將成為聊天室管理員。 |
|
包含資源資料
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321",
"state": "JOINED",
"member":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MANAGER"
}
}
排除資源資料
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
}
|
| 使用者將聊天室說明更新為「Cymbal Labs 的銷售團隊」。 | google.workspace.chat.space.v1.updated |
包含資源資料
{
"space":
{
"name": "spaces/AAAABBBBBB",
"displayName": "Cymbal Sales",
"spaceThreadingState": "THREADED_MESSAGES",
"spaceType": "SPACE",
"spaceDetails":
{
"description": "Sales team for Cymbal Labs."
},
"spaceHistoryState": "HISTORY_ON"
}
}
排除資源資料
{
"space":
{
"name": "spaces/AAAABBBBBB"
}
}
|
| 兩名 Chat 使用者同時新增至聊天室。 | google.workspace.chat.membership.v1.batchCreated |
包含資源資料
{
"memberships": [
{
"membership": {
"name": "spaces/AAAABBBBBB/members/1234567890987654321",
"state": "JOINED",
"member":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MEMBER"
}
},
{
"membership": {
"name": "spaces/AAAABBBBBB/members/987654321234567890",
"state": "JOINED",
"member":
{
"name": "users/987654321234567890",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MEMBER"
}
}
]
}
排除資源資料
{
"memberships": [
{
"membership": {
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
},
{
"membership": {
"name": "spaces/AAAABBBBBB/members/98765432123456789019"
}
}
]
}
|
| 使用者用 › 表情符號回應訊息。 | google.workspace.chat.reaction.v1.created |
包含資源資料
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
"user":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😊"
}
}
}
Omits 資源資料
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
}
}
|
| 使用者會使用 › 表情符號和 😸? 表情符號回應訊息。 | google.workspace.chat.reaction.v1.batchCreated |
包含資源資料
{
"reactions": [
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
"user":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😊"
}
}
},
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
"user":
{
"name": "users/98765431234564321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😸"
}
}
}
]
}
Omits 資源資料
{
"reactions": [
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
},
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
}
}
]
}
|
限制
-
對使用者來說，在即時訊息或未命名的群組通訊 (
google.workspace.chat.membership.v1.created) 中有關新成員的事件，只會在第一則訊息張貼後觸發。 - 變更聊天室記錄時，不會觸發更新的聊天室事件 (事件類型：
google.workspace.chat.spaces.v1.updated)。 - 如要接收成員資格事件，使用者必須是聊天室的直接成員。如果使用者是透過 Google 群組間接新增、更新或移除聊天室，訂閱項目並不會收到這類成員事件。如要瞭解 Google 群組成員的運作方式，請參閱將 Google 群組新增至聊天室。
相關主題
- Google Workspace 事件結構
- 選擇 OAuth 範圍
- 如要接收 Chat 事件，請建立訂閱項目