Mengubah acara dengan JSONata

Untuk mengubah apa yang diterima target, Transformer atur CreateSubscriber atauUpdateSubscriber. Transformer.TypeRAW, default, mengirimkan data yang dipublikasikan saja; WITH_METADATA mengirimkan data dengan metadatanya; dan JSONATA memberikan hasil ekspresi, misalnya{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}. Pelanggan yang targetnya adalah Bus Acara Kustom - Classic hanya mendukungRAW. Target universal tidak menggunakanTransformer; itu membentuk permintaannyaUniversalTargetParameters.Input, yang mengambil ekspresi yang sama.

Jenis transformator	Gunakan kapan	Muatan target
RAW	Target membutuhkan data acara yang dipublikasikan	Data yang dipublikasikan, tidak berubah. Defaultnya.
WITH_METADATA	Target membutuhkan data dan metadatanya	Sebuah amplop JSON denganData,Metadata, dan SystemMetadata
JSONATA	Target membutuhkan nilai yang dipilih atau bentuk baru	Hasil dari satu ekspresi JSONata per peristiwa

Apa yang dimiliki $events

WITH_METADATA,JSONATA, dan setiap ekspresi parameter target membaca objek input yang sama, yang dilihat oleh ekspresi JSONata. $events Ini memiliki tiga bagian.

{
    "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"
    }
}

• Dataadalah data yang diterbitkan dan mempertahankan tipe JSON-nya: objek, array, string, angka, Boolean, atau null. Karena PutRawEvents itu adalah Data nilai entri, jadi pengenal pesanan ada di$events.Data.orderId. Karena PutEvents itu adalah seluruh EventBridge amplop, denganversion,id,detail-type,source,account,time,region,resources, dandetail, jadi pengenal yang sama ada di$events.Data.detail.orderId. Karena application/octet-stream itu adalah string Base64; lihatMengubah data biner.

• Metadataadalah peta string-to-string yang digunakan produsen. PutRawEvents PutEventstidak mengambil metadata, jadi untuk acaranya peta kosong.

• SystemMetadatamemegang bidang yang dit EventBridge ugaskan. Setiap nilai adalah string. EventBridgemenghilangkan bidang opsional yang tidak memiliki nilai, dan bidang yang dihilangkan mengevaluasi seperti undefined di JSONata; hanya aws:DeliveryType selalu ada. ContentTypemenyimpan nilai yang dipublikasikan, sehingga data Avro dan Protobuf yang diterjemahkan EventBridge ke JSON masih ditampilkan application/avro atau application/protobuf di sini, dan acara ditampilkan. PutEvents application/eventbridge+json Untuk setiap bidang, lihatSystemMetadata bidang.

Kutip nama bidang yang berisi titik dua, seperti pada$events.SystemMetadata."aws:EventId".

Membangun target payload dengan JSONata

Atur Transformer.Type ke JSONATA dan masukkan satu ekspresi lengkap, terlampir di {% dan%}, diJsonataConfiguration.Expression. Untuk PutRawEvents entri yang datanya{"orderId": "12345", "priority": "high", "items": [...]}, transformator berikut hanya memberikan dua bidang bernama.

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

Target menerima {"orderId": "12345", "priority": "high"} EventBridge mengevaluasi ekspresi sekali untuk setiap peristiwa, sebelum melakukan batch. Jenis hasil menentukan apa yang diterima target.

Hasil ekspresi	Muatan target
String	String, tanpa tanda kutip JSON
Objek atau array	Objek atau array JSON yang diserialisasi. Sebuah null bersarang di dalamnya tetap JSONnull.
Angka atau Boolean	Nilai JSON yang diserialkan
null atau undefined	Kegagalan transformasi; lihat Batas dan kegagalan

Mengubah data biner

When SystemMetadata.ContentType isapplication/octet-stream, EventBridge menyimpan byte yang diterbitkan tanpa menguraikannya dan mengeksposnya ke ekspresi sebagai string Base64 di. $events.Data Byte dari hello tiba sebagai$events.Data = "aGVsbG8=". EventBridge tidak mengurai string itu sebagai JSON bahkan ketika byte yang didekodekan adalah teks JSON, jadi periksa ContentType sebelum Anda menafsirkanData, dan gunakan $base64decode($events.Data) hanya jika byte asli adalah teks.

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

Jenis transformator menentukan bagaimana byte mencapai target. Hanya RAW dapat meneruskan array byte asli.

Jenis transformator	Apa yang diterima target
RAW	Byte asli, untuk target Kinesis, Firehose, API Gateway, dan Custom Event Bus. Teks Base64, untuk target Amazon SQS dan Amazon SNS. String JSON yang berisi teks Base64, untuk Lambda, Step Functions, Custom Event Bus - Classic, dan target tujuan API; pemanggilan Lambda atau Step Functions batch menerima array string tersebut.
WITH_METADATA	Amplop sebagai UTF-8 JSON, dengan Data memegang teks Base64
JSONATA	Hasil ekspresi sebagai UTF-8 teks atau JSON; ekspresi membaca teks Base64

