Transformación de eventos con JSonata

Para cambiar lo que recibe un objetivo, Transformer defina CreateSubscriber oUpdateSubscriber. Transformer.TypeRAW, el valor predeterminado, entrega solo los datos publicados; WITH_METADATA entrega los datos con sus metadatos; y JSONATA entrega el resultado de una expresión, por ejemplo{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}. Un suscriptor cuyo objetivo sea un bus de eventos personalizado: el modo clásico solo lo admiteRAW. Un objetivo universal no utilizaUniversalTargetParameters.Input, Transformer sino que moldea su solicitud de forma que adopte las mismas expresiones.

Tipo de transformador	Usar cuando	Carga útil objetivo
RAW	El objetivo necesita los datos del evento publicados	Los datos publicados, sin cambios. El valor predeterminado.
WITH_METADATA	El objetivo necesita los datos y sus metadatos	Un sobre JSON con DataMetadata, y SystemMetadata
JSONATA	El objetivo necesita valores seleccionados o una forma nueva	El resultado de una expresión de JSonata por evento

Qué contiene $events

WITH_METADATAJSONATA, y cada expresión de parámetro de destino lee el mismo objeto de entrada, que una expresión de JSonata ve como. $events Tiene tres partes.

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

• Datason los datos publicados y mantienen su tipo de JSON: un objeto, una matriz, una cadena, un número, un booleano o un valor nulo. Porque PutRawEvents es el Data valor de la entrada, por lo que el identificador de pedido está en. $events.Data.orderId Porque PutEvents es el EventBridge sobre completo, con,version,id,detail-type,source,, accounttime, y regionresources, por lo tantodetail, el mismo identificador está en$events.Data.detail.orderId. Porque application/octet-stream es una cadena en Base64; consulteTransformación de datos binarios.

• Metadataes el mapa cadena a cadena con el que configuró el productor. PutRawEvents PutEventsno toma metadatos, por lo que para sus eventos el mapa está vacío.

• SystemMetadatacontiene los campos EventBridge asignados. Cada valor es una cadena. EventBridgeomite un campo opcional que no tiene ningún valor y un campo omitido se evalúa como undefined en JSonata; solo está siempre presente. aws:DeliveryType ContentTypemantiene el valor publicado, por lo que los datos de Avro y Protobuf EventBridge descodificados en JSON siguen mostrándose o aquí, y se muestra un evento. application/avro application/protobuf PutEvents application/eventbridge+json Para cada campo, consulte. SystemMetadata campos

Escriba un nombre de campo que contenga dos puntos, como en$events.SystemMetadata."aws:EventId".

Creación de una carga útil objetivo con JSonata

Transformer.TypeJSONATAEstablézcalo y póngalo en una expresión completa, encerrada entre {% y%}, dentro. JsonataConfiguration.Expression Para una PutRawEvents entrada cuyos datos son{"orderId": "12345", "priority": "high", "items": [...]}, el siguiente transformador solo proporciona los dos campos con nombre.

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

El objetivo recibe{"orderId": "12345", "priority": "high"}. EventBridge evalúa la expresión una vez para cada evento, antes del procesamiento por lotes. El tipo de resultado decide lo que recibe el objetivo.

Resultado de la expresión	Carga útil objetivo
Cadena	La cadena, sin comillas en JSON
Objeto o matriz	El objeto o la matriz JSON serializados. Un elemento null anidado en su interior permanece en JSON. null
Número o booleano	El valor JSON serializado
null o undefined	Un error de transformación; consulte Límites y fallos

Transformación de datos binarios

Cuando SystemMetadata.ContentType estáapplication/octet-stream, EventBridge almacena los bytes publicados sin analizarlos y los expone a una expresión como una cadena en Base64. $events.Data Los bytes de llegan como. hello $events.Data = "aGVsbG8=" EventBridge no analiza esa cadena como JSON incluso cuando los bytes decodificados son texto JSON, así que compruébalo ContentType antes de interpretarlo Data y $base64decode($events.Data) utilízalo solo cuando los bytes originales sean texto.

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

El tipo de transformador decide cómo los bytes llegan al objetivo. Solo RAW puede reenviar la matriz de bytes original.

Tipo de transformador	Lo que recibe el objetivo
RAW	Los bytes originales, para los objetivos de Kinesis, Firehose, API Gateway y Custom Event Bus. Texto en base64, para los objetivos de Amazon SQS y Amazon SNS. Una cadena JSON que contiene el texto de Base64 para Lambda, Step Functions, Custom Event Bus: Classic y los objetivos de destino de la API; una invocación por lotes de Lambda o Step Functions recibe una matriz de esas cadenas.
WITH_METADATA	El sobre en UTF-8 formato JSON, que contiene el texto en Base64 Data
JSONATA	La expresión resulta como UTF-8 texto o JSON; la expresión lee el texto en Base64

