Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Mengubah acara dengan JSONata
Untuk mengubah apa yang diterima target, `Transformer` atur `CreateSubscriber` atau`UpdateSubscriber`. `Transformer.Type``RAW`, 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 mendukung`RAW`. Target universal tidak menggunakan`Transformer`; itu membentuk permintaannya`UniversalTargetParameters.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"
}
}
```
+ `Data`adalah 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, dengan`version`,`id`,`detail-type`,`source`,`account`,`time`,`region`,`resources`, dan`detail`, jadi pengenal yang sama ada di`$events.Data.detail.orderId`. Karena `application/octet-stream` itu adalah string Base64; lihat[Mengubah data biner](#eb-custom-bus-transform-binary).
+ `Metadata`adalah peta string-to-string yang digunakan produsen. `PutRawEvents` `PutEvents`tidak mengambil metadata, jadi untuk acaranya peta kosong.
+ `SystemMetadata`memegang 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. `ContentType`menyimpan 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, lihat[SystemMetadata bidang](eb-custom-bus-addressing.md#eb-custom-bus-addressing-system).
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`%}`, di`JsonataConfiguration.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](#eb-custom-bus-transform-limits) |
## Mengubah data biner
When `SystemMetadata.ContentType` is`application/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 menafsirkan`Data`, 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 diatur`ContentType`. 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 di`InvokeConfiguration`, seperti`SqsParameters.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 | `$events`memegang |
| --- | --- |
| 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}}.StringValue``HttpParameters.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 byte`0x01 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 dengan`X-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 |
`$eval`Fungsi 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 dengan`InvalidInputException`. 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 pelanggan`RetryPolicy`, 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 adalah`errorCode`. `INPUT_TRANSFORMATION_FAILURE` Lihat [Pengamatan untuk Bus Peristiwa Kustom: metrik, log, dan CloudTrail](eb-custom-bus-observability.md) dan [Kebijakan coba ulang dan antrian surat mati](eb-custom-bus-retry.md).