使用 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"
    }
}

请注意以下字段:

  • attributesCloudEvent 的属性,包括 事件类型。在本示例中,该事件与 空间。
  • data事件数据,包含更新后的事件的详细信息 spaces.message 资源,格式为 Base64 编码的字符串。
  • messageId:Google Cloud Pub/Sub 消息的标识符。

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