本页面介绍了 Google Chat 应用如何在 Google Chat 中接收和响应事件。
Google Chat 事件表示 Chat 中的活动或更改,例如聊天室中的新消息。您的 Chat 应用可以使用事件来了解发生了什么,并对用户采取有意义的行动或响应。
下面列举了一些示例来说明如何使用事件:
- 监控和回复聊天室中的新消息,例如检查关键词或短语。
- 在用户加入聊天室时向其发送欢迎消息,以说明聊天室准则或分享有关如何有效使用 Chat 应用的提示。
- 跟踪和分析 Chat 活动。例如,发送有关新成员或获得最多回应或回复的消息的每月报告。
- 跨消息传递平台进行通信。例如,用户可以在其他即时通讯平台上发送和接收来自用户的消息,而无需离开 Chat。
事件的运作方式
每当 Google Chat 中发生事件时,系统都会创建、更新或删除 Google Chat API 资源。Chat 使用事件向 Chat 应用传递有关已发生的活动类型及受影响的 Chat API 资源的信息。
Chat 会按类型对活动进行分类。事件类型可帮助您仅过滤和接收所需信息类型,并让您以相同的方式处理类似的活动。
下表显示了 Chat 中的活动如何影响相关的 Chat API 资源,以及 Chat 应用收到的事件类型:
Activity | 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 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 聊天室中的事件。
限制
-
对于用户的订阅,私信或未命名的群聊中的新成员事件 (
google.workspace.chat.membership.v1.created
) 仅在第一条消息发布后触发。 - 对聊天室聊天记录所做的更改不会触发聊天室更新事件(事件类型:
google.workspace.chat.spaces.v1.updated
)。 - 要接收会员活动,用户必须是聊天室的直接成员。如果通过 Google 群组间接添加、更新或移出聊天室,则订阅不会收到这些成员资格事件。如需了解 Google 群组成员资格的运作方式,请参阅将 Google 群组添加到聊天室。
相关主题
- Google Workspace Events API 概览
- 创建订阅
- 获取有关 Google Chat 聊天室活动的详细信息
- 列出 Google Chat 聊天室中的活动
- 如需查看如何使用事件的示例,请参阅通过 Gemini AI Chat 应用根据 Chat 对话回答问题教程或使用 Gemini 构建适用于 Google Chat 的应用 Codelab 中问题管理 Chat 应用的包容性帮助功能。