Transformieren von Ereignissen mit JSonata

Um zu ändern, was ein Ziel empfängt, setzen Sie Transformer auf CreateSubscriber oderUpdateSubscriber. Transformer.TypeRAW, die Standardeinstellung, liefert die veröffentlichten Daten allein, WITH_METADATA stellt die Daten zusammen mit ihren Metadaten JSONATA bereit und liefert beispielsweise das Ergebnis eines Ausdrucks{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}. Ein Abonnent, dessen Ziel ein Custom Event Bus ist, unterstützt nur ClassicRAW. Ein universelles Ziel verwendet es nichtTransformer; es formt seine Anfrage entsprechendUniversalTargetParameters.Input, wobei dieselben Ausdrücke verwendet werden.

Typ des Transformators	Anwendungsfall	Ziel-Nutzlast
RAW	Das Ziel benötigt die veröffentlichten Eventdaten	Die veröffentlichten Daten, unverändert. Der Standard.
WITH_METADATA	Das Ziel benötigt die Daten und ihre Metadaten	Ein JSON-Envelope mit DataMetadata, und SystemMetadata
JSONATA	Das Ziel benötigt ausgewählte Werte oder eine neue Form	Das Ergebnis eines JSONATA-Ausdrucks pro Ereignis

Was $events beinhaltet

WITH_METADATAJSONATA, und jeder Zielparameterausdruck liest dasselbe Eingabeobjekt, als das ein JSONata-Ausdruck betrachtet. $events Es besteht aus drei Teilen.

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

• Dataist die veröffentlichten Daten und behält ihren JSON-Typ bei: ein Objekt, ein Array, eine Zeichenfolge, eine Zahl, ein boolescher Wert oder Null. Denn PutRawEvents es ist der Data Wert des Eintrags, also ist eine Bestell-ID bei. $events.Data.orderId Denn PutEvents es ist der ganze EventBridge Umschlag, mit versionid,detail-type,source,,account,time, regionresources, unddetail, und, also ist dieselbe Kennung bei$events.Data.detail.orderId. Denn application/octet-stream es ist eine Base64-Zeichenfolge; sieheTransformieren von Binärdaten.

• Metadataist die String-zu-String-Map, die der Producer festgelegt hat. PutRawEvents PutEventsnimmt keine Metadaten an, daher ist die Map für ihre Ereignisse leer.

• SystemMetadataenthält die Felder und EventBridge weist sie zu. Jeder Wert ist eine Zeichenfolge. EventBridgelässt ein optionales Feld aus, das keinen Wert hat, und ein ausgelassenes Feld wird wie undefined in JSONata ausgewertet; nur aws:DeliveryType ist immer vorhanden. ContentTypebehält den veröffentlichten Wert bei, sodass Avro- und Protobuf-Daten, die in JSON EventBridge dekodiert wurden, weiterhin oder hier angezeigt werden und ein Ereignis angezeigt application/avro wird. application/protobuf PutEvents application/eventbridge+json Für jedes Feld siehe. SystemMetadata Felder

Geben Sie einen Feldnamen an, der einen Doppelpunkt enthält, wie in$events.SystemMetadata."aws:EventId".

Erstellen einer Zielnutzlast mit JSONata

Setzen Sie Transformer.Type auf JSONATA und fügen Sie einen vollständigen Ausdruck ein, eingeschlossen in {% und%}, in. JsonataConfiguration.Expression Für einen PutRawEvents Eintrag, dessen Daten gleich sind{"orderId": "12345", "priority": "high", "items": [...]}, liefert der folgende Transformator nur die beiden benannten Felder.

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

Das Ziel empfängt{"orderId": "12345", "priority": "high"}. EventBridge wertet den Ausdruck einmal für jedes Ereignis aus, vor der Stapelverarbeitung. Der Typ des Ergebnisses entscheidet, was das Ziel erhält.

