本頁說明 Google Chat 應用程式可使用 Google Workspace Events API 訂閱的 Google Chat 事件。決定所需的事件類型後，請建立訂閱項目，開始接收 Google Chat 的事件。
除了訂閱事件外，您也可以呼叫 Chat API 來查詢事件。呼叫 Chat API 可讓您定期擷取事件，或追蹤因服務中斷而錯過的訂閱事件。如要瞭解如何接收及回應 Chat 事件，請參閱 Chat 說明文件中的「使用 Google Chat 事件」一節。
支援的 Chat 事件
訂閱 Google Workspace 後，您就能接收 Chat 中下列類型的變更事件：
可監控事件的資源
如要接收事件，您必須指定要監控的 Chat 資源，這稱為訂閱的目標資源。
Google Workspace Events API 支援以下 Chat 目標資源：
| 目標資源 | 格式 | 限制 |
|---|---|---|
| 空格 |
其中 SPACE 是 Chat API |
授權訂閱的 Chat 使用者必須透過 Google Workspace 或 Google 帳戶成為聊天室的成員。 |
| 使用者的所有聊天室 |
|
訂閱項目只會接收使用者透過 Google Workspace 或 Google 帳戶成為成員的聊天室活動。 |
| 使用者 |
其中 USER 是 Chat API |
訂閱項目只會收到授權訂閱的使用者相關事件。使用者無法代表其他使用者授權訂閱。 |
建立訂閱項目的事件類型
建立訂閱時，您可以使用 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": "😊"
}
}
}
省略資源資料
{
"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": "😸"
}
}
}
]
}
省略資源資料
{
"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 群組間接加入聊天室、更新或移除，訂閱項目就不會收到這些會員事件。如要瞭解 Google 群組會員資格運作方式，請參閱「將 Google 群組新增至聊天室」。
相關主題
- Google Workspace 事件的結構
- 選擇 OAuth 範圍
- 建立訂閱項目以接收 Chat 事件