处理 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 订阅事件的 Chat 应用。
图 2. Chat 应用通过使用 Google Workspace Events API 的订阅接收成员资格事件。

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

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

查询近期的会员活动

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

使用 Chat API 查询事件的聊天应用。
图 3. Chat 应用通过使用 Chat API 查询聊天室事件来接收近期的成员资格事件。

在图 3 中，聊天应用在所有会员活动发生后调用 Chat API spaces.spaceEvents.list() 方法，并过滤查询以获取新增、更新和已删除的会员事件。Chat API 会返回一个 spaceEvent 资源列表，其中包含每次成员资格变更的信息。然后，Chat 应用可以根据最近的活动进行处理或做出响应，例如发布一条每周消息，其中包含聊天室过去 7 天的成员活动摘要。

如需使用 Chat API 查询活动，请参阅列出 Google Chat 聊天室中的活动。

限制
  • 对于用户订阅，有关私信或未命名群聊中新成员的事件 (google.workspace.chat.membership.v1.created) 仅在发布第一条消息后触发。
  • 如需接收会员事件，用户必须是相应空间的直接成员。如果用户是通过 Google 群组间接添加到聊天室、更新聊天室或从聊天室中移除的，订阅不会收到这些成员资格事件。如需了解 Google 群组成员资格的运作方式，请参阅向聊天室添加 Google 群组。