本页简要介绍了 Google Workspace Events API，并说明了如何使用该 API 来订阅整个 Google Workspace 中的事件。
Google Workspace 事件代表 Google Workspace 资源发生了更改，例如创建、更新或删除了资源。 您可以使用 Google Workspace Events API 订阅 Google Workspace 资源并接收相关事件。
应用接收事件的方式
如需让应用接收 Google Workspace 事件，请使用 Google Workspace Events API 创建对 Google Workspace 资源的订阅。
以下示例介绍了 Google Workspace Events API 如何通过订阅向 Chat 应用提交事件：
- Chat 应用订阅 Google Chat 聊天室。
- Chat 聊天室发生更改。例如，聊天室中发布了一条新消息。
- Chat 向
Google Cloud Pub/Sub 中的主题提交事件，
该主题充当订阅的通知端点。该事件包含所发生更改的相关数据。例如，对于有关新消息的事件，该事件包含有关所创建
Message资源的详细信息。 - Chat 应用处理包含事件的 Google Cloud Pub/Sub 消息，并在必要时采取措施。
重要术语
Google Workspace Events API 中使用的常见术语包括：
- Google Workspace 事件
对 Google Workspace 资源的更改。事件使用 CloudEvents规范进行格式化，可以是 订阅事件或生命周期事件：
- 订阅事件
- 对您正在监控的 Google Workspace 资源的更改，例如 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 事件。 - 事件类型
- 您希望收到有关目标资源的哪些更改的通知。例如，如果您订阅了 Chat 聊天室，则可以选择是否接收有关该聊天室及其子资源（例如会员和消息）的事件。
- 通知端点
- Google Workspace 订阅接收事件的端点。Google Workspace Events API 支持 Google Cloud Pub/Sub 主题作为通知端点。如需详细了解如何使用 Google Cloud Pub/Sub，请参阅 Google Cloud Pub/Sub 文档。
- 载荷选项
- 您希望接收有关已更改资源的哪些事件数据。
受支持的 Google Workspace 事件
您的应用可以接收哪些事件取决于订阅的目标资源。下表显示了每个可能的目标资源支持的事件。
| 目标资源 | 支持的事件 |
|---|---|
| Chat 聊天室 |
|
| Chat 用户 |
|
| Google 云端硬盘文件或共享云端硬盘文件 |
|
| Google Meet 会议聊天室和用户 |
|
如需了解详情，请参阅以下指南：
Google Workspace 事件的结构
Google Workspace 事件遵循 CloudEvents 规范，这是一种描述事件数据的行业标准方式。Google Workspace 事件包含以下内容：
以下部分介绍了 Google Workspace 事件的属性和数据的结构。
CloudEvent 属性
Google Workspace 事件包含以下必需的 CloudEvents 属性：
| 属性 | 说明 | 示例 |
|---|---|---|
|
事件中传递的数据类型。 |
|
|
CloudEvent 的标识符。 |
|
|
事件的来源。对于 Google Workspace 事件，这是订阅的完整资源名称。 |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
此事件使用的 CloudEvents 规范版本。 |
|
|
发生事件的 Google Workspace 资源。 |
|
|
事件发生的时间戳，采用 RFC 3339 格式。 |
|
|
Google Workspace 事件的类型。 |
|
事件数据
事件数据是一个载荷，表示对订阅的目标资源（包括目标资源的子资源）的更改。在订阅中，您可以指定载荷是否包含有关已更改资源的数据，或者仅包含已更改资源的名称。
例如，如果您订阅了 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 Protocol Binding for CloudEvents。