CloudEvents - JSON 이벤트 형식

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

Eventarc는 HTTP 요청을 통해 CloudEvents 형식으로 이벤트 수신자에 이벤트를 전달합니다. 예를 들어 Workflows 서비스와 같은 대상은 이벤트를 CloudEvents 사양에 따라 JSON 객체로 변환하고 이벤트를 워크플로 실행에 워크플로 런타임 인수로 전달합니다.

JSON 페이로드 형식

대상 서비스는 이벤트 라우터에서 이벤트를 수신하고 다음 CloudEvents 속성을 사용해서 CloudEvents 버전 1.0.1의 JSON 이벤트 형식으로 이벤트 형식을 지정합니다.

속성 설명 예시
data 이벤트 데이터의 페이로드입니다. 

{
  "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 이벤트의 고유 식별자입니다. 2070443601311540
source 이벤트의 소스입니다. //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion 이 이벤트에 사용되는 CloudEvents 사양 버전입니다. 1.0
type 이벤트 데이터의 유형입니다. google.cloud.pubsub.topic.v1.messagePublished
time RFC 3339 형식의 이벤트 생성 시간입니다(선택사항). 2020-12-20T13:37:33.647Z

이벤트 유형에 따라 페이로드 형식은 다음과 같습니다.

Cloud 감사 로그

런타임 인수는 Cloud 감사 로그 이벤트를 자세히 설명하는 JSON 객체입니다. 이 문서에서 일반적인 이벤트 예시를 참조하세요. 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 버킷의 이름입니다.
  • 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 프로토콜 버퍼
  • 생성된 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 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 메시지를 사용하여 워크플로 트리거