Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Transformer les événements avec JSonata Pour modifier ce que reçoit une cible, `Transformer` activez `CreateSubscriber` ou`UpdateSubscriber`. `Transformer.Type``RAW`, 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 charge`RAW`. 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_METADATA``JSONATA`, 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" } } ``` + `Data`repré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ère`version`, avec `id``detail-type`,`source`,,`account`,`time`, `region``resources`, et`detail`, donc le même identifiant se trouve à`$events.Data.detail.orderId`. Car `application/octet-stream` il s'agit d'une chaîne Base64 ; voir[Transformation de données binaires](#eb-custom-bus-transform-binary). + `Metadata`est la carte chaîne à chaîne avec laquelle le producteur a défini. `PutRawEvents` `PutEvents`ne prend aucune métadonnée, donc pour ses événements, la carte est vide. + `SystemMetadata`contient 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` `ContentType`conserve 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, voir[SystemMetadata champs](eb-custom-bus-addressing.md#eb-custom-bus-addressing-system). 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](#eb-custom-bus-transform-limits) | ## Transformation de données binaires Lorsque `SystemMetadata.ContentType` c'est le cas`application/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égler`ContentType`. 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 cible`InvokeConfiguration`, tel que`SqsParameters.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 | `$events`dé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}}.StringValue``HttpParameters.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 : `Authorization``Host`, 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 avec`InvalidInputException`. 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'est`errorCode`. `INPUT_TRANSFORMATION_FAILURE` Consultez [Observabilité pour le bus d'événements personnalisé : métriques, journaux et CloudTrail](eb-custom-bus-observability.md) et [Politiques relatives aux nouvelles tentatives et files d'attente](eb-custom-bus-retry.md).