CloudEvents 形式 - HTTP プロトコル バインディング

CloudEvents（cloudevents.io）は、イベントデータを一般的な方法で記述するための仕様です。この仕様は、Cloud Native Computing Foundation（CNCF）の Serverless Working Group によって編成されています。

Eventarc は、HTTP リクエストを使用して CloudEvents 形式でイベント レシーバにイベントを配信します。

HTTP リクエスト ヘッダー

ターゲット サービスは、CloudEvents バージョン 1.0 HTTP プロトコル バインディング仕様の形式で HTTP POST リクエストとしてイベント ルーターからイベントを受信します。各 HTTP リクエストにはイベント固有のヘッダーと本文が含まれ、サービスのルート URL パス（/）に送信されます。

他の HTTP ヘッダーに加えて、すべてのイベントに次の CloudEvents HTTP ヘッダーがあります。

ヘッダー 説明 例
ce-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 Audit Logs

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 のイベントの場合は bigquery.googleapis.com です。
  • PROJECT_ID: Google Cloud プロジェクト ID。
  • MESSAGE_ID、PUBLISH_TIME、CONTENT_LENGTH: システム生成。

本文

ペイロードは、Cloud Audit Logs イベントの詳細を示す JSON オブジェクトです。protoPayload には、resourceName、serviceName、methodName の値があります。詳細については、Cloud Audit Logs のイベント フィルタの決定をご覧ください。

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 の push メッセージです。data フィールドには、メッセージが Base64 でエンコードされた文字列として格納されます。このドキュメントの例をご覧ください。

オープンソース リポジトリ

すべてのイベントの HTTP 本文の構造は、CloudEvents GitHub リポジトリで入手できます。

リポジトリには、CloudEvents データを理解して、お使いのプログラミング言語で使用する際に役立つものが用意されています。

  • CloudEvents データ ペイロード用の Google Protocol Buffer
  • 生成された JSON スキーマ
  • 公開 JSON スキーマ カタログ

クライアント ライブラリへのリンクも含まれます。

一般的なイベント

プロトコル バッファ（protobuf）は、Eventarc によって生成されたイベント内のデータを表します。CloudEvents のプロトコル バッファは機械で読み取り可能なスキーマとして提供されます。これにより、データタイプのライブラリを作成し、イベントを容易に使用できるようになります。

CloudEvent のタイプに関連する protobuf メッセージは 2 つあります。

  • 拡張属性を含む 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 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 メッセージを使用してワークフローをトリガーする

次のステップ

イベントルートの詳細を確認する。