使用 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 应用中的资源，例如 Google Chat 聊天室。
2. 您订阅的资源发生变化。
3. Google Workspace 应用会向 Google Cloud Pub/Sub 中的主题传递事件，以充当您的 Google Workspace 订阅的通知端点。该事件包含有关资源中发生了什么更改的数据。
4. 您的应用会处理包含该事件的 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 聊天室	//chat.googleapis.com/spaces/SPACE_ID	消息 会员福利 回应 空间 有关详情，请参阅订阅 Google Chat 事件。	授权订阅的 Google Chat 用户必须通过其 Google Workspace 或 Google 帐号成为聊天室成员。
Google Chat 用户	//cloudidentity.googleapis.com/users/USER_ID	会员福利 有关详情，请参阅订阅 Google Chat 事件。	订阅仅接收授权订阅的用户的相关事件。用户不能代表其他用户对订阅项目进行授权。
Google Meet
Google Meet 会议空间	//meet.googleapis.com/spaces/SPACE_ID	联盟 参与者会话 录音内容 解说词 有关详情，请参阅订阅 Google Meet 活动。
Google Meet 用户	//cloudidentity.googleapis.com/users/USER_ID	联盟 参与者会话 录音内容 解说词 有关详情，请参阅订阅 Google Meet 活动。	订阅会收到与会议空间相关的事件，用户属于以下一种情况： 会议聊天室的所有者。 与会议空间关联的 Google 日历活动的组织者。

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 资源的载荷。

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

注意 ：只有 Chat 事件支持包含资源数据。

• 包含资源数据：包含已更改资源的部分或全部字段。如果您选择包含资源数据，则订阅时长最长为 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 消息中指定 CloudEvents，请参阅适用于 CloudEvents 的 Google Cloud Pub/Sub 协议绑定。

相关主题

• 订阅 Google Chat 事件
• Google Workspace 订阅的生命周期事件
• 选择 Google Workspace Events API 范围
• 创建 Google Workspace 订阅