Transformación de entradas de Amazon EventBridge Pipes - Amazon EventBridge

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Transformación de entradas de Amazon EventBridge Pipes

Amazon EventBridge Pipes admite transformadores de entrada opcionales al transferir datos al enriquecimiento y al destino. Puede utilizar los transformadores de entrada para modificar la forma de la carga de entrada del evento JSON a fin de satisfacer las necesidades del servicio de enriquecimiento o de destino. En el caso de Amazon API Gateway y los destinos de API, así es como se configura el evento de entrada según el modelo RESTful de la API. Los transformadores de entrada se modelan como un parámetro InputTemplate. Pueden ser texto libre, una ruta JSON a la carga del evento o un objeto JSON que incluye rutas JSON en línea a la carga del evento. Para el enriquecimiento, la carga del evento proviene del origen. En el caso de los destinos, la carga del evento es la que se devuelve desde el enriquecimiento, si hay alguna configurada en la canalización. Además de los datos específicos del servicio en la carga del evento, puede usar variables reservadas en su InputTemplate para hacer referencia a datos para la canalización.

Para acceder a los elementos de una matriz, use la notación entre corchetes.

nota

EventBridge no admite toda la sintaxis de ruta JSON y la evalúa en tiempo de ejecución. La sintaxis admitida incluye:

  • notación de puntos (por ejemplo, $.detail)

  • guiones

  • guiones bajos

  • Caracteres alfanuméricos

  • índices de matrices

  • caracteres comodín (*)

Los siguientes son ejemplos de parámetros InputTemplate que hacen referencia a una carga de eventos de Amazon SQS:

Cadena estática

InputTemplate: "Hello, sender"

Ruta JSON

InputTemplate: <$.attributes.SenderId>

Cadena dinámica

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

JSON estático

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

JSON dinámico

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

Uso de la notación entre corchetes para acceder a los elementos de una matriz:

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

EventBridge reemplaza a los transformadores de entrada en tiempo de ejecución para garantizar una salida JSON válida. Por este motivo, debe colocar comillas alrededor de las variables que hagan referencia a los parámetros de ruta JSON, pero no alrededor de las variables que hagan referencia a objetos o matrices JSON.

Variables reservadas

Las plantillas de entrada pueden utilizar las siguientes variables reservadas:

  • <aws.pipes.pipe-arn>: el Nombre de recurso de Amazon (ARN) para la canalización.

  • <aws.pipes.pipe-name>: el nombre de la canalización.

  • <aws.pipes.source-arn>: el ARN del origen del evento de la canalización.

  • <aws.pipes.enrichment-arn>: el ARN del enriquecimiento de la canalización.

  • <aws.pipes.target-arn>: el ARN del destino de la canalización.

  • <aws.pipes.event.ingestion-time>: la hora a la que el transformador de entrada recibió el evento. Se trata de una marca de tiempo ISO 8601. Esta hora es diferente para el transformador de entrada de enriquecimiento y el transformador de entrada de destino, según el momento en que el enriquecimiento haya completado el procesamiento del evento.

  • <aws.pipes.event>: el evento recibido pro el transformador de entrada.

    En el caso de un transformador de entrada de enriquecimiento, este es el evento del origen. Contiene la carga original del origen, además de metadatos específicos de los servicios adicionales. Consulte los temas en Fuentes de Amazon EventBridge Pipes para obtener ejemplos específicos de este servicio.

    En el caso de un transformador de entrada de destino, este es el evento devuelto por el enriquecimiento, si hay alguno configurado, sin metadatos adicionales. Por lo tanto, una carga devuelta por el enriquecimiento puede no ser un valor JSON. Si no se configura ningún enriquecimiento en la canalización, se trata del evento del origen con los metadatos.

  • <aws.pipes.event.json>: igual que aws.pipes.event, pero la variable solo tiene un valor si la carga original, ya sea del origen o devuelta por el enriquecimiento, es un valor JSON. Si la canalización tiene un campo codificado, como el campo body de Amazon SQS o el campo data de Kinesis, esos campos se decodifican y se convierten en un valor JSON válido. Como no está oculta, la variable solo se puede usar como valor para un campo JSON. Para obtener más información, consulte Análisis implícito de datos del cuerpo.

Ejemplos de transformación de entrada

El siguiente es un ejemplo de un evento de Amazon EC2 que podemos usar como evento de muestra.

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

