本页介绍了 Google Chat 应用如何接收和响应 Google Chat 中的事件。
Google Chat 事件表示 Chat 中的活动或更改,例如聊天室中的新消息。您的 Chat 应用可以借助事件来了解所发生的情况,然后采取相应措施或以对用户有意义的方式作出响应。
以下示例说明了如何使用事件:
- 监控并响应聊天室中的新消息,例如检查关键字词或短语。
- 在用户加入聊天室时向他们发送欢迎消息,说明聊天室指南或分享有关如何有效使用 Chat 应用的提示。
- 跟踪和分析 Chat 活动。例如,发送关于新会员或者获得最多回应或回复的消息的每月报告。
- 跨即时通讯平台进行沟通。例如,用户无需退出 Chat,即可与其他即时通讯平台上的用户互发消息。
事件的运作方式
每当 Google Chat 中发生某个事件时,系统都会创建、更新或删除 Google Chat API 资源。Chat 使用事件向您的 Chat 应用传送发生的活动类型以及受影响的 Chat API 资源。
Chat 会按类型对活动进行分类。事件类型可帮助您过滤和仅接收您需要的类型的信息,并可让您以相同的方式处理类似的 activity。
下表显示了 Chat 中的 activity 对相关 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 群组向聊天室间接添加、更新或移除用户,则订阅不会接收这些成员资格事件。如需了解 Google 群组成员资格的工作原理,请参阅将 Google 群组添加到聊天室。
相关主题
- Google Workspace Events API 概览
- 创建订阅
- 获取有关 Google Chat 聊天室活动的详细信息
- 列出 Google Chat 聊天室中的活动
- 如需查看有关如何使用事件的示例,请参阅根据与 Gemini AI Chat 应用的 Chat 对话回答问题教程,或 Codelab 中的“使用 Gemini 构建 Google Chat 应用”中的“问题管理”Chat 应用的包容性帮助功能。