Un transformador no puede ContentType configurarse. Cuando el destino es otro bus de eventos personalizado, EventBridge copia el valor publicado, excepto que los datos de Avro y Protobuf se entregan como JSON y, por lo tanto, llegan como. application/json

Uso de JSonata en los parámetros de destino

Un parámetro de destino enInvokeConfiguration, por ejemploSqsParameters.MessageGroupId, contiene un valor literal o una expresión JSonata completa entre y. {% %} EventBridge no evalúa una expresión incrustada dentro de una cadena más larga. Las expresiones de los parámetros de destino leen el objeto de entrada original, no la carga útil que lo Transformer produjo. Los siguientes parámetros de Amazon SQS toman los valores FIFO de cada evento.

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

Lo que $events se mantenga depende del parámetro. Los parámetros que se EventBridge resuelven por evento ven un objeto de entrada. Los parámetros que resuelve una vez por invocación de destino muestran una matriz de objetos de entrada, uno por evento del lote, por lo que el primer evento es$events[0].Data.

Parameters	$eventsse mantiene
SqsParameters, SnsParameters, KinesisParameters, HttpParameters y EventBusV2Parameters.Metadata	Un objeto de entrada, por evento
LambdaParameters, StepFunctionsParameters, y EventBusV2Parameters.DeduplicationConfiguration	Una matriz de objetos de entrada, por invocación
UniversalTargetParameters.Input	Una matriz de objetos de entrada, por invocación

La expresión de un parámetro de destino debe devolver una cadena, a menos que el campo defina otro tipo; UniversalTargetParameters.Input puede devolver cualquier valor JSON que forme la solicitud de API. En un parámetro con valores de mapa, tanto las claves como los valores de cadena pueden ser expresiones:SqsParameters.MessageAttributes.name.StringValue,, SqsParameters.MessageSystemAttributes.name.StringValue SnsParameters.MessageAttributes.name.StringValueHttpParameters.QueryStringParameters.key, y. EventBusV2Parameters.Metadata.key El atributo BinaryValue de mensaje de Amazon SQS o Amazon SNS es un valor literal de Base64 que EventBridge nunca se evalúa, por lo que "BinaryValue": "AQID" llegan al destino en forma de bytes0x01 0x02 0x03; utilícelo como expresión. StringValue

Para un objetivo de API Gateway, cada HttpParameters.HeaderParameters clave debe ser literal; un objetivo de destino de API también permite expresiones en las claves de encabezado. EventBridge rechaza un encabezado que anule la firma de la solicitud:Authorization,Host, y cualquier encabezado que comience por. X-Amz Todas las $millis() llamadas $now() y con una resolución respecto a los parámetros de un suscriptor muestran la misma marca de tiempo.

Funciona más allá del JSonata estándar

Además de la biblioteca JSonata estándar, hay seis funciones disponibles.

Función	Resultado
$hash(input, algorithm)	Resumen hexadecimal en minúsculas. algorithmdistingue entre mayúsculas y minúsculas:MD5,,SHA-1, SHA-256 o SHA-384 SHA-512
$uuid()	Un UUID de la versión 4
$parse(jsonString)	El JSON analizado; se produce un error si la cadena no es un JSON válido
$partition(array, chunkSize)	La matriz se dividió en partes
$range(start, end, delta)	Un rango numérico; los tres argumentos son obligatorios y el resultado tiene un límite de 10 000 000 elementos
$random(seed)	Un número en [0, 1); la misma semilla da el mismo número

La $eval función no está disponible.

Límites y fallos

Una Transformer expresión y cada expresión de parámetro de destino pueden tener hasta 8.192 caracteres; una Input expresión de objetivo universal puede tener hasta 262.144. EventBridge comprueba la sintaxis al crear o actualizar el suscriptor y rechaza una expresión no válida con. InvalidInputException En el momento de la entrega, una expresión puede ejecutarse durante un segundo, usar una profundidad de pila de 100 y asignar 10 MiB.

Una expresión que arroja, supera esos límites, produce null o undefined no logra la entrega de ese evento. EventBridge vuelve a intentarlo por debajo del del suscriptor RetryPolicy y, a continuación, envía el evento al destino en caso de error, si hay uno configurado. La EventTransformationFailures métrica cuenta cada error, un EVENT_TRANSFORMATION_FAILURE registro contiene el error y el registro de puntos muertos es. errorCode INPUT_TRANSFORMATION_FAILURE Consulte Observabilidad del bus de eventos personalizado: métricas, registros y CloudTrail y Políticas de reintentos y colas de mensajes muertos.