处理 Google Chat 中的活动

本页介绍了 Google Chat 应用如何接收和响应 Google Chat 中的事件。

Google Chat 事件表示 Chat 中的活动或更改，例如聊天室中收到新消息。Chat 应用可以使用事件来了解所发生的情况，并采取行动或以有意义的方式回应用户。

以下一些示例展示了事件的使用方法：

  • 监控和回复聊天室中的新消息，例如检查关键字或词组。
  • 在用户加入聊天室时向其发送欢迎消息，说明聊天室准则或分享有关如何有效使用 Chat 应用的技巧。
  • 跟踪和分析 Chat 活动。例如，发送有关新成员或获得最多回应或回复的消息的月度报告。
  • 跨消息传递平台进行沟通。例如，用户无需离开 Chat，即可与其他即时通讯平台上的用户发送和接收消息。

事件的运作方式

每当 Google Chat 中发生任何情况时，系统都会创建、更新或删除 Google Chat API 资源。Chat 使用事件向 Chat 应用传递有关发生的活动类型和受影响的 Chat API 资源的信息。

向 Google Chat 聊天室发布消息如何触发事件的示例。
图 1.用户在 Chat 聊天室中发消息，系统会创建 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 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 应用即可开始接收会员事件。

使用 Google Workspace Events API 订阅事件的聊天应用。
图 2. Chat 应用使用 Google Workspace Events API 通过订阅接收成员事件。

在图 2 中，Chat 应用已订阅该聊天室，因此每当聊天室中的成员资格发生变化时，该应用都会收到事件。然后，Chat 应用就可以处理或实时响应任何活动，例如向加入聊天室的成员发布私密欢迎消息。

如需了解如何使用 Google Workspace Events API 创建订阅，请参阅 Google Workspace Events API 文档。

查询近期的会员活动

Chat 应用可以调用 Chat API 来列出与会员活动相关的近期聊天室事件，而不是在事件发生时接收这些事件。

使用 Chat API 查询事件的 Chat 应用。
图 3. 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 群组。