CloudEvents - JSON 事件格式

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

Eventarc 會透過 HTTP 要求，以 CloudEvents 格式將事件傳送至事件接收器。目的地目標 (例如 Workflows 服務) 會將事件轉換為 JSON 物件 (遵循 CloudEvents 規格)，並將事件當做工作流程執行階段引數傳遞至工作流程執行作業。

JSON 酬載格式

目的地服務會接收事件路由器傳送的事件，並將事件格式設為 CloudEvents 1.0.1 版的 JSON 事件格式，其中包含下列 CloudEvents 屬性：

屬性 說明 範例
資料 事件資料的酬載。 
{
  "subscription": "projects/my-project/subscriptions/my-sub",
  "message": {
    "attributes": {
      "attr1":"attr1-value"
    },
    "data": "aGVsbG8gd29ybGQ=",
    "messageId": "2070443601311540",
    "publishTime":"2021-02-26T19:13:55.749Z"
  }
}
datacontenttype 已傳遞的資料類型 application/json
id 活動的專屬 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 稽核記錄

執行階段引數是 JSON 物件，詳細說明 Cloud Audit Logs 事件。請參閱本文中的「常見事件範例」。在 JSON 物件中，您可以找到 resourceName、serviceName 和 methodName 值。詳情請參閱「決定 Cloud 稽核記錄的事件篩選器」。

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 bucket 名稱。
  • 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 結構定義目錄

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

常見活動

通訊協定緩衝區 (或 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 訊息觸發工作流程