JSONata로 이벤트 변환

대상이 수신하는 내용을 변경하려면 CreateSubscriber 또는 Transformer에 설정합니다UpdateSubscriber. 기본값RAW인 Transformer.Type는 게시된 데이터만 전송하고, 메타데이터와 함께 데이터를 WITH_METADATA 전송하며,와 같은 표현식의 결과를 JSONATA 전송합니다{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}. 대상이 사용자 지정 이벤트 버스 - Classic인 구독자는 만 지원합니다RAW. 범용 대상은를 사용하지 않습니다. Transformer동일한 표현식을 UniversalTargetParameters.Input사용하는에서 요청을 형성합니다.

변환기 유형	사용 상황	대상 페이로드
RAW	대상에 게시된 이벤트 데이터가 필요합니다.	게시된 데이터는 변경되지 않습니다. 기본값입니다.
WITH_METADATA	대상에 데이터 및 메타데이터가 필요합니다.	Data, Metadata및가 포함된 JSON 봉투 SystemMetadata
JSONATA	대상에 선택한 값 또는 새 셰이프가 필요합니다.	이벤트당 하나의 JSONata 표현식 결과

$events의 내용

WITH_METADATA, JSONATA및 모든 대상 파라미터 표현식은 JSONata 표현식이 로 보는 것과 동일한 입력 객체를 읽습니다$events. 세 부분으로 구성되어 있습니다.

{
    "Data": { "orderId": "12345", "priority": "high" },
    "Metadata": { "tenant": "acme" },
    "SystemMetadata": {
        "ContentType": "application/json",
        "aws:EventId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "aws:IngestionTime": "2026-09-23T18:00:00Z",
        "aws:DeliveryType": "LIVE"
    }
}

• Data는 게시된 데이터이며 객체, 배열, 문자열, 숫자, 부울 또는 null과 같은 JSON 유형을 유지합니다. PutRawEvents의 경우 항목의 Data 값이기 때문에 주문 식별자는에 있습니다$events.Data.orderId. 의 경우 전체 EventBridge 봉투PutEvents이며, version, id, detail-type, source, time, accountregion, resources, 및 detail가 있으므로 동일한 식별자는에 있습니다$events.Data.detail.orderId. Base64 문자열인 경우 섹션을 참조application/octet-stream하세요바이너리 데이터 변환.

• Metadata는 로 설정된 생산자 세트의 string-to-string 맵입니다PutRawEvents. PutEvents는 메타데이터를 사용하지 않으므로 이벤트의 경우 맵이 비어 있습니다.

• SystemMetadata 에는 EventBridge가 할당하는 필드가 있습니다. 모든 값은 문자열입니다. EventBridge는 값이 없는 선택적 필드를 생략하고 생략된 필드는 JSONataundefined에서 로 평가됩니다.는 항상 존재합니다. aws:DeliveryType는 게시된 값을 ContentType 유지합니다. 따라서 EventBridge가 JSON으로 디코딩한 Avro 및 Protobuf 데이터는 여전히 application/avro 또는 application/protobuf 여기 표시되며 PutEvents 이벤트는를 표시합니다application/eventbridge+json. 모든 필드에 대해서는 단원을 참조하십시오SystemMetadata 필드.

와 같이 콜론이 포함된 필드 이름을 인용합니다$events.SystemMetadata."aws:EventId".

JSONata를 사용하여 대상 페이로드 빌드

Transformer.Type를 로 설정하고 JSONATA 및 {% 로 묶인 하나의 전체 표현식을 %}에 넣습니다JsonataConfiguration.Expression. 데이터가 인 PutRawEvents 항목의 경우 {"orderId": "12345", "priority": "high", "items": [...]}다음 변환기는 2개의 명명된 필드만 전송합니다.

{
    "Transformer": {
        "Type": "JSONATA",
        "JsonataConfiguration": {
            "Expression": "{% {\"orderId\": $events.Data.orderId, \"priority\": $events.Data.priority} %}"
        }
    }
}

