CloudEvents JSON 본문 검수CloudEvents data_base64 차이CloudEvents datacontenttype 생략

CloudEvents JSON 본문 검수, data와 data_base64는 어떻게 읽을까

CloudEvents JSON 본문의 객체·문자열·바이트를 검수합니다. 명시적 null과 필드 생략, data와 data_base64가 함께 온 경우도 가상 표본 8건으로 대조합니다.

이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스

발행 ·알파카랩스

CloudEvents 구조화 JSON에서 JSON 형식의 data는 값을 그대로 읽고, data_base64는 바이트로 복원합니다. 두 필드가 함께 있으면 형식 위반입니다.

2026년 11월 15일 기준입니다. 수신기는 HTTP 헤더에서 이벤트 전체가 구조화 JSON인지 확인한 다음, 이벤트 안에서 업무 데이터를 꺼냅니다. 이 두 단계에 각각 기대 타입을 적어 두면 JSON 객체가 문자열로 전달되거나, 파일 바이트가 문자로 바뀌는 문제를 업무 처리 전에 확인할 수 있습니다.

바깥 Content-Type과 안쪽 datacontenttype은 무엇을 설명할까?#

HTTP의 Content-Type이 application/cloudevents+json이면 이벤트 속성과 업무 데이터가 한 JSON 문서에 들어갑니다. 그 문서 안의 datacontenttype은 업무 데이터 자체의 형식을 설명합니다. 아래 가상 이벤트에서 업무 데이터는 JSON 객체입니다. 문서 태그가 v1.0.2여도 이벤트의 specversion 값은 1.0입니다. CloudEvents HTTP 바인딩

{
  "specversion": "1.0",
  "id": "sample-1",
  "source": "/orders",
  "type": "example.order.received",
  "datacontenttype": "application/json",
  "data": {"orderId": "A"}
}

업무 데이터가 JSON 형식일 때 data가 문자열이면 문자열 그대로 전달합니다. 그 문자열의 내용이 JSON 객체처럼 보여도 이벤트를 해석하는 단계에서 두 번째 JSON 파싱을 하지 않습니다. JSON 계열의 미디어 타입에는 application/json과 같이 하위 유형이 json인 경우와 +json으로 끝나는 경우가 포함됩니다. 형식을 지정하지 않은 data는 이 검수에서 application/json으로 해석하는 규격의 기본 권고를 따릅니다. CloudEvents JSON 본문 규칙

수신기가 어떤 타입을 넘겨야 할까?#

먼저 두 필드의 존재 여부를 확인합니다. data_base64가 있으면 Base64를 바이트로 복원하고, data가 있으면 안쪽 미디어 타입에 따라 JSON 값 또는 인코딩된 문자열로 읽습니다. 두 필드가 모두 없는 경우와 data에 null이 들어 있는 경우는 별도 상태로 전달합니다.

가상 입력내부 미디어 타입수신 확인
data에 주문 객체application/json주문 객체가 전달됨
data에 객체처럼 보이는 문자열application/json문자열이 전달됨
data에 주문 객체생략기본 권고에 따라 주문 객체가 전달됨
data에 평문text/plain내용 문자열이 전달됨
data_base64에 QQ==생략A에 해당하는 바이트가 복원됨
data에 nullapplication/json명시적 null이 기록됨
두 본문 필드 모두 생략생략본문 없음이 기록됨
data에 null, data_base64에 QQ==생략두 필드가 함께 있어 형식 오류로 분류
가상 입력 8건의 수신 판정입니다. Python 표준 라이브러리로 JSON 타입과 Base64 바이트, 필드 존재 여부를 대조했습니다.

표본마다 파서가 읽은 타입과 업무 앱이 실제로 받은 타입을 함께 기록합니다. 예를 들어 주문 객체를 기대하는 소비자에게 JSON 문자열이 전달되면, 이벤트 형식 검수를 통과하더라도 업무 앱에서는 입력 계약 오류입니다. 웹훅 본문이 서명된 바이트와 일치하는지 확인하는 절차는 웹훅 본문 무결성 검수, 여러 항목의 수신 완료를 판정하는 절차는 OpenAPI NDJSON 검수에서 다룹니다.

