Transformation d'entrée Amazon EventBridge Pipes

Amazon EventBridge Pipes prend en charge les transformateurs d'entrée facultatifs lors du transfert de 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 de cible. Pour Amazon API Gateway et les destinations d'API, voici comment modeler l'événement d'entrée dans le modèle RESTful de votre API. Les transformateurs d'entrée sont modélisés sous forme de paramètre InputTemplate. 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 en ligne 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 correspond à ce qui est renvoyé par l'enrichissement, si une telle charge est configurée sur le canal. Outre les données propres au service incluses dans la charge utile de l'événement, vous pouvez utiliser des variables réservées dans InputTemplate pour référencer les données de votre canal.

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

Note

EventBridge ne prend pas en charge l'ensemble de la syntaxe du chemin JSON et l'évalue lors de l'exécution. La syntaxe prise en charge inclut :

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

• tirets

• traits de soulignement

• caractères alphanumériques

• index de tableau

• caractères génériques (*)

Voici des exemples de paramètres InputTemplate 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 dans un tableau :

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

Note

EventBridge remplace 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 d'entrée peuvent utiliser les variables réservées suivantes :

• <aws.pipes.pipe-arn> : Amazon Resource Name (ARN) du canal.

• <aws.pipes.pipe-name> : nom du canal.

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

• <aws.pipes.enrichment-arn> : ARN de l'enrichissement du canal.

• <aws.pipes.target-arn> : ARN de la cible du canal.

• <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 de l'enrichissement et le transformateur d'entrée de la cible, selon le moment où l'enrichissement a terminé de traiter l'événement.

• <aws.pipes.event> : é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 de la source, ainsi que des métadonnées supplémentaires propres au service. Pour obtenir des exemples propres à un service, consultez Sources d'Amazon EventBridge Pipes.

  Pour un transformateur d'entrée de 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 l'enrichissement peut ne pas être au format JSON. Si aucun enrichissement n'est configuré sur le canal, il s'agit de l'événement provenant de la source avec des 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 au format JSON. Si le canal contient un champ codé, tel que le champ body Amazon SQS ou data Kinesis, ces champs sont décodés et convertis au format JSON valide. Comme elle n'est pas mise en échappement, la variable ne peut être utilisée que comme valeur pour un champ JSON. Pour de plus amples informations, veuillez consulter Analyse implicite des données de corps.

Exemple de transformation d'entrée

Voici un exemple d'événement Amazon EC2 que nous pouvons utiliser comme exemple 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 code JSON suivant comme transformateur.

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

La sortie générée est la suivante :

{
  "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 de corps

Les champs suivants de la charge utile entrante peuvent être mis en échappement dans le code JSON, tels que l'objet Amazon SQS body, ou codés en base64, tels que l'objet Kinesis data. Pour le filtrage et la transformation d'entrée, EventBridge transforme ces champs au format 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 de corps, propres à 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"}), l'utilisation du transformateur d'entrée avec des données de corps propres à la source entraînera la suppression des guillemets contenus dans la charge utile source d'origine. Par exemple, {"key": "value"} deviendra "{key: value}" une fois livré à la cible. Si votre cible requiert des charges utiles JSON valides (par exemple, EventBridge Lambda 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 code JSON non valide, encapsulez le transformateur d'entrée des données de corps source au format JSON. Par exemple, {"data": <$.data>}.

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

Note

Si la charge utile d'origine est au format JSON valide, ce champ contient le code JSON non mis en échappement et non codé en base64. Toutefois, si la charge utile n'est pas au format JSON valide, EventBridge code en base64 les champs répertoriés ci-dessous, à l'exception d'Amazon SQS.

• Active MQ : data

• Kinesis : data

• Amazon MSK : key et value

• Rabbit MQ : data

• Apache Kafka autogéré : key et value

• Amazon SQS : body

Problèmes courants liés à la transformation d'entrée

Les problèmes courants qui se produisent lors de la transformation d'entrées dans EventBridge Pipes sont les suivants :

• 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 à mettre en correspondance avec 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.

• Les propriétés JSON telles que aws.pipes.event.json ne peuvent être utilisées que comme valeur d'un champ JSON, et non en ligne dans d'autres chaînes.

• EventBridge ne met pas en échappement les valeurs extraites par le chemin d'entrée lors du remplissage du modèle d'entrée pour 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, EventBridge supprime tous les guillemets internes pour garantir la validité de la chaîne. Par exemple, "Body is <$.body>" obligerait EventBridge à supprimer 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, mais EventBridge Pipes 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 code JSON valide. EventBridge Pipes 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>
  }

  Le résultat est un code JSON valide avec des guillemets appropriés :

  {
    "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 livrés à 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 de plus amples informations, veuillez consulter Traitement par lots et simultanéité d'Amazon EventBridge Pipes.