대상은를 수신합니다{"orderId": "12345", "priority": "high"}. EventBridge는 일괄 처리 전에 각 이벤트에 대해 표현식을 한 번 평가합니다. 결과 유형에 따라 대상이 수신하는 항목이 결정됩니다.

표현식 결과	대상 페이로드
문자열	JSON 따옴표가 없는 문자열
객체 또는 배열	직렬화된 JSON 객체 또는 배열입니다. 내부에 중첩된 null는 JSON을 유지합니다null.
숫자 또는 부울	직렬화된 JSON 값
null 또는 undefined	변환 실패, 참조 제한 및 실패

바이너리 데이터 변환

이 application/octet-stream인 경우 EventBridgeSystemMetadata.ContentType는 게시된 바이트를 구문 분석하지 않고 저장하고 표현식에의 Base64 문자열로 노출합니다$events.Data. 의 바이트는 로 hello 도착합니다$events.Data = "aGVsbG8=". EventBridge는 디코딩된 바이트가 JSON 텍스트인 경우에도 해당 문자열을 JSON으로 구문 분석하지 않으므로 해석ContentType하기 전에 확인하고 원래 바이트가 텍스트인 $base64decode($events.Data) 경우에만 Data사용합니다.

{% {
    "contentType": $events.SystemMetadata.ContentType,
    "base64Data": $events.Data
} %}

변환기 유형에 따라 바이트가 대상에 도달하는 방식이 결정됩니다. 만 원래 바이트 배열을 전달할 RAW 수 있습니다.

변환기 유형	대상이 수신하는 내용
RAW	Kinesis, Firehose, API Gateway 및 사용자 지정 이벤트 버스 대상의 원래 바이트입니다. Amazon SQS 및 Amazon SNS 대상에 대한 Base64 텍스트입니다. Lambda, Step Functions, Custom Event Bus - Classic 및 API 대상에 대한 Base64 텍스트가 포함된 JSON 문자열입니다. 일괄 Lambda 또는 Step Functions 호출은 해당 문자열의 배열을 수신합니다.
WITH_METADATA	Base64 텍스트를 Data 누른 상태에서 UTF-8 JSON 형식의 봉투
JSONATA	표현식 결과는 UTF-8 텍스트 또는 JSON입니다. 표현식은 Base64 텍스트를 읽습니다.

변환기는를 설정할 수 없습니다ContentType. 대상이 다른 사용자 지정 이벤트 버스인 경우 EventBridge는 Avro 및 Protobuf 데이터가 JSON으로 전송되어 로 도착한다는 점을 제외하고 게시된 값을 복사합니다application/json.

대상 파라미터에서 JSONata 사용

InvokeConfiguration와 같은의 대상 파라미터는 및 로 묶인 리터럴 값 또는 하나의 전체 JSONata 표현식을 SqsParameters.MessageGroupId보유합니다{%%}. EventBridge는 더 긴 문자열 내에 포함된 표현식을 평가하지 않습니다. 대상 파라미터 표현식은가 Transformer 생성한 페이로드가 아닌 원래 입력 객체를 읽습니다. 다음 Amazon SQS 파라미터는 각 이벤트에서 FIFO 값을 가져옵니다.

{
    "InvokeConfiguration": {
        "TargetArn": "arn:aws:sqs:us-east-1:111122223333:orders.fifo",
        "RoleArn": "arn:aws:iam::111122223333:role/SubscriberTargetRole",
        "SqsParameters": {
            "MessageGroupId": "{% $events.Data.customerId %}",
            "MessageDeduplicationId": "{% $events.SystemMetadata.\"aws:EventId\" %}"
        }
    }
}

가 $events 보유하는 항목은 파라미터에 따라 달라집니다. EventBridge가 이벤트당 확인하는 파라미터는 입력 객체 하나를 참조하세요. 대상 호출당 한 번 확인되는 파라미터는 배치의 이벤트당 하나씩 입력 객체 배열을 표시하므로 첫 번째 이벤트는 입니다$events[0].Data.

