Transformer les événements avec JSonata

Pour modifier ce que reçoit une cible, Transformer activez CreateSubscriber ouUpdateSubscriber. Transformer.TypeRAW, la valeur par défaut, fournit les données publiées uniquement ; WITH_METADATA fournit les données avec leurs métadonnées ; et JSONATA fournit le résultat d'une expression, par exemple{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}. Un abonné dont la cible est un Custom Event Bus - Classic est uniquement pris en chargeRAW. Une cible universelle n'utilise pas Transformer ; elle façonne sa demande UniversalTargetParameters.Input en utilisant les mêmes expressions.

Type de transformateur	À utiliser lorsque	Charge utile cible
RAW	La cible a besoin des données d'événement publiées	Les données publiées, inchangées. Valeur par défaut.
WITH_METADATA	La cible a besoin des données et de leurs métadonnées	Une enveloppe JSON avec DataMetadata, et SystemMetadata
JSONATA	La cible a besoin de valeurs sélectionnées ou d'une nouvelle forme	Le résultat d'une expression JSonata par événement

Ce que propose $events

WITH_METADATAJSONATA, et chaque expression de paramètre cible lit le même objet d'entrée, qu'une expression JSonata considère comme tel. $events Il comporte trois parties.

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

• Datareprésente les données publiées et conserve leur type JSON : un objet, un tableau, une chaîne, un nombre, un booléen ou une valeur nulle. Car PutRawEvents il s'agit de la Data valeur de l'entrée, donc un identifiant de commande se trouve à$events.Data.orderId. Car PutEvents il s'agit de l' EventBridge enveloppe entièreversion, avec iddetail-type,source,,account,time, regionresources, etdetail, donc le même identifiant se trouve à$events.Data.detail.orderId. Car application/octet-stream il s'agit d'une chaîne Base64 ; voirTransformation de données binaires.

• Metadataest la carte chaîne à chaîne avec laquelle le producteur a défini. PutRawEvents PutEventsne prend aucune métadonnée, donc pour ses événements, la carte est vide.

• SystemMetadatacontient les champs EventBridge assignés. Chaque valeur est une chaîne. EventBridgeomet un champ facultatif qui n'a aucune valeur, et un champ omis est évalué comme undefined dans JSonata ; seul est toujours présent. aws:DeliveryType ContentTypeconserve la valeur publiée, de sorte que les données Avro et Protobuf EventBridge décodées au format JSON s'affichent toujours application/avro ou application/protobuf ici, et un événement s'affiche. PutEvents application/eventbridge+json Pour chaque champ, voirSystemMetadata champs.

Citez un nom de champ contenant deux points, comme dans$events.SystemMetadata."aws:EventId".

Création d'une charge utile cible avec JSonata

Définissez Transformer.Type JSONATA et insérez une expression complète, entourée de {% et %}JsonataConfiguration.Expression. Pour une PutRawEvents entrée dont les données sont{"orderId": "12345", "priority": "high", "items": [...]}, le transformateur suivant fournit uniquement les deux champs nommés.

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

La cible reçoit{"orderId": "12345", "priority": "high"}. EventBridge évalue l'expression une fois pour chaque événement, avant le traitement par lots. Le type du résultat détermine ce que la cible reçoit.

Résultat de l'expression	Charge utile cible
Chaîne	La chaîne, sans guillemets JSON
Objet ou tableau	L'objet ou le tableau JSON sérialisé. Un élément null imbriqué à l'intérieur reste JSONnull.
Nombre ou booléen	La valeur JSON sérialisée
null ou undefined	Un échec de transformation ; voir Limites et défaillances

Transformation de données binaires

Lorsque SystemMetadata.ContentType c'est le casapplication/octet-stream, EventBridge stocke les octets publiés sans les analyser et les expose à une expression sous forme de chaîne Base64 dans. $events.Data Les octets de hello arrivent en tant que$events.Data = "aGVsbG8=". EventBridge n'analyse pas cette chaîne au format JSON même lorsque les octets décodés sont du texte JSON. Vérifiez donc ContentType avant d'interpréter et Data utilisez-le $base64decode($events.Data) uniquement lorsque les octets d'origine sont du texte.

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

Le type de transformateur détermine la manière dont les octets atteignent la cible. Seul RAW peut transmettre le tableau d'octets d'origine.

Type de transformateur	Ce que reçoit la cible
RAW	Les octets d'origine, pour les cibles Kinesis, Firehose, API Gateway et Custom Event Bus. Texte Base64, pour les cibles Amazon SQS et Amazon SNS. Chaîne JSON contenant le texte Base64, pour les cibles de destination Lambda, Step Functions, Custom Event Bus - Classic et API ; une invocation Lambda ou Step Functions par lots reçoit un tableau de ces chaînes.
WITH_METADATA	L'enveloppe au format UTF-8 JSON, Data contenant le texte Base64
JSONATA	Le résultat de l'expression sous forme de UTF-8 texte ou de JSON ; l'expression lit le texte Base64

