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 稽核記錄 事件。請參閱本文的「常見事件範例」。 在 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 bucket 的變更。請參閱本文「常見事件範例」一節。

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 的 Protocol Buffers 以機器可讀取的結構定義形式提供，方便建立資料類型程式庫，並輕鬆使用事件。

針對任何 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 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 訊息觸發工作流程