使用 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 资源的订阅。

图 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 聊天室	如需订阅特定聊天室，请执行以下操作： //chat.googleapis.com/spaces/SPACE_ID 如需订阅用户已加入的所有聊天室，请执行以下操作： //chat.googleapis.com/spaces/-	信息 会员福利 回应 空格 有关详情，请参阅订阅 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 消息中指定 CloudEvent，请参阅适用于 CloudEvents 的 Google Cloud Pub/Sub 协议绑定。

相关主题

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