Un transformateur ne peut pas se réglerContentType. Lorsque la cible est un autre bus d'événements personnalisé, EventBridge copie la valeur publiée, sauf que les données Avro et Protobuf sont fournies au format JSON et arrivent donc telles quelles. application/json

Utilisation de JSonata dans les paramètres cibles

Un paramètre cibleInvokeConfiguration, tel queSqsParameters.MessageGroupId, contient soit une valeur littérale, soit une expression JSonata complète entourée de et. {% %} EventBridge n'évalue pas une expression incorporée dans une chaîne plus longue. Les expressions des paramètres cibles lisent l'objet d'entrée d'origine, et non la charge utile Transformer produite. Les paramètres Amazon SQS suivants prennent les valeurs FIFO de chaque événement.

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

Ce qui $events est valable dépend du paramètre. Les paramètres résolus EventBridge par événement ne voient qu'un seul objet d'entrée. Les paramètres qu'il résout une fois par appel de cible voient un tableau d'objets d'entrée, un par événement du lot, donc le premier événement est$events[0].Data.

Parameters	$eventsdétient
SqsParameters, SnsParameters, KinesisParameters, HttpParameters et EventBusV2Parameters.Metadata	Un objet d'entrée, par événement
LambdaParameters, StepFunctionsParameters et EventBusV2Parameters.DeduplicationConfiguration	Un tableau d'objets d'entrée, par invocation
UniversalTargetParameters.Input	Un tableau d'objets d'entrée, par invocation

Une expression de paramètre cible doit renvoyer une chaîne, sauf si le champ définit un autre type ; elle UniversalTargetParameters.Input peut renvoyer n'importe quelle valeur JSON qui constitue la demande d'API. Dans un paramètre à valeur cartographique, les clés et les valeurs de chaîne peuvent être des expressions :SqsParameters.MessageAttributes.name.StringValue, SqsParameters.MessageSystemAttributes.name.StringValue SnsParameters.MessageAttributes.name.StringValueHttpParameters.QueryStringParameters.key, et. EventBusV2Parameters.Metadata.key L'attribut BinaryValue d'un message Amazon SQS ou Amazon SNS est une valeur littérale en Base64 qui EventBridge n'est jamais évaluée. Elle "BinaryValue": "AQID" atteint donc la cible en octets 0x01 0x02 0x03 ; à utiliser pour une expression. StringValue

Pour une cible API Gateway, chaque HttpParameters.HeaderParameters clé doit être un littéral ; une cible de destination API autorise également les expressions dans les clés d'en-tête. EventBridge rejette un en-tête qui remplacerait la requête signing : AuthorizationHost, et tout en-tête commençant X-Amz par. Chaque $millis() appel $now() et correspondant à une résolution des paramètres d'un abonné renvoie le même horodatage.

Fonctions allant au-delà de la norme JSonata

Outre la bibliothèque JSonata standard, six fonctions sont disponibles.

Fonction	Résultat
$hash(input, algorithm)	Résumé hexadécimal en minuscules. algorithmfait la distinction entre majuscules et minuscules : MD5SHA-1,SHA-256,SHA-384, ou SHA-512
$uuid()	Un UUID version 4
$parse(jsonString)	Le JSON analysé ; une erreur si la chaîne n'est pas un JSON valide
$partition(array, chunkSize)	Le tableau s'est divisé en morceaux
$range(start, end, delta)	Une plage numérique ; les trois arguments sont obligatoires et le résultat est plafonné à 10 000 000 éléments
$random(seed)	Un nombre entre [0, 1) ; la même graine donne le même numéro

La $eval fonction n'est pas disponible.

Limites et défaillances

Une Transformer expression et chaque expression de paramètre cible peuvent comporter jusqu'à 8 192 caractères ; une Input expression de cible universelle peut comporter jusqu'à 262 144 caractères. EventBridge vérifie la syntaxe lorsque vous créez ou mettez à jour l'abonné et rejette une expression non valide avecInvalidInputException. Lors de la livraison, une expression peut s'exécuter pendant une seconde, utiliser une profondeur de pile de 100 et allouer 10 Mo.

Expression qui génère, dépasse ces limites, produit null ou undefined échoue à délivrer cet événement. EventBridge réessaie sous celui de l'abonnéRetryPolicy, puis envoie l'événement à la destination en cas d'échec si une telle destination est configurée. La EventTransformationFailures métrique compte chaque échec, un enregistrement de EVENT_TRANSFORMATION_FAILURE journal contient l'erreur et celui en lettre morte l'esterrorCode. INPUT_TRANSFORMATION_FAILURE Consultez Observabilité pour le bus d'événements personnalisé : métriques, journaux et CloudTrail et Politiques relatives aux nouvelles tentatives et files d'attente.