处理 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 应用收到的事件类型：

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 应用可以开始接收成员资格事件。

使用 Google Workspace Events API 订阅事件的聊天应用。
图 2.聊天应用使用 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.workspace.chat.spaces.v1.updated）。
  • 要接收会员活动，用户必须是聊天室的直接成员。如果通过 Google 群组间接添加、更新或移出聊天室，则订阅不会收到这些成员资格事件。如需了解 Google 群组成员资格的运作方式，请参阅将 Google 群组添加到聊天室。