AmazonEventBridgeTransformation des tuyaux en entrée

AmazonEventBridgeLes tubes supportent des transformateurs d'entrée optionnels lorsqu'ils transmettent des données à l'enrichissement et à la cible. Vous pouvez utiliser des transformateurs d'entrée pour remodeler la charge utile d'entrée des événements JSON afin de répondre aux besoins du service d'enrichissement ou du service cible. Pour Amazon API Gateway et les destinations d'API, voici comment vous façonnez l'événement d'entrée dans le modèle RESTful de votre API. Les transformateurs d'entrée sont modélisés sous la forme d'unInputTemplateparamètre. Il peut s'agir de texte libre, d'un chemin JSON vers la charge utile de l'événement ou d'un objet JSON qui inclut des chemins JSON intégrés vers la charge utile de l'événement. Pour l'enrichissement, la charge utile de l'événement provient de la source. Pour les cibles, la charge utile de l'événement est celle renvoyée par l'enrichissement, si une telle charge est configurée sur le canal. Outre les données spécifiques au service incluses dans la charge utile de l'événement, vous pouvez utiliservariables réservéesdans votreInputTemplatepour référencer les données de votre tube.

Pour accéder aux éléments d'un tableau, utilisez la notation entre crochets.

Note

EventBridgene prend pas en charge toutes les syntaxes JSON Path et ne l'évalue pas lors de l'exécution. La syntaxe prise en charge inclut :

• notation par points (par exemple,$.detail)

• tirets

• souligne

• caractères alphanumériques

• indices matriciels

• jokers (*)

Voici des exemplesInputTemplateparamètres faisant référence à la charge utile d'un événement Amazon SQS :

Chaîne statique

InputTemplate: "Hello, sender"

Chemin JSON

InputTemplate: <$.attributes.SenderId>

Chaîne dynamique

InputTemplate: "Hello, <$.attributes.SenderId>"

JSON statique

InputTemplate: >
{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3",
}

JSON dynamique

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.key>,
  "d": <aws.pipes.event.ingestion-time>
}

Utilisation de la notation entre crochets pour accéder à un élément d'un tableau :

InputTemplate: >
{
  "key1": "value1"
  "key2": <$.body.Records[3]>,
  "d": <aws.pipes.event.ingestion-time>
}

Note

EventBridgeremplace les transformateurs d'entrée lors de l'exécution pour garantir une sortie JSON valide. Pour cette raison, placez des guillemets autour des variables qui font référence aux paramètres de chemin JSON, mais ne placez pas de guillemets autour des variables qui font référence à des objets ou à des tableaux JSON.

Variables réservées

Les modèles de saisie peuvent utiliser les variables réservées suivantes :

• <aws.pipes.pipe-arn>— Le nom de ressource Amazon (ARN) du canal.

• <aws.pipes.pipe-name>— Le nom du tube.

• <aws.pipes.source-arn>— L'ARN de la source d'événement du canal.

• <aws.pipes.enrichment-arn>— L'ARN de l'enrichissement du tuyau.

• <aws.pipes.target-arn>— L'ARN de la cible du tube.

• <aws.pipes.event.ingestion-time>— Heure à laquelle l'événement a été reçu par le transformateur d'entrée. Il s'agit d'un horodatage ISO 8601. Cette durée est différente pour le transformateur d'entrée d'enrichissement et le transformateur d'entrée cible, selon le moment où l'enrichissement a terminé de traiter l'événement.

• <aws.pipes.event>— L'événement tel qu'il a été reçu par le transformateur d'entrée.

  Pour un transformateur d'entrée d'enrichissement, il s'agit de l'événement provenant de la source. Il contient la charge utile d'origine provenant de la source, ainsi que des métadonnées supplémentaires spécifiques au service. Voir les sujets dansSources d'AmazonEventBridge Pipespour des exemples spécifiques à un service.

  Pour un transformateur d'entrée cible, il s'agit de l'événement renvoyé par l'enrichissement, s'il est configuré, sans métadonnées supplémentaires. En tant que telle, une charge utile renvoyée par enrichissement peut être non JSON. Si aucun enrichissement n'est configuré sur le canal, il s'agit de l'événement provenant de la source avec les métadonnées.

• <aws.pipes.event.json>— Identique àaws.pipes.event, mais la variable n'a de valeur que si la charge utile d'origine, provenant de la source ou renvoyée par l'enrichissement, est JSON. Si le canal contient un champ codé, tel que Amazon SQSbodychamp ou Kinesisdata, ces champs sont décodés et transformés en JSON valide. Comme elle n'est pas échappée, la variable ne peut être utilisée que comme valeur pour un champ JSON. Pour plus d'informations, veuillez consulter Analyse implicite des données corporelles.

Exemple de transformation d'entrée

Voici un exemple d'événement Amazon EC2 que nous pouvons utiliser commeexemple d'événement.

{
  "version": "0",
  "id": "7bf73129-1428-4cd3-a780-95db273d1602",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "123456789012",
  "time": "2015-11-11T21:29:54Z",
  "region": "us-east-1",
  "resources": [
    "arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111"
  ],
  "detail": {
    "instance-id": "i-0123456789",
    "state": "RUNNING"
  }
}
		

Utilisons le JSON suivant comme notreTransformateur.

