本页介绍了 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。
例如，如需接收与用户加入聊天聊天室相关的事件，您可以将聊天室指定为目标资源，并将事件类型指定为 google.workspace.chat.membership.v1.created。如需接收有关指定用户加入任何聊天室的事件，您可以将该用户指定为目标资源，并将事件类型指定为 google.workspace.chat.membership.v1.created。如需详细了解事件的运作方式，请参阅 Google Workspace 事件的结构。
下表显示了聊天室订阅和用户订阅支持哪些事件类型。如需了解有关触发事件的例外情况，请参阅限制。
| Event type | 格式 | 资源数据 | ||
|---|---|---|---|---|
| 对聊天室的订阅 | ||||
| 发布了一条消息。 |
|
|
||
| 消息已更新。 |
|
|
||
| 消息已删除。 |
|
|
||
| 系统会创建一条回应。 |
|
|
||
| 删除回应。 |
|
|
||
| 将成员添加到聊天室。 |
|
|
||
| 聊天室中的成员已更新。 |
|
|
||
| 将成员从聊天室中移除。 |
|
|
||
| 聊天室已更新。 |
|
|
||
| 聊天室已被删除。 |
|
|
||
| 向用户订阅 | ||||
| 用户成为聊天室的成员。
并非所有新成员都会触发事件。如需了解详情，请参阅限制 |
|
|
||
| 更新用户对聊天室的成员资格。 |
|
|
||
| 系统会将用户从聊天室的直接成员名单中移除。 |
|
|
||
批量事件类型（仅限输出）
除了接收您订阅的事件类型之外，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 字段中：
| 示例 | Event type | 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 事件