JSONata を使用したイベントの変換

ターゲットが受信する内容を変更するには、 CreateSubscriberまたは Transformer.Type Transformerに設定しますUpdateSubscriber。デフォルトRAWは、公開されたデータのみを配信し、メタデータとともにデータをWITH_METADATA配信し、 などの式の結果をJSONATA配信します{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}。ターゲットがカスタムイベントバスであるサブスクライバー - Classic は のみをサポートしますRAW。ユニバーサルターゲットは を使用しませんTransformer。同じ式を取る UniversalTargetParameters.Inputでリクエストを形成します。

トランスフォーマータイプ	次の場合に使用	ターゲットペイロード
RAW	ターゲットには公開されたイベントデータが必要です	公開済みデータ、変更なし。デフォルト。
WITH_METADATA	ターゲットにはデータとメタデータが必要です	、Data、Metadataおよび を含む JSON エンベロープ SystemMetadata
JSONATA	ターゲットには、選択した値または新しいシェイプが必要です	イベントごとに 1 つの JSONata 式の結果

$events 保持するもの

WITH_METADATA、JSONATA、およびすべてのターゲットパラメータ式は、JSONata 式が として認識する同じ入力オブジェクトを読み取ります$events。これには 3 つの部分があります。

{
    "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、、、iddetail-type、、sourceaccount、timeregionresources、、および が含まれるためdetail、同じ識別子は にあります$events.Data.detail.orderId。Base64 文字列については、application/octet-stream「」を参照してくださいバイナリデータの変換。

• 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 フィールド。

のように、コロンを含むフィールド名を引用符で囲みます$events.SystemMetadata."aws:EventId"。

JSONata を使用したターゲットペイロードの構築

Transformer.Type を に設定JSONATAし、 {%と で囲まれた完全な式を 1 つ配置%}します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 は、バッチ処理の前に、イベントごとに式を 1 回評価します。結果のタイプによって、ターゲットが受け取る内容が決まります。

式の結果	ターゲットペイロード
String	JSON 引用符なしの文字列
オブジェクトまたは配列	シリアル化された JSON オブジェクトまたは配列。null ネストされた は JSON のままですnull。
数値またはブール値	シリアル化された JSON 値
null、または undefined	変換の失敗。「」を参照してください。 制限と障害

バイナリデータの変換

SystemMetadata.ContentType が の場合application/octet-stream、EventBridge は公開されたバイトを解析せずに保存し、 の Base64 文字列として式に公開します$events.Data。のバイトは としてhello到着します$events.Data = "aGVsbG8="。EventBridge は、デコードされたバイトが JSON テキストであってもその文字列を JSON として解析しないため、 を解釈ContentTypeする前に を確認しData、元のバイトがテキストである$base64decode($events.Data)場合にのみ を使用します。

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

トランスフォーマータイプは、バイトがターゲットに到達する方法を決定します。のみが元のバイト配列を転送RAWできます。

トランスフォーマータイプ	ターゲットが受け取るもの
RAW	Kinesis、Firehose、API Gateway、およびカスタムイベントバスターゲットの元のバイト。Amazon SQS および Amazon SNS ターゲット用の Base64 テキスト。 Amazon SNS Lambda、Step Functions、カスタムイベントバス - 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、リテラル値または {%と で囲まれた 1 つの完全な 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 がイベントごとに解決するパラメータには、1 つの入力オブジェクトが表示されます。ターゲット呼び出しごとに 1 回解決されるパラメータは、バッチ内のイベントごとに 1 つずつ入力オブジェクトの配列を参照するため、最初のイベントは です$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"に到達します0x01 0x02 0x03。式StringValueには を使用します。

API Gateway ターゲットの場合、各HttpParameters.HeaderParametersキーはリテラルである必要があります。API 送信先ターゲットはヘッダーキーの式も許可します。EventBridge は、リクエスト署名を上書きするヘッダー、Authorization、Hostおよび で始まるヘッダーを拒否しますX-Amz。サブスクライバーのパラメータの 1 つの解像度内で $now()と を$millis()呼び出すたびに、同じタイムスタンプが返されます。

標準 JSONata を超える関数

標準の JSONata ライブラリに加えて、6 つの関数を使用できます。

関数	結果
$hash(input, algorithm)	小文字の 16 進ダイジェスト。 algorithmでは大文字と小文字が区別されます: MD5、SHA-1、SHA-256、SHA-384、または SHA-512
$uuid()	バージョン 4 UUID
$parse(jsonString)	解析された JSON。文字列が有効な JSON でない場合のエラー
$partition(array, chunkSize)	配列をチャンクに分割する
$range(start, end, delta)	数値範囲。3 つの引数すべてが必要で、結果は 10,000,000 要素に制限されます。
$random(seed)	[0, 1) の数値。同じシードで同じ数値が与えられる

$eval 関数は使用できません。

制限と障害

Transformer 式と各ターゲットパラメータ式は最大 8,192 文字で、ユニバーサルターゲットのInput式は最大 262,144 文字です。EventBridge は、サブスクライバーを作成または更新するときに構文をチェックし、 で無効な式を拒否しますInvalidInputException。配信時に、式を 1 秒間実行し、スタック深度 100 を使用し、10 MiB を割り当てることができます。

そのイベントの配信をスロー、超過、または生成nullまたはundefined失敗する式。EventBridge はサブスクライバーの で再試行しRetryPolicy、イベントが設定されている場合は障害発生時の送信先にイベントを送信します。EventTransformationFailures メトリクスは各失敗をカウントし、EVENT_TRANSFORMATION_FAILUREログレコードはエラーを保持し、デッドレターレコードの errorCodeは ですINPUT_TRANSFORMATION_FAILURE。「カスタムイベントバスのオブザーバビリティ: メトリクス、ログ、CloudTrail」および「再試行ポリシーとデッドレターキュー」を参照してください。