本页面介绍了 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 资源。
|
| 事件格式 | 根据 CloudEvent 规范设置格式的 Google Cloud Pub/Sub 消息。如需了解详情，请参阅 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 组织必须至少有一个企业版 SKU 许可。
- Chat 应用只能为给定的 Google Workspace 组织创建一个客户订阅。一个 Google Workspace 组织总共最多可以有 5 个客户订阅（由不同的 Chat 应用创建）。
对于客户订阅，事件传送遵循以下一般规则：
- 聊天室事件：仅当事件发生在由您的 Google Workspace 组织管理的聊天室中时，才会传送。
- 用户事件：仅在事件发生在属于您 Google Workspace 组织的用户时才会传送。
这些规则的唯一例外是成员资格事件。您的订阅可以接收来自贵组织管理的聊天室和外部组织管理的聊天室的成员资格事件，但这些事件的传递方式取决于哪个组织管理该聊天室：
由您的 Google Workspace 组织管理的聊天室
如果 Google Workspace 组织管理的聊天室中发生成员资格变更，则会以聊天室事件的形式传递。
空间事件的资源名称采用以下格式：
spaces/{spaceId}/spaceEvents/{spaceEventId}
由外部组织管理的聊天室
如果由您的 Google Workspace 组织管理的用户在由外部组织管理的聊天室（例如，外部命名聊天室或由外部用户创建的私信）中的成员资格发生变化，您的订阅会将此事件作为用户事件接收。
用户事件的资源名称采用以下格式：
users/{userId}/userEvents/{userEventId}