{
  "instance" : <$.detail.instance-id>,
  "state": <$.detail.state>,
  "pipeArn" : <aws.pipes.pipe-arn>,
  "pipeName" : <aws.pipes.pipe-name>,
  "originalEvent" : <aws.pipes.event.json>
}

Ce qui suit sera le résultatSortie:

{
  "instance" : "i-0123456789",
  "state": "RUNNING",
  "pipeArn" : "arn:aws:pipe:us-east-1:123456789012:pipe/example",
  "pipeName" : "example",
  "originalEvent" : {
    ... // commented for brevity
  }
}

Analyse implicite des données corporelles

Les champs suivants de la charge utile entrante peuvent être échappés au JSON, tels que Amazon SQSbodyobjet, ou codé en base64, tel que le Kinesisdataobjet. Pour les deuxfiltrageet transformation des entrées,EventBridgetransforme ces champs en JSON valide afin que les sous-valeurs puissent être référencées directement. Par exemple,<$.data.someKey>pour Kinesis.

Pour que la cible reçoive la charge utile d'origine sans aucune métadonnée supplémentaire, utilisez un transformateur d'entrée avec ces données corporelles, spécifiques à la source. Par exemple,<$.body>pour Amazon SQS, ou<$.data>pour Kinesis. Si la charge utile d'origine est une chaîne JSON valide (par exemple{"key": "value"}), puis l'utilisation du transformateur d'entrée avec des données corporelles spécifiques à la source entraînera la suppression des guillemets de la charge utile source d'origine. Par exemple,{"key": "value"}deviendra"{key: value}"lorsqu'il est livré à la cible. Si votre cible nécessite des charges utiles JSON valides (par exemple,EventBridgeLambda ou Step Functions), cela entraînera un échec de livraison. Pour que la cible reçoive les données source d'origine sans générer de JSON non valide, encapsulez le transformateur d'entrée des données du corps source dans du JSON. Par exemple, {"data": <$.data>}.

L'analyse corporelle implicite peut également être utilisée pour renseigner dynamiquement les valeurs de la plupart des paramètres de cible ou d'enrichissement du tube. Pour de plus amples informations, consultez Paramètres de trajectoire dynamiques.

Note

Si la charge utile d'origine est un JSON valide, ce champ contiendra le JSON non échappé et non codé en base64. Toutefois, si la charge utile n'est pas un JSON valide,EventBridgeEncode en base64 pour les champs répertoriés ci-dessous, à l'exception d'Amazon SQS.

• MQ actif—data

• Kinésis—data

• Amazon MSK—keyetvalue

• Lapin MQ—data

• Apache Kafka autogéré ;—keyetvalue

• Amazon SQS—body

Problèmes courants liés à la transformation des entrées

Voici quelques problèmes courants lors de la transformation des entrées dansEventBridgetuyaux :

• Pour les chaînes, des guillemets sont requis.

• Il n'y a pas de validation lors de la création du chemin JSON pour votre modèle.

• Si vous spécifiez une variable correspondant à un chemin JSON qui n'existe pas dans l'événement, cette variable n'est pas créée et n'apparaîtra pas dans la sortie.

• Des propriétés JSON telles queaws.pipes.event.jsonne peut être utilisé que comme valeur d'un champ JSON, et non en ligne dans d'autres chaînes.

• EventBridgen'échappe pas aux valeurs extraites parChemin d'entrée, lors du remplissage duModèle de saisiepour une cible.

• Si un chemin JSON fait référence à un objet ou à un tableau JSON, mais que la variable est référencée dans une chaîne,EventBridgesupprime tous les guillemets internes pour garantir une chaîne valide. Par exemple, « Body is <$.body> » entraîneraitEventBridgesupprimer les guillemets de l'objet.

  Par conséquent, si vous souhaitez générer un objet JSON basé sur une seule variable de chemin JSON, vous devez le placer sous forme de clé. Dans cet exemple,{"body": <$.body>}.

• Les guillemets ne sont pas obligatoires pour les variables qui représentent des chaînes. Ils sont autorisés, maisEventBridgePipes ajoute automatiquement des guillemets aux valeurs des variables de chaîne pendant la transformation, afin de garantir que le résultat de la transformation est un JSON valide. EventBridgePipes n'ajoute pas de guillemets aux variables qui représentent des objets ou des tableaux JSON. N'ajoutez pas de guillemets pour les variables qui représentent des objets ou des tableaux JSON.

  Par exemple, le modèle d'entrée suivant inclut des variables qui représentent à la fois des chaînes et des objets JSON :

  {
    "pipeArn" : <aws.pipes.pipe-arn>,
    "pipeName" : <aws.pipes.pipe-name>,
    "originalEvent" : <aws.pipes.event.json>
  }

  Résultat : JSON valide avec une citation appropriée :

  {
    "pipeArn" : "arn:aws:events:us-east-2:123456789012:pipe/example",
    "pipeName" : "example",
    "originalEvent" : {
      ... // commented for brevity
    }
  }

• Pour les enrichissements ou les cibles Lambda ou Step Functions, les lots sont fournis à la cible sous forme de tableaux JSON, même si la taille du lot est de 1. Cependant, les transformateurs d'entrée seront toujours appliqués aux enregistrements individuels du tableau JSON, et non au tableau dans son ensemble. Pour plus d'informations, veuillez consulter AmazonEventBridgeMise en lots de tuyaux et simultanéité.