使用 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 通过订阅向 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 云端硬盘事件
• 订阅 Google Meet 事件

Google Workspace 活动的结构

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

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

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

CloudEvent 属性

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

事件数据

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

例如，如果您订阅了某个 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 消息中指定 CloudEvents，请参阅 Google Cloud Pub/Sub CloudEvents 协议绑定。

相关主题

• 选择 Google Workspace Events API 范围
• 创建 Google Workspace 订阅