Usemos el siguiente valor JSON como transformador.

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

Se generará la siguiente salida:

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

Análisis implícito de datos del cuerpo

Los siguientes campos de la carga entrante pueden ser valores JSON ocultos, como el objeto body de Amazon SQS, o valores codificados en base64, como el objeto data de Kinesis. Tanto para el filtrado como para la transformación de entradas, EventBridge transforma estos campos en un valor JSON válido para que se pueda hacer referencia a los subvalores directamente. Por ejemplo, <$.data.someKey> para Kinesis.

Para que el destino reciba la carga original sin ningún metadato adicional, utilice un transformador de entrada con estos datos del cuerpo, específicos del origen. Por ejemplo, <$.body> para Amazon SQS o <$.data> para Kinesis. Si la carga original es una cadena JSON válida (por ejemplo, {"key": "value"}), el uso del transformador de entrada con datos del cuerpo específicos del origen hará que se eliminen las comillas de la carga de origen original. Por ejemplo, {"key": "value"} se convertirá en "{key: value}" cuando se entregue al destino. Si el destino requiere cargas JSON válidas (por ejemplo, EventBridge Lambda o Step Functions), se producirá un error en la entrega. Para que el destino reciba los datos de origen originales sin generar un valor JSON no válido, empaquete el transformador de entrada de los datos del cuerpo del origen en formato JSON. Por ejemplo, {"data": <$.data>}.

El análisis del cuerpo implícito también se puede utilizar para rellenar dinámicamente los valores de la mayoría de los parámetros de enriquecimiento o de destino de la canalización. Para obtener más información, consulte Parámetros de ruta dinámicos

nota

Si la carga original es un valor JSON válido, este campo contendrá el valor JSON sin ocultar ni codificar en base64. Sin embargo, si la carga no es un valor JSON válido, EventBridge codifica en base64 los campos que se indican a continuación, con la excepción de Amazon SQS.

  • Active MQdata

  • Kinesisdata

  • Amazon MSK, y key value

  • Rabbit MQ — data

  • Apache Kafka autoadministrado;key y value

  • Amazon SQSbody

Problemas comunes con la transformación de entradas

Estos son algunos problemas comunes cuando se transforma la entrada en EventBridge:

  • Para cadenas, se requieren comillas.

  • No hay validación al crear la ruta JSON para la plantilla.

  • Si especifica una variable que coincida con una ruta JSON que no existe en el evento, dicha variable no se crea ni aparece en la salida.

  • Las propiedades JSON como aws.pipes.event.json solo se pueden usar como el valor de un campo JSON, no en línea en otras cadenas.

  • EventBridge no oculta valores extraídos por la ruta de entrada al rellenar la plantilla de entrada para un destino.

  • Si una ruta JSON hace referencia a un objeto o matriz JSON, pero se hace referencia a la variable en una cadena, EventBridge elimina las comillas internas para garantizar la validez de la cadena. Por ejemplo, en "Cuerpo es <$.body>", EventBridge eliminaría las comillas del objeto.

    Por lo tanto, si quiere generar un objeto JSON basado en una única variable de ruta JSON, debe colocarlo como clave. En este ejemplo, {"body": <$.body>}.

  • No se requieren comillas para las variables que representan cadenas. Están permitidas, pero EventBridge Pipes añade automáticamente comillas a los valores de las variables de cadena durante la transformación, para garantizar que el resultado de la transformación tenga un formato JSON válido. EventBridge Pipes no añade comillas a las variables que representan objetos o matrices JSON. No añada comillas a las variables que representan objetos o matrices JSON.

    Por ejemplo, la siguiente plantilla de entrada incluye variables que representan tanto cadenas como objetos JSON:

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

    El resultado es un formato JSON válido con las comillas adecuadas:

    { "pipeArn" : "arn:aws:events:us-east-2:123456789012:pipe/example", "pipeName" : "example", "originalEvent" : { ... // commented for brevity } }
  • Para los enriquecimientos o destinos de Lambda o Step Functions, los lotes se entregan al destino como matrices JSON, incluso si el tamaño del lote es 1. Sin embargo, los transformadores de entrada se seguirán aplicando a los registros individuales de la matriz JSON, no a la matriz en su conjunto. Para obtener más información, consulte Procesamiento por lotes y simultaneidad de Amazon EventBridge Pipes.