파라미터	$events 보류
SqsParameters, SnsParameters, KinesisParameters, HttpParameters 및 EventBusV2Parameters.Metadata	이벤트당 입력 객체 1개
LambdaParameters, StepFunctionsParameters 및 EventBusV2Parameters.DeduplicationConfiguration	호출당 입력 객체 배열
UniversalTargetParameters.Input	호출당 입력 객체 배열

필드가 다른 유형을 정의하지 않는 한 대상 파라미터 표현식은 문자열을 반환해야 합니다.는 API 요청을 구성하는 모든 JSON 값을 반환할 UniversalTargetParameters.Input 수 있습니다. 맵 값 파라미터에서 키와 문자열 값은 모두 표현식 , SqsParameters.MessageAttributes.name.StringValue, SqsParameters.MessageSystemAttributes.name.StringValue, SnsParameters.MessageAttributes.name.StringValue및 HttpParameters.QueryStringParameters.key일 수 있습니다EventBusV2Parameters.Metadata.key. Amazon SQS 또는 Amazon SNS 메시지 속성BinaryValue의는 EventBridge가 평가하지 않는 리터럴 Base64 값이므로는 대상에 바이트로 "BinaryValue": "AQID" 도달하고 표현식StringValue에를 0x01 0x02 0x03사용합니다.

API Gateway 대상의 경우 각 HttpParameters.HeaderParameters 키는 리터럴이어야 합니다. API 대상 대상은 헤더 키의 표현식도 허용합니다. EventBridge는 요청 서명을 재정의하는 Authorization, Host및 로 시작하는 모든 헤더를 거부합니다X-Amz. 구독자 파라미터의 단일 해상도 내에서 모든 $now() 및 $millis() 호출은 동일한 타임스탬프를 반환합니다.

표준 JSONata 이외의 함수

표준 JSONata 라이브러리 외에도 6가지 함수를 사용할 수 있습니다.

함수	결과
$hash(input, algorithm)	소문자 16진수 다이제스트입니다. algorithm는 대/소문자를 구분합니다. MD5, SHA-1, SHA-256SHA-384, 또는 SHA-512
$uuid()	버전 4 UUID
$parse(jsonString)	구문 분석된 JSON입니다. 문자열이 유효한 JSON이 아닌 경우 오류가 발생합니다.
$partition(array, chunkSize)	배열이 청크로 분할됩니다.
$range(start, end, delta)	숫자 범위. 세 인수가 모두 필요하며 결과는 10,000,000개의 요소로 제한됩니다.
$random(seed)	[0, 1)의 숫자. 동일한 시드는 동일한 숫자를 제공합니다.

$eval 함수를 사용할 수 없습니다.

제한 및 실패

Transformer 표현식과 각 대상 파라미터 표현식은 최대 8,192자일 수 있으며, 범용 대상의 Input 표현식은 최대 262,144자입니다. EventBridge는 구독자를 생성하거나 업데이트할 때 구문을 확인하고를 사용하여 잘못된 표현식을 거부합니다InvalidInputException. 전송 시 표현식은 1초 동안 실행되고, 스택 깊이 100을 사용하고, 10MiB를 할당할 수 있습니다.

이러한 제한을 발생시키거나 초과하거나 해당 이벤트의 전송을 생성null하거나 undefined 실패하는 표현식입니다. EventBridge는 구독자의에서 재시도한 다음 RetryPolicy이벤트가 구성된 경우 실패 시 대상으로 이벤트를 보냅니다. EventTransformationFailures 지표는 각 실패를 계산하고, EVENT_TRANSFORMATION_FAILURE 로그 레코드에는 오류가 포함되며, 배달 못한 편지 레코드의 errorCode는 입니다INPUT_TRANSFORMATION_FAILURE. 사용자 지정 이벤트 버스에 대한 관찰성: 지표, 로그 및 CloudTrail 및 재시도 정책 및 배달 못한 편지 대기열 단원을 참조하세요.