Ergebnis des Ausdrucks	Ziel-Nutzlast
Zeichenfolge	Die Zeichenfolge ohne JSON-Anführungszeichen
Objekt oder Array	Das serialisierte JSON-Objekt oder Array. Ein darin null verschachteltes Objekt bleibt JSON. null
Zahl oder Boolescher Wert	Der serialisierte JSON-Wert
null oder undefined	Ein Transformationsfehler; siehe Grenzwerte und Ausfälle

Transformieren von Binärdaten

Wenn SystemMetadata.ContentType jaapplication/octet-stream, EventBridge werden die veröffentlichten Bytes gespeichert, ohne sie zu analysieren, und sie werden einem Ausdruck als Base64-Zeichenfolge in ausgesetzt. $events.Data Die Bytes von kommen als an. hello $events.Data = "aGVsbG8=" EventBridge analysiert diese Zeichenfolge nicht als JSON, auch wenn es sich bei den dekodierten Bytes um JSON-Text handelt. Prüfen Sie dies also, ContentType bevor Sie sie interpretierenData, und verwenden Sie sie $base64decode($events.Data) nur, wenn es sich bei den ursprünglichen Bytes um Text handelt.

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

Der Transformertyp entscheidet, wie die Bytes das Ziel erreichen. Nur das ursprüngliche Byte-Array RAW kann weitergeleitet werden.

Transformator-Typ	Was das Ziel erhält
RAW	Die ursprünglichen Byte für Kinesis-, Firehose-, API Gateway- und Custom Event Bus-Ziele. Base64-Text für Amazon SQS- und Amazon SNS-Ziele. Eine JSON-Zeichenfolge, die den Base64-Text für Lambda-, Step Functions-, Custom Event Bus — Classic- und API-Zielziele enthält; ein Batch-Aufruf von Lambda oder Step Functions erhält ein Array dieser Zeichenfolgen.
WITH_METADATA	Der Umschlag als UTF-8 JSON, der den Base64-Text enthält Data
JSONATA	Das Ausdrucksergebnis als UTF-8 Text oder JSON; der Ausdruck liest den Base64-Text

Ein Transformator kann nicht gesetzt ContentType werden. Wenn das Ziel ein anderer Custom Event Bus ist, wird der veröffentlichte Wert EventBridge kopiert, mit der Ausnahme, dass Avro- und Protobuf-Daten als JSON geliefert werden und daher als ankommen. application/json

Verwendung von JSONata in Zielparametern

Ein Zielparameter inInvokeConfiguration, z. B.SqsParameters.MessageGroupId, enthält entweder einen Literalwert oder einen vollständigen JSONata-Ausdruck, der in und eingeschlossen ist. {% %} EventBridge wertet keinen Ausdruck aus, der in eine längere Zeichenfolge eingebettet ist. Ausdrücke mit Zielparametern lesen das ursprüngliche Eingabeobjekt, nicht die Transformer erzeugte Nutzlast. Die folgenden Amazon SQS-Parameter übernehmen die FIFO-Werte von jedem Ereignis.

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

Was $events gilt, hängt vom Parameter ab. Für Parameter, die pro Ereignis EventBridge aufgelöst werden, wird ein Eingabeobjekt angezeigt. Für Parameter, die einmal pro Zielaufruf aufgelöst werden, wird ein Array von Eingabeobjekten angezeigt, eines pro Ereignis im Batch, also das erste Ereignis. $events[0].Data

Parameters	$eventshält
SqsParameters, SnsParameters, KinesisParameters, HttpParameters, und EventBusV2Parameters.Metadata	Ein Eingabeobjekt pro Ereignis
LambdaParameters, StepFunctionsParameters und EventBusV2Parameters.DeduplicationConfiguration	Ein Array von Eingabeobjekten pro Aufruf
UniversalTargetParameters.Input	Ein Array von Eingabeobjekten pro Aufruf

