Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Trasformare gli eventi con JSonata Per modificare ciò che riceve un bersaglio, imposta `Transformer` su `CreateSubscriber` o`UpdateSubscriber`. `Transformer.Type``RAW`, impostazione predefinita, fornisce solo i dati pubblicati, `WITH_METADATA` fornisce i dati con i relativi metadati e `JSONATA` fornisce il risultato di un'espressione, ad esempio. `{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}` Supporta solo un abbonato il cui obiettivo è un Custom Event Bus - Classic. `RAW` Un target universale non utilizza`Transformer`; modella la sua richiesta in`UniversalTargetParameters.Input`, che accetta le stesse espressioni. | Tipo di trasformatore | Da usare quando | Carico utile target | | --- | --- | --- | | RAW | Il target ha bisogno dei dati degli eventi pubblicati | I dati pubblicati, invariati. Il valore predefinito. | | WITH\_METADATA | L'obiettivo ha bisogno dei dati e dei relativi metadati | Una busta JSON con, e Data Metadata SystemMetadata | | JSONATA | Il target necessita di valori selezionati o di una nuova forma | Il risultato di un'espressione JSonata per evento | ## Cosa contiene $events `` `WITH_METADATA``JSONATA`, e ogni espressione del parametro di destinazione legge lo stesso oggetto di input, visto da un'espressione JSonata. `$events` È composto da tre parti. ``` { "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`sono i dati pubblicati e mantengono il tipo JSON: un oggetto, un array, una stringa, un numero, booleano o null. Perché `PutRawEvents` è il `Data` valore della voce, quindi un identificatore d'ordine si trova in. `$events.Data.orderId` Perché `PutEvents` è l'intera EventBridge busta, con,`version`,`id`,`detail-type`,,`source`,`account`, `time``region`, e `resources``detail`, quindi è lo stesso identificatore. `$events.Data.detail.orderId` Perché `application/octet-stream` è una stringa Base64; vedi. [Trasformazione di dati binari](#eb-custom-bus-transform-binary) + `Metadata`è la mappa da stringa a stringa con cui il produttore ha impostato. `PutRawEvents` `PutEvents`non accetta metadati, quindi per i suoi eventi la mappa è vuota. + `SystemMetadata`contiene le assegnazioni dei campi EventBridge . Ogni valore è una stringa. EventBridgeomette un campo opzionale che non ha valore e un campo omesso viene valutato come `undefined` in JSonata; solo è sempre presente. `aws:DeliveryType` `ContentType`mantiene il valore pubblicato, quindi i dati Avro e Protobuf EventBridge decodificati in JSON vengono ancora visualizzati o qui e viene visualizzato un evento. `application/avro` `application/protobuf` `PutEvents` `application/eventbridge+json` Per ogni campo, vedi. [SystemMetadata campi](eb-custom-bus-addressing.md#eb-custom-bus-addressing-system) Cita un nome di campo che contiene i due punti, come in`$events.SystemMetadata."aws:EventId"`. ## Creazione di un payload di destinazione con JSonata `Transformer.Type`Imposta `JSONATA` e inserisci un'espressione completa, racchiusa in e, dentro`{%`. `%}` `JsonataConfiguration.Expression` Per una `PutRawEvents` voce i cui dati sono`{"orderId": "12345", "priority": "high", "items": [...]}`, il seguente trasformatore fornisce solo i due campi denominati. ``` { "Transformer": { "Type": "JSONATA", "JsonataConfiguration": { "Expression": "{% {\"orderId\": $events.Data.orderId, \"priority\": $events.Data.priority} %}" } } } ``` Il bersaglio riceve`{"orderId": "12345", "priority": "high"}`. EventBridge valuta l'espressione una volta per ogni evento, prima dell'assegnazione in batch. Il tipo di risultato decide cosa riceve il bersaglio. | Risultato dell'espressione | Payload target | | --- | --- | | Stringa | La stringa, senza virgolette JSON | | Oggetto o matrice | L'oggetto o l'array JSON serializzato. Un null nidificato al suo interno rimane JSON. null | | Numero o booleano | Il valore JSON serializzato | | null o undefined | Un errore di trasformazione; vedi [Limiti e guasti](#eb-custom-bus-transform-limits) | ## Trasformazione di dati binari In `SystemMetadata.ContentType` tal caso`application/octet-stream`, EventBridge memorizza i byte pubblicati senza analizzarli e li espone a un'espressione come stringa Base64 in. `$events.Data` I byte di arrive as. `hello` `$events.Data = "aGVsbG8="` EventBridge non analizza quella stringa come JSON anche quando i byte decodificati sono testo JSON, quindi controlla `ContentType` prima di interpretare `Data` e usalo `$base64decode($events.Data)` solo quando i byte originali sono testo. ``` {% { "contentType": $events.SystemMetadata.ContentType, "base64Data": $events.Data } %} ``` Il tipo di trasformatore decide in che modo i byte raggiungono la destinazione. `RAW`Può solo inoltrare l'array di byte originale. | Tipo di trasformatore | Cosa riceve il bersaglio | | --- | --- | | RAW | I byte originali, per i target Kinesis, Firehose, API Gateway e Custom Event Bus. Testo Base64, per destinazioni Amazon SQS e Amazon SNS. Una stringa JSON contenente il testo Base64, per Lambda, Step Functions, Custom Event Bus - Classic e le destinazioni API; una chiamata Lambda o Step Functions in batch riceve un array di tali stringhe. | | WITH\_METADATA | La busta in formato JSON, contenente il testo Base64 UTF-8 Data | | JSONATA | Il risultato dell'espressione è UTF-8 testo o JSON; l'espressione legge il testo Base64 | Un trasformatore non può essere impostato. `ContentType` Quando l'obiettivo è un altro Custom Event Bus, EventBridge copia il valore pubblicato, tranne per il fatto che i dati Avro e Protobuf vengono consegnati come JSON e quindi arrivano come. `application/json` ## Utilizzo di JSonata nei parametri di destinazione Un parametro di destinazione in`InvokeConfiguration`, ad esempio`SqsParameters.MessageGroupId`, contiene un valore letterale o un'espressione JSonata completa racchiusa tra e. `{%` `%}` EventBridge non valuta un'espressione incorporata in una stringa più lunga. Le espressioni dei parametri di destinazione leggono l'oggetto di input originale, non il payload `Transformer` prodotto. I seguenti parametri Amazon SQS prendono i valori FIFO da ciascun evento. ``` { "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\" %}" } } } ``` La `$events` validità dipende dal parametro. I parametri che EventBridge si risolvono per evento vedono un oggetto di input. I parametri che risolve una volta per chiamata di destinazione vedono una serie di oggetti di input, uno per evento nel batch, quindi il primo evento è. `$events[0].Data` | Parameters | `$events`detiene | | --- | --- | | SqsParameters, SnsParameters, KinesisParameters, HttpParameters, e EventBusV2Parameters.Metadata | Un oggetto di input, per evento | | LambdaParameters, StepFunctionsParameters e EventBusV2Parameters.DeduplicationConfiguration | Una serie di oggetti di input, per chiamata | | UniversalTargetParameters.Input | Una serie di oggetti di input, per chiamata | Un'espressione del parametro target deve restituire una stringa, a meno che il campo non definisca un altro tipo; `UniversalTargetParameters.Input` può restituire qualsiasi valore JSON che costituisce la richiesta API. In un parametro con valori di mappa, sia le chiavi che i valori della stringa possono essere espressioni:`SqsParameters.MessageAttributes.{{name}}.StringValue`,`SqsParameters.MessageSystemAttributes.{{name}}.StringValue`, `SnsParameters.MessageAttributes.{{name}}.StringValue` e. `HttpParameters.QueryStringParameters.{{key}}` `EventBusV2Parameters.Metadata.{{key}}` L'attributo `BinaryValue` di un messaggio di Amazon SQS o Amazon SNS è un valore letterale Base64 che EventBridge non viene mai valutato, quindi `"BinaryValue": "AQID"` raggiunge l'obiettivo in byte; da utilizzare per un'espressione. `0x01 0x02 0x03` `StringValue` Per un target API Gateway, ogni `HttpParameters.HeaderParameters` chiave deve essere letterale; un target di destinazione API consente anche espressioni nelle chiavi di intestazione. EventBridge rifiuta un'intestazione che sostituirebbe la richiesta signing: `Authorization` e qualsiasi intestazione che `Host` inizia con. `X-Amz` Ogni singola `$now()` `$millis()` chiamata entro una risoluzione dei parametri di un abbonato restituisce lo stesso timestamp. ## Funziona oltre lo standard JSonata Oltre alla libreria JSonata standard, sono disponibili sei funzioni. | Funzione | Risultato | | --- | --- | | $hash(input, algorithm) | Digest esadecimale minuscolo. algorithmfa distinzione tra maiuscole e minuscole:MD5,,, o SHA-1 SHA-256 SHA-384 SHA-512 | | $uuid() | Un UUID della versione 4 | | $parse(jsonString) | Il JSON analizzato; un errore se la stringa non è un JSON valido | | $partition(array, chunkSize) | L'array è diviso in blocchi | | $range(start, end, delta) | Un intervallo numerico; tutti e tre gli argomenti sono obbligatori e il risultato è limitato a 10.000.000 di elementi | | $random(seed) | Un numero in [0, 1); lo stesso seme dà lo stesso numero | La `$eval` funzione non è disponibile. ## Limiti e guasti Un'`Transformer`espressione e ogni espressione del parametro di destinazione possono contenere fino a 8.192 caratteri; un'espressione universale di destinazione può contenere fino a `Input` 262.144. EventBridge controlla la sintassi quando si crea o si aggiorna il sottoscrittore e rifiuta un'espressione non valida con. `InvalidInputException` Alla consegna, un'espressione può essere eseguita per un secondo, utilizzare una profondità dello stack di 100 e allocare 10 MiB. Un'espressione che genera, supera tali limiti o produce `null` o `undefined` fallisce la consegna di quell'evento. EventBridge riprova con quello dell'abbonato`RetryPolicy`, quindi invia l'evento alla destinazione in caso di errore, se ne è stata configurata una. La `EventTransformationFailures` metrica conta ogni errore, un record di `EVENT_TRANSFORMATION_FAILURE` log riporta l'errore e il record in lettera morta è. `errorCode` `INPUT_TRANSFORMATION_FAILURE` Consulta [Osservabilità per il Custom Event Bus: metriche, registri e CloudTrail](eb-custom-bus-observability.md) e [Policy di ripetizione dei tentativi e code DLQ](eb-custom-bus-retry.md).