Transformator tidak dapat diaturContentType. Ketika targetnya adalah Bus Acara Kustom lainnya, EventBridge salin nilai yang diterbitkan, kecuali bahwa data Avro dan Protobuf dikirimkan sebagai JSON dan tiba sebagai. application/json

Menggunakan JSONata dalam parameter target

Parameter target diInvokeConfiguration, sepertiSqsParameters.MessageGroupId, menyimpan nilai literal atau satu ekspresi JSONata lengkap yang terlampir di {% dan. %} EventBridge tidak mengevaluasi ekspresi yang tertanam di dalam string yang lebih panjang. Ekspresi parameter target membaca objek input asli, bukan payload yang Transformer dihasilkan. Parameter Amazon SQS berikut mengambil nilai FIFO dari setiap peristiwa.

{
    "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\" %}"
        }
    }
}

Apa $events yang berlaku tergantung pada parameter. Parameter EventBridge yang menyelesaikan per peristiwa melihat satu objek input. Parameter yang diselesaikan sekali per pemanggilan target melihat array objek input, satu per peristiwa dalam batch, jadi peristiwa pertama adalah. $events[0].Data

Parameter	$eventsmemegang
SqsParameters,SnsParameters,KinesisParameters,HttpParameters, dan EventBusV2Parameters.Metadata	Satu objek masukan, per peristiwa
LambdaParameters, StepFunctionsParameters, dan EventBusV2Parameters.DeduplicationConfiguration	Array objek masukan, per pemanggilan
UniversalTargetParameters.Input	Array objek masukan, per pemanggilan

Ekspresi parameter target harus mengembalikan string, kecuali bidang mendefinisikan tipe lain; UniversalTargetParameters.Input dapat mengembalikan nilai JSON apa pun yang membentuk permintaan API. Dalam parameter nilai peta, kunci dan nilai string dapat berupa ekspresi:SqsParameters.MessageAttributes.name.StringValue,,, SqsParameters.MessageSystemAttributes.name.StringValue SnsParameters.MessageAttributes.name.StringValueHttpParameters.QueryStringParameters.key, dan. EventBusV2Parameters.Metadata.key A BinaryValue tribut pesan Amazon SQS atau Amazon SNS adalah nilai Base64 literal yang EventBridge tidak pernah mengevaluasi, jadi "BinaryValue": "AQID" mencapai target sebagai byte0x01 0x02 0x03; gunakan StringValue untuk ekspresi.

Untuk target API Gateway, setiap HttpParameters.HeaderParameters kunci harus literal; target tujuan API juga mengizinkan ekspresi dalam kunci header. EventBridge menolak header yang akan menggantikan penandatanganan permintaan:Authorization,Host, dan header apa pun yang dimulai denganX-Amz. Setiap $now() $millis() panggilan dalam satu resolusi parameter pelanggan mengembalikan stempel waktu yang sama.

Fungsi di luar standar JSONata

Selain pustaka JSONata standar, enam fungsi tersedia.

Fungsi	Hasil
$hash(input, algorithm)	Intisari hex huruf kecil. algorithmpeka huruf besar/kecil:MD5,SHA-1,SHA-256,SHA-384, atau SHA-512
$uuid()	Sebuah versi 4 UUID
$parse(jsonString)	JSON yang diurai; kesalahan jika string tidak valid JSON
$partition(array, chunkSize)	Array dibagi menjadi potongan-potongan
$range(start, end, delta)	Rentang numerik; ketiga argumen diperlukan, dan hasilnya dibatasi pada 10.000.000 elemen
$random(seed)	Angka dalam [0, 1); benih yang sama memberikan angka yang sama

$evalFungsi ini tidak tersedia.

Batas dan kegagalan

Ek Transformer spresi dan setiap ekspresi parameter target dapat mencapai 8.192 karakter; Input ekspresi target universal hingga 262.144. EventBridge memeriksa sintaks saat Anda membuat atau memperbarui pelanggan dan menolak ekspresi yang tidak valid denganInvalidInputException. Saat pengiriman, ekspresi dapat berjalan selama satu detik, menggunakan kedalaman tumpukan 100, dan mengalokasikan 10 MiB.

Ekspresi yang melempar, melebihi batas tersebut, null atau menghasilkan atau undefined gagal pengiriman peristiwa itu. EventBridge coba lagi di bawah pelangganRetryPolicy, lalu mengirim acara ke tujuan gagal jika salah satu dikonfigurasi. Met EventTransformationFailures rik menghitung setiap kegagalan, catatan EVENT_TRANSFORMATION_FAILURE log membawa kesalahan, dan catatan huruf mati adalaherrorCode. INPUT_TRANSFORMATION_FAILURE Lihat Pengamatan untuk Bus Peristiwa Kustom: metrik, log, dan CloudTrail dan Kebijakan percobaan ulang dan antrean surat mati.