Trasformare gli eventi con JSonata

Per modificare ciò che riceve un bersaglio, imposta Transformer su CreateSubscriber oUpdateSubscriber. Transformer.TypeRAW, 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 utilizzaTransformer; modella la sua richiesta inUniversalTargetParameters.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_METADATAJSONATA, 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"
    }
}

• Datasono 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, timeregion, e resourcesdetail, quindi è lo stesso identificatore. $events.Data.detail.orderId Perché application/octet-stream è una stringa Base64; vedi. Trasformazione di dati binari

• Metadataè la mappa da stringa a stringa con cui il produttore ha impostato. PutRawEvents PutEventsnon accetta metadati, quindi per i suoi eventi la mappa è vuota.

• SystemMetadatacontiene 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 ContentTypemantiene 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

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.TypeImposta 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

Trasformazione di dati binari

In SystemMetadata.ContentType tal casoapplication/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. RAWPuò 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 inInvokeConfiguration, ad esempioSqsParameters.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	$eventsdetiene
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'Transformerespressione 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'abbonatoRetryPolicy, 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 e Criteri di riprova e code per lettere morte.