CloudEvents 형식 - HTTP 프로토콜 바인딩

CloudEvents(cloudevents.io)는 이벤트 데이터를 일반적인 방식으로 설명할 수 있는 사양입니다. 이 사양은 CNCF(Cloud Native Computing Foundation)에 속하며 CNCF의 서버리스 작업 그룹별로 구성됩니다.

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 감사 로그

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 감사 로그 이벤트를 자세히 설명하는 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 프로토콜 버퍼
  • 생성된 JSON 스키마
  • 공개 JSON 스키마 카탈로그

클라이언트 라이브러리 링크도 포함됩니다.

일반 이벤트

프로토콜 버퍼(또는 protobuf)는 Eventarc에서 생성되는 이벤트 내의 데이터를 나타냅니다. CloudEvents의 프로토콜 버퍼는 머신 판독 가능 스키마로 제공되며, 데이터 유형의 라이브러리를 생성하고 이벤트를 더 쉽게 소비할 수 있게 해줍니다.

모든 특정 CloudEvent 유형에는 2개의 protobuf 메시지가 관련되어 있습니다.

  • 하나는 확장 속성을 포함하여 전체 CloudEvent를 나타내는 봉투 메시지입니다(예: AuditLogWrittenEvent).
  • data 메시지입니다(예: 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 메시지를 사용하여 워크플로 트리거

다음 단계

이벤트 경로에 대해 자세히 알아보기