CloudEvents - JSON 事件格式

CloudEvents (cloudevents.io) 是一种以通用方式描述事件数据的规范。该规范属于 Cloud Native Computing Foundation (CNCF)，并由 CNCF 的无服务器工作组整理。

Eventarc 通过 HTTP 请求以 CloudEvents 格式将事件传递给事件接收器。 目的地目标（例如 Workflows 服务）将事件转换为 JSON 对象（遵循 CloudEvents 规范），并将事件作为工作流运行时参数传递给工作流执行。

JSON 载荷格式

目标服务接收来自事件路由器的事件，并使用以下 CloudEvents 属性将事件格式设置为 CloudEvents 1.0.1 版 JSON 事件格式：

属性 说明 示例
数据 事件数据的载荷。 
{
  "subscription": "projects/my-project/subscriptions/my-sub",
  "message": {
    "attributes": {
      "attr1":"attr1-value"
    },
    "data": "aGVsbG8gd29ybGQ=",
    "messageId": "2070443601311540",
    "publishTime":"2021-02-26T19:13:55.749Z"
  }
}
数据类型 已传递的数据类型 application/json
id 事件的唯一标识符 2070443601311540
来源 事件的来源 //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion 此事件使用的 CloudEvents 规范版本 1.0
类型 事件数据的类型 google.cloud.pubsub.topic.v1.messagePublished
时间 事件生成时间，采用 RFC 3339 格式（可选） 2020-12-20T13:37:33.647Z

根据事件类型，载荷格式如下：

Cloud Audit Logs

运行时参数是详细说明 Cloud Audit Logs 事件的 JSON 对象。在本文档中，请参阅常见事件示例。 在 JSON 对象中，您可以找到 resourceName、serviceName 和 methodName 值。如需了解详情，请参阅确定 Cloud Audit Logs 的事件过滤条件。

google.cloud.audit.log.v1.written 类型的事件具有以下格式：

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//cloudaudit.googleapis.com/projects/PROJECT_ID/logs/data_access",
  "specversion": "1.0",
  "type": "google.cloud.audit.log.v1.written",
  "time": "EVENT_GENERATION_TIME",
  "dataschema": "https://googleapis.github.io/google-cloudevents/jsonschema/google/events/cloud/audit/v1/LogEntryData.json",
  "methodName": "jobservice.jobcompleted",
  "resourceName": "projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1",
  "serviceName": "bigquery.googleapis.com",
  "subject": "bigquery.googleapis.com/projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1"
}
  • EVENT_DATA：JSON 格式的已解码消息内容。如需了解详情，请参阅本文档中的常见事件部分。
  • MESSAGE_ID、EVENT_GENERATION_TIME、：系统生成。
  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • dataschema、methodName、resourceName、serviceName、subject：特定于事件类型的属性。

Cloud Storage

运行时参数是对 Cloud Storage 的更改。在 data 字段中，您可以找到 Cloud Storage 存储桶中的更改。在本文档中，请参阅常见事件示例。

google.cloud.storage.object.v1.finalized 类型的事件具有以下格式：

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json",
  "id": "MESSAGE_ID",
  "source": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME",
  "specversion": "1.0",
  "type": "google.cloud.storage.object.v1.finalized",
  "time": "EVENT_GENERATION_TIME",
  "subject": "objects/my-file.txt"
}
  • EVENT_DATA：JSON 格式的已解码消息内容。如需了解详情，请参阅本文档中的常见事件部分。
  • MESSAGE_ID、EVENT_GENERATION_TIME、：系统生成。
  • BUCKET_NAME：要更新的 Cloud Storage 存储桶的名称。
  • subject：特定于事件类型的属性。

Pub/Sub

运行时参数是 Pub/Sub 推送消息。在 data 字段中，您可以找到以 Base64 编码的字符串形式的消息。在本文档中，请参阅常见事件示例。

