使用 JSONata 轉換事件

若要變更目標接收的內容，請在 Transformer.Type CreateSubscriber或 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	目標需要選取的值或新形狀	每個事件一個 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 是已發佈的資料，並保留其 JSON 類型：物件、陣列、字串、數字、布林值或 null。PutRawEvents 因為它是項目Data的值，因此訂單識別符位於 $events.Data.orderId。對於PutEvents整個 EventBridge 信封，使用 version、id、detail-type、source、accounttime、、resources、 region和 detail，因此相同的識別符位於 $events.Data.detail.orderId。application/octet-stream 其為 Base64 字串；請參閱 轉換二進位資料。

• 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並在 中放置一個完整的表達式%}，括在 {%和 中JsonataConfiguration.Expression。對於資料為 PutRawEvents的項目{"orderId": "12345", "priority": "high", "items": [...]}，下列轉換器只會提供兩個具名欄位。

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

目標會收到 {"orderId": "12345", "priority": "high"}。EventBridge 會在批次處理前評估每個事件的表達式一次。結果的類型決定目標接收的內容。

表達式結果	目標承載
String	字串，不含 JSON 引號
物件或陣列	序列化 JSON 物件或陣列。其中的null巢狀 會保留 JSON null。
數字或布林值	序列化 JSON 值
null 或 undefined	轉換失敗；請參閱 限制和失敗

轉換二進位資料

當 SystemMetadata.ContentType為 時application/octet-stream，EventBridge 會儲存已發佈的位元組而不剖析它們，並在 中將其公開為 Base64 字串的表達式$events.Data。的位元組會以 的形式hello抵達$events.Data = "aGVsbG8="。即使解碼的位元組是 JSON 文字，EventBridge 也不會將該字串剖析為 JSON，因此請在解譯 ContentType之前進行檢查Data，並$base64decode($events.Data)僅在原始位元組是文字時使用。

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

轉換器類型決定位元組如何到達目標。只有 RAW可以轉送原始位元組陣列。

轉換器類型	目標接收的內容
RAW	Kinesis、Firehose、API Gateway 和自訂事件匯流排目標的原始位元組。Base64 文字，適用於 Amazon SQS 和 Amazon SNS 目標。包含 Base64 文字的 JSON 字串，適用於 Lambda、Step Functions、Custom Event Bus - Classic 和 API 目的地目標；批次 Lambda 或 Step Functions 調用會收到這些字串的陣列。
WITH_METADATA	信封為 UTF-8 JSON，Data內含 Base64 文字
JSONATA	表達式結果為 UTF-8 文字或 JSON；表達式讀取 Base64 文字

轉換器無法設定 ContentType。當目標是另一個自訂事件匯流排時，EventBridge 會複製發佈的值，但 Avro 和 Protobuf 資料會以 JSON 形式交付，因此會以 的形式送達application/json。

在目標參數中使用 JSONata

中的目標參數InvokeConfiguration，例如 SqsParameters.MessageGroupId，會保留常值或括在 {%和 中的完整 JSONata 表達式%}。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。

Parameters	$events 保留
SqsParameters, SnsParameters, KinesisParameters, HttpParameters, 和 EventBusV2Parameters.Metadata	每個事件一個輸入物件
LambdaParameters、StepFunctionsParameters 與 EventBusV2Parameters.DeduplicationConfiguration	每次調用的輸入物件陣列
UniversalTargetParameters.Input	每次調用的輸入物件陣列

除非 欄位定義另一種類型，否則目標參數表達式必須傳回字串； UniversalTargetParameters.Input 可以傳回任何構成 API 請求的 JSON 值。在映射值參數中，索引鍵和字串值都可以是表達式：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 會拒絕會覆寫請求簽署的標頭：Host、 Authorization和開頭為 的任何標頭X-Amz。在訂閱者參數的一個解析度內，每個 $now()和 $millis()呼叫都會傳回相同的時間戳記。

超出標準 JSONata 的函數

除了標準 JSONata 程式庫之外，還提供六個函數。

函式	結果
$hash(input, algorithm)	小寫十六進位摘要。區分algorithm大小寫：MD5、SHA-1、SHA-384、 SHA-256或 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。在交付時，表達式可以執行一秒鐘，使用堆疊深度 100，並配置 10 MiB。

擲回、超過這些限制，或產生null或undefined失敗交付該事件的表達式。EventBridge 會在訂閱者的 下重試RetryPolicy，如果已設定事件，則會將該事件傳送至失敗時的目的地。EventTransformationFailures 指標會計算每個失敗、EVENT_TRANSFORMATION_FAILURE日誌記錄帶有錯誤，而無效字母記錄的 errorCode是 INPUT_TRANSFORMATION_FAILURE。請參閱自訂事件匯流排的可觀測性：指標、日誌和 CloudTrail和重試政策和無效字母佇列。