수신 파서에서 업무 처리까지 어디를 확인할까?#

바이트를 복원한 뒤 파일이나 JSON으로 추가 해석할 수 있는지는 본문 형식과 소비자 계약에 달려 있습니다. 안쪽 미디어 타입이 없으면 Base64 경로에서는 바이트까지만 기대값으로 둡니다. 반면 data에서 적용되는 암묵적 JSON 형식을 다른 바인딩으로 옮길 때는, 해당 형식이 유지되도록 application/json을 명시하라는 규격의 권고를 확인합니다.

SDK가 명시적 null과 누락을 같은 값으로 넘긴다면 원본 구조화 JSON에서 필드 존재 여부를 확인합니다. 업무 앱에도 둘의 차이가 필요하다면 변환 뒤까지 확인할 수 있는 테스트를 둡니다. 이미 HTTP 바이너리 모드로 전달하는 구간은 헤더에 이벤트 속성이 있고 메시지 본문에는 업무 데이터가 들어가므로 그 바인딩의 인수표로 확인합니다.

출처와 적용 범위#

2025년 8월 19일자 태그 커밋의 CloudEvents v1.0.2 JSON 형식과 HTTP 바인딩을 2026년 11월 15일 확인했습니다. Microsoft의 Azure Event Grid 문서는 CloudEvents 1.0의 JSON 형식과 HTTP 바인딩을 지원하는 플랫폼 사례입니다. 표의 결과는 로컬 가상 입력을 대조한 기록입니다. 설치한 SDK와 브로커는 같은 입력을 사용해 별도로 확인합니다. CloudEvents 태그 기록 Azure Event Grid 문서

알파카랩스는 공개 서비스 안내에서 채널별 입력, API 연동, 수집 실패·중복 재처리와 인수 조건을 합의한다고 설명합니다. 수신한 값을 어떤 업무 타입으로 넘길지 정할 때도 입력 예시와 실패 표본을 함께 검토합니다. 업무 자동화·API 연동 서비스

자주 묻는 질문#

data의 문자열에 중괄호가 들어 있으면 객체로 읽나요?

JSON 형식으로 선언된 data의 문자열은 JSON 문자열로 읽습니다. 객체를 기대하는 소비자에서는 별도 입력 계약에 따라 타입 오류로 처리할 수 있습니다.

data와 data_base64를 동시에 보낼 수 있나요?

구조화 JSON 이벤트에서는 두 필드가 함께 있을 수 없습니다. data의 값이 null이어도 필드가 존재하므로 같은 기준을 적용합니다.

datacontenttype이 없어도 JSON으로 읽나요?

data를 받는 쪽은 application/json으로 해석하는 것이 규격의 기본 권고입니다. data_base64가 있으면 먼저 바이트를 복원하며, 원래 데이터 형식은 미확인으로 둡니다.

data가 null인 경우와 아예 빠진 경우는 같은가요?

JSON 형식의 명시적 null은 존재하는 값입니다. data와 data_base64가 모두 생략되면 본문 없음으로 처리합니다. 둘을 구분하려면 필드의 존재 여부를 확인합니다.

이벤트가 유효하면 업무 앱의 입력도 유효한가요?

업무 앱의 입력 계약은 기대 타입과 필수 필드를 따로 확인합니다. 유효한 CloudEvents JSON 문자열도 주문 객체만 받는 처리기에서는 타입 오류가 될 수 있습니다.

본문 검수표 준비#

비식별 구조화 이벤트 표본과 업무 앱이 기대하는 타입을 준비합니다. 객체처럼 보이는 문자열, 명시적 null, 필드 생략이 필요한 업무라면 입력 표본을 각각 남기십시오.

이벤트 본문의 인수 기준을 정리합니다

첫 범위 협의에서 비식별 이벤트와 기대 타입으로 본문 검수표 초안을 정리합니다. 소요 시간은 수신 형식과 연동 범위를 확인한 뒤 협의합니다.

이벤트 본문 검수표 초안 협의