使用 Google Workspace Events API 订阅活动

本页简要介绍了 Google Workspace Events API，并说明了如何使用该 API 来订阅整个 Google Workspace 中的事件。

Google Workspace 事件代表 Google Workspace 资源发生了更改，例如创建、更新或删除了资源。您的应用可以订阅 Google Workspace 资源，接收您感兴趣的相关事件信息。

应用如何接收事件

如需让您的应用接收 Google Workspace 事件，您可以使用 Google Workspace Events API 创建 Google Workspace 资源订阅。

一张插图，展示了 Google Workspace Events API 如何提交事件。
图 1.Google Workspace Events API 如何向 Chat 应用提交事件的示例。

在以下示例中，Google Workspace Events API 通过订阅向 Google Chat 应用提交事件的方式如下：

  1. Chat 应用订阅 Chat 聊天室。
  2. Chat 聊天室会发生变化。例如，在聊天室中发布了新消息。
  3. Chat 向 Google Cloud Pub/Sub 中的主题提交事件，它充当订阅的通知端点。该事件包含所发生变化的相关数据。例如，对于与新消息相关的事件，该事件包含有关创建的 Message 资源的详细信息。
  4. Chat 应用会处理包含事件的 Google Cloud Pub/Sub 消息，并在必要时采取措施。

重要术语

以下是 Google Workspace Events API 中常用的术语列表：

Google Workspace 事件

对 Google Workspace 资源所做的更改。事件的格式使用 CloudEvents 规范，可以是订阅事件或生命周期事件：

订阅事件
您所监控的 Google Workspace 资源发生的变化，例如 Google Chat 聊天室中收到新消息。您可以指定希望收到有关发生更改的资源的详细程度。有关详情，请参阅 Google Workspace 事件的结构。
生命周期事件
与您的 Google Workspace 订阅相关的事件。生命周期事件会通知您订阅存在的问题和状态，以免您错过订阅事件。默认情况下，您的订阅始终会收到生命周期事件。如需了解详情，请参阅 Google Workspace 订阅的生命周期事件。
Google Workspace 订阅

用于监控 Google Workspace 应用中的资源的命名实体。订阅由 Subscription 资源表示。订阅由以下信息定义：

目标资源
您要监控的 Google Workspace 资源。此资源在 Google Workspace 订阅的 targetResource 字段中表示。每个订阅只能监控一个资源。如需了解 Google Workspace Events API 支持哪些 Google Workspace 资源，请参阅受支持的 Google Workspace 事件。
事件类型
您希望针对目标资源收到通知的更改类型。例如，如果您订阅了 Google Chat 聊天室，则可以选择是否接收与该聊天室及其子资源（例如成员资格和消息）相关的事件。
通知端点
Google Workspace 订阅接收事件的端点。Google Workspace Events API 支持将 Google Cloud Pub/Sub 主题用作通知端点。如需详细了解如何使用 Google Cloud Pub/Sub，请参阅 Google Cloud Pub/Sub 文档。
载荷选项
您希望接收的有关更改资源的事件数据。

支持的 Google Workspace 事件

您的应用可以接收哪些事件取决于订阅的目标资源。下表显示了每个可能的目标资源支持的事件。

目标资源 支持的事件
Google Chat 聊天室
  • 消息
  • 会员
  • 回应
  • 空格
Google Chat 用户
  • 会员
Google Meet 会议空间
  • 联盟
  • 参与者会话
  • 录音内容
  • 解说词
Google Meet 用户
  • 联盟
  • 参与者会话
  • 录音内容
  • 解说词

如需了解详情，请参阅以下指南：

Google Workspace 事件的结构

Google Workspace 事件遵循 CloudEvents 规范，该规范是一种描述事件数据的行业标准方式。Google Workspace 事件包含以下各项：

  • CloudEvent 的属性。
  • 与因事件而发生更改的 Google Workspace 资源相关的数据

以下部分介绍了 Google Workspace 事件的属性和数据结构。

CloudEvent 属性

Google Workspace 事件包含以下必需的 CloudEvents 属性：

属性 说明 示例

datacontenttype

事件中传递的数据类型。

application/json

id

CloudEvent 的标识符。

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

事件的来源。对于 Google Workspace 事件，这是订阅的完整资源名称。 //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

此事件使用的 CloudEvents 规范版本。

1.0

subject

发生事件的 Google Workspace 资源。

//chat.googleapis.com/spaces/AAAABBBBBBB

time

事件发生的时间戳，采用 RFC 3339 格式。

2023-09-07T21:37:36.260127Z

type

Google Workspace 事件的类型。

google.workspace.chat.message.v1.created

事件数据

事件数据是一种载荷，表示订阅的目标资源（包括目标资源的子资源）发生了变化。在订阅中，您可以指定是希望载荷包含有关已更改资源的数据，还是仅包含已更改资源的名称。

例如，如果您订阅了某个 Chat 聊天室，则可以接收有关该聊天室中新消息的事件。对于与新消息相关的事件，事件数据包含包含所创建 Chat spaces.message 资源的载荷。

创建订阅时，您可以指定应用收到的事件中包含多少资源数据：

  • 包含资源数据：包含更改的资源的部分或全部字段。如果您选择包含资源数据，订阅时长最多限制为 4 小时；如果您使用域名级委托，则最多限制为 24 小时。
  • 排除资源数据：仅包含所更改资源的名称。订阅时长最多为 7 天。如需获取事件的详细信息，您可以使用资源名称查询资源。

事件数据的这些选项显示在订阅的 payloadOptions 字段中。

将事件作为 Google Cloud Pub/Sub 消息

Google Workspace Events API 订阅使用 Google Cloud Pub/Sub 主题作为接收 Google Workspace 事件的通知端点。这些事件会编码为 Google Cloud Pub/Sub 消息。您的应用可以处理 Google Cloud Pub/Sub 消息，以执行操作或响应事件。

以下示例展示了一个 Google Cloud Pub/Sub 消息，其中包含与 Chat 聊天室中更新的消息相关的事件：

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

请注意以下字段：

  • attributes：CloudEvent 的属性，包括事件类型。在本例中，该事件与聊天室中更新的消息有关。
  • data：事件数据，其中包含更新后的 spaces.message 资源的详细信息，格式为 base64 编码的字符串。
  • messageId：Google Cloud Pub/Sub 消息的标识符。

如需详细了解如何在 Google Cloud Pub/Sub 消息中指定 CloudEvent，请参阅 适用于 CloudEvent 的 Google Cloud Pub/Sub 协议绑定。