기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 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`, `account``region`, `resources`, 및 `detail`가 있으므로 동일한 식별자는에 있습니다`$events.Data.detail.orderId`. Base64 문자열인 경우 섹션을 참조`application/octet-stream`하세요[바이너리 데이터 변환](#eb-custom-bus-transform-binary).
+ `Metadata`는 로 설정된 생산자 세트의 string-to-string 맵입니다`PutRawEvents`. `PutEvents`는 메타데이터를 사용하지 않으므로 이벤트의 경우 맵이 비어 있습니다.
+ `SystemMetadata` 에는 EventBridge가 할당하는 필드가 있습니다. 모든 값은 문자열입니다. EventBridge는 값이 없는 선택적 필드를 생략하고 생략된 필드는 JSONata`undefined`에서 로 평가됩니다.는 항상 존재합니다. `aws:DeliveryType`는 게시된 값을 `ContentType` 유지합니다. 따라서 EventBridge가 JSON으로 디코딩한 Avro 및 Protobuf 데이터는 여전히 `application/avro` 또는 `application/protobuf` 여기 표시되며 `PutEvents` 이벤트는를 표시합니다`application/eventbridge+json`. 모든 필드에 대해서는 단원을 참조하십시오[SystemMetadata 필드](eb-custom-bus-addressing.md#eb-custom-bus-addressing-system).
와 같이 콜론이 포함된 필드 이름을 인용합니다`$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 | 변환 실패, 참조 [제한 및 실패](#eb-custom-bus-transform-limits) |
## 바이너리 데이터 변환
이 `application/octet-stream`인 경우 EventBridge`SystemMetadata.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](eb-custom-bus-observability.md) 및 [재시도 정책 및 배달 못한 편지 대기열](eb-custom-bus-retry.md) 단원을 참조하세요.