处理 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 会按类型对活动进行分类。事件类型可帮助您过滤和仅接收您需要的类型的信息，并可让您以相同的方式处理类似的 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 应用可以开始接收成员资格事件。

使用 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 查询事件的 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 群组添加到聊天室。