Ein Zielparameterausdruck muss eine Zeichenfolge zurückgeben, es sei denn, das Feld definiert einen anderen Typ. Er UniversalTargetParameters.Input kann jeden JSON-Wert zurückgeben, der die API-Anforderung bildet. In einem Parameter mit Kartenwert können sowohl die Schlüssel als auch die Zeichenfolgenwerte Ausdrücke sein:SqsParameters.MessageAttributes.name.StringValue, SqsParameters.MessageSystemAttributes.name.StringValue SnsParameters.MessageAttributes.name.StringValueHttpParameters.QueryStringParameters.key, und. EventBusV2Parameters.Metadata.key Bei einem Amazon SQS- oder Amazon SNS-Nachrichtenattribut handelt es sich um einen Base64-Literalwert, der EventBridge niemals ausgewertet wird, also das Ziel in Form von Byte "BinaryValue": "AQID" erreicht; für einen Ausdruck verwenden. BinaryValue 0x01 0x02 0x03 StringValue

Für ein API-Gateway-Ziel muss jeder HttpParameters.HeaderParameters Schlüssel ein Literal sein; ein API-Zielziel erlaubt auch Ausdrücke in Header-Schlüsseln. EventBridge lehnt einen Header ab, der das Signieren der Anforderung überschreiben würde: AuthorizationHost, und jeden Header, der mit beginnt. X-Amz Jeder $now() $millis() UND-Aufruf innerhalb einer Auflösung der Parameter eines Abonnenten gibt denselben Zeitstempel zurück.

Funktionen, die über das Standard-JSONATA hinausgehen

Zusätzlich zur Standard-JSonata-Bibliothek stehen sechs Funktionen zur Verfügung.

Funktion	Ergebnis
$hash(input, algorithm)	Hexadezimaler Digest in Kleinbuchstaben. algorithmunterscheidet zwischen Groß- und Kleinschreibung:MD5,,SHA-1, oder SHA-256 SHA-384 SHA-512
$uuid()	Eine UUID der Version 4
$parse(jsonString)	Das analysierte JSON; ein Fehler, wenn die Zeichenfolge kein gültiges JSON ist
$partition(array, chunkSize)	Das Array ist in Blöcke aufgeteilt
$range(start, end, delta)	Ein numerischer Bereich; alle drei Argumente sind erforderlich, und das Ergebnis ist auf 10.000.000 Elemente begrenzt
$random(seed)	Eine Zahl in [0, 1); derselbe Startwert ergibt dieselbe Zahl

Die $eval Funktion ist nicht verfügbar.

Grenzwerte und Ausfälle

Ein Transformer Ausdruck und jeder Zielparameterausdruck können bis zu 8.192 Zeichen lang sein; der Input Ausdruck eines universellen Ziels bis zu 262.144. EventBridge prüft die Syntax, wenn Sie den Abonnenten erstellen oder aktualisieren, und lehnt einen ungültigen Ausdruck mit ab. InvalidInputException Bei der Auslieferung kann ein Ausdruck eine Sekunde lang ausgeführt werden, eine Stapeltiefe von 100 verwenden und 10 MiB zuweisen.

Ein Ausdruck, der das Ereignis auslöst, diese Grenzwerte überschreitet oder die Übertragung des null Ereignisses hervorruft oder undefined fehlschlägt. EventBridge versucht es erneut unter dem Namen des Abonnenten und sendet dann das Ereignis an das ZielRetryPolicy, falls ein Fehler aufgetreten ist, sofern eines konfiguriert ist. Die EventTransformationFailures Metrik zählt jeden Fehler, ein EVENT_TRANSFORMATION_FAILURE Protokolldatensatz enthält den Fehler, und der Datensatz mit unleserem Buchstaben ist. errorCode INPUT_TRANSFORMATION_FAILURE Siehe Beobachtbarkeit für den Custom Event Bus: Metriken, Protokolle und CloudTrail und Richtlinien und Warteschlangen mit unzustellbaren Briefen wiederholen.