google.cloud.pubsub.topic.v1.messagePublished 类型的事件具有以下格式：

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//pubsub.googleapis.com/TOPIC_NAME",
  "specversion": "1.0",
  "type": "google.cloud.pubsub.topic.v1.messagePublished",
  "time": "EVENT_GENERATION_TIME"
}
  • EVENT_DATA：JSON 格式的已解码消息内容。如需了解详情，请参阅本文档中的常见事件部分。
  • MESSAGE_ID、EVENT_GENERATION_TIME、：系统生成。
  • TOPIC_NAME：事件发布到的 Pub/Sub 主题名称。

开源代码库

所有事件的 HTTP 正文结构都位于 CloudEvents GitHub 代码库中。

该代码库包含以下内容，帮助您了解和使用采用您的编程语言的 CloudEvents 数据：

  • 用于 CloudEvents 数据载荷的 Google Protocol Buffers
  • 生成的 JSON 架构
  • 公开 JSON 架构目录

还包含指向客户端库的链接。

常见事件

Protocol Buffer（或 protobuf）表示 Eventarc 生成的事件中的数据。适用于 CloudEvent 的 Protocol Buffer 以机器可读的架构提供，允许创建数据类型库并更轻松地使用事件。

以下是两个与任何给定 CloudEvent 类型相关的 protobuf 消息：

  • 表示完整 CloudEvent 的信包消息，包括任何扩展特性；例如 AuditLogWrittenEvent。
  • 数据消息；例如 LogEntryData 或 StorageObjectData。
许多 CloudEvent 类型都可以使用相同的数据消息。例如，与 Cloud Storage 对象关联的每个事件都使用 StorageObjectData 作为数据消息。每个信包消息通过 proto 注释指定与之关联的 CloudEvent 类型。如需了解详情，请参阅 protobuf 消息与 CloudEvent 类型之间的关系。

下表详细说明了一些常见事件的组成部分：

Cloud Audit Logs

Proto 文件google/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
信包消息google.events.cloud.audit.v1.AuditLogWrittenEvent
数据消息google.events.cloud.audit.v1.LogEntryData
事件类型
（写入审核日志条目时）		 google.cloud.audit.log.v1.written
事件扩展
  • serviceName
  • methodName
  • resourceName
请参阅使用 Cloud Audit Logs 的事件类型列表。
示例 Pub/Sub 审核日志
BigQuery 审核日志
更多信息 为 Cloud Audit Logs 事件创建 Eventarc 触发器
确定 Cloud Audit Logs 的事件过滤条件
具有审核日志的 Google Cloud 服务

Cloud Storage

Proto 文件 google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
信包消息google.events.cloud.storage.v1.ObjectFinalizedEvent
google.events.cloud.storage.v1.ObjectArchivedEvent
google.events.cloud.storage.v1.ObjectDeletedEvent
google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
数据消息google.events.cloud.storage.v1.StorageObjectData
资源 Objects
事件类型
 请参阅直接事件类型列表。
示例简单
复杂
更多信息 为 Cloud Storage 事件创建 Eventarc 触发器
在 Cloud Run 服务中接收来自 Cloud Storage 的事件

Firestore

Proto 文件 google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
信包消息google.events.cloud.firestore.v1.DocumentCreatedEvent
google.events.cloud.firestore.v1.DocumentUpdatedEvent
google.events.cloud.firestore.v1.DocumentDeletedEvent
google.events.cloud.firestore.v1.DocumentWrittenEvent
数据消息google.events.cloud.firestore.v1.DocumentEventData
资源 Document
事件类型 请参阅直接事件类型列表。
示例简单
复杂
更多信息 为 Firestore 事件创建 Eventarc 触发器
使用 Eventarc 和 Firestore 创建事件驱动型架构
通过 Cloud Functions 扩展以处理因 Firestore 更改而触发的事件。

Pub/Sub

Proto 文件 google/events/cloud/pubsub/v1/events.proto
google/events/cloud/pubsub/v1/data.proto
信包消息google.events.cloud.pubsub.v1.MessagePublishedEvent
数据消息google.events.cloud.pubsub.v1.MessagePublishedData
资源 PubsubMessage
事件类型
（发布 Pub/Sub 消息时）		 google.cloud.pubsub.topic.v1.messagePublished
示例 文本
更多信息 使用 Pub/Sub 消息接收 Cloud Run 服务中的事件
使用 Pub/Sub 消息触发工作流