使用 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 资源。 此资源在targetResource Google Workspace 订阅。每个订阅只能 监控一项资源如要查看 Google Workspace Events API 支持，请参阅 支持的 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 事件包含以下内容：

以下部分介绍了 属性和数据的结构 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 中指定 CloudEvents 消息，请参阅适用于 CloudEvents 的 Google Cloud Pub/Sub 协议绑定。