CloudEvents 格式 - HTTP 通訊協定繫結

CloudEvents (cloudevents.io) 是一種規格，可採用通用方式描述事件資料。這項規格由雲端原生運算基金會 (CNCF) 負責，並由 CNCF 的無伺服器工作組管理。

Eventarc 會透過 HTTP 要求，以 CloudEvents 格式將事件傳送至事件接收器。

HTTP 要求標頭

目標服務會以 HTTP POST 要求的形式，從事件路由器接收事件，這些要求會根據 CloudEvents 1.0 版的 HTTP 通訊協定繫結規格格式化。每個 HTTP 要求都包含事件專屬的標頭和主體，並傳送至服務的根網址路徑 (/)。

除了其他 HTTP 標頭外，所有事件都有下列 CloudEvents HTTP 標頭：

標頭 說明 範例
ce-id 活動的專屬 ID 1096434104173400
ce-source 識別事件來源 //pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion 這個事件使用的 CloudEvents 規格版本 1.0
ce-type 事件資料類型 google.cloud.pubsub.topic.v1.messagePublished
ce-time 事件產生時間，採用 RFC 3339 格式 (選填) 2020-12-20T13:37:33.647Z

HTTP 酬載格式

Cloud 稽核記錄

google.cloud.audit.log.v1.written 類型的事件格式如下：

標頭

ce-specversion: 1.0
ce-type: google.cloud.audit.log.v1.written
ce-source: //SERVICE_NAME/projects/PROJECT_ID
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • SERVICE_NAME：發出事件的服務所用 Google API URI；例如，BigQuery 事件的 URI 為 bigquery.googleapis.com。
  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • MESSAGE_ID、PUBLISH_TIME、CONTENT_LENGTH： 系統自動產生。

內文

酬載是詳細說明 Cloud 稽核記錄事件的 JSON 物件。您可以在 protoPayload 中找到 resourceName、serviceName 和 methodName 值。詳情請參閱「決定 Cloud 稽核記錄的事件篩選器」。

Pub/Sub

google.cloud.pubsub.topic.v1.messagePublished 類型的事件格式如下：

標頭

ce-specversion: 1.0
ce-type: google.cloud.pubsub.topic.v1.messagePublished
ce-source: //pubsub.googleapis.com/TOPIC
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • TOPIC：事件發布至其中的 Pub/Sub 主題。
  • MESSAGE_ID、PUBLISH_TIME、CONTENT_LENGTH： 系統自動產生。

內文

酬載是 Pub/Sub 推送訊息。您可以在 data 欄位中找到以 Base64 編碼字串形式呈現的訊息。請參閱本文中的範例。

開放原始碼存放區

所有事件的 HTTP 內文結構都可在 CloudEvents GitHub 存放區中找到。

這個存放區包含下列項目，可協助您瞭解及使用所選程式語言的 CloudEvents 資料：

  • 適用於 CloudEvents 資料酬載的 Google Protocol Buffers
  • 產生的 JSON 結構定義
  • 公開的 JSON 結構定義目錄

同時也會提供用戶端程式庫的連結。

常見活動

通訊協定緩衝區 (或 protobuf) 代表 Eventarc 產生的事件中的資料。CloudEvents 的通訊協定緩衝區以機器可讀取的結構定義形式提供，可建立資料型別程式庫，方便使用事件。

與任何 CloudEvent 類型相關的 protobuf 訊息有兩種：

  • 代表完整 CloudEvent 的封包訊息，包括任何擴充屬性，例如 AuditLogWrittenEvent。
  • 資料訊息，例如 LogEntryData 或 StorageObjectData。
許多 CloudEvent 類型可使用相同的資料訊息。舉例來說，與 Cloud Storage 物件相關聯的每個事件都會使用 StorageObjectData 做為資料訊息。每個封裝訊息都會透過 Proto 註解，指定與其相關聯的 CloudEvent 型別。詳情請參閱「protobuf 訊息和 CloudEvent 類型之間的關係」。

下表詳細列出一些常見事件的元件：

Cloud 稽核記錄

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 稽核記錄支援的事件類型。
範例 Pub/Sub 稽核記錄
BigQuery 稽核記錄
更多資訊 為 Cloud 稽核記錄事件建立 Eventarc 觸發條件
決定 Cloud 稽核記錄的事件篩選器
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 Run 函式擴充功能，處理因 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 訊息觸發工作流程

後續步驟

進一步瞭解事件路徑。