

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 eventos con JSonata

Para cambiar lo que recibe un objetivo, `Transformer` defina `CreateSubscriber` o`UpdateSubscriber`. `Transformer.Type``RAW`, 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 admite`RAW`. Un objetivo universal no utiliza`UniversalTargetParameters.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 ``
<a name="eb-custom-bus-transform-shape"></a>

`WITH_METADATA``JSONATA`, 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.

```json
{
    "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`son 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`,, `account``time`, y `region``resources`, por lo tanto`detail`, el mismo identificador está en`$events.Data.detail.orderId`. Porque `application/octet-stream` es una cadena en Base64; consulte[Transformación de datos binarios](#eb-custom-bus-transform-binary).
+ `Metadata`es el mapa cadena a cadena con el que configuró el productor. `PutRawEvents` `PutEvents`no toma metadatos, por lo que para sus eventos el mapa está vacío.
+ `SystemMetadata`contiene 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` `ContentType`mantiene 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](eb-custom-bus-addressing.md#eb-custom-bus-addressing-system)

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

## Creación de una carga útil objetivo con JSonata
<a name="eb-custom-bus-transform-jsonata"></a>

`Transformer.Type``JSONATA`Establé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.

```json
{
    "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](#eb-custom-bus-transform-limits) | 

## Transformación de datos binarios
<a name="eb-custom-bus-transform-binary"></a>

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
<a name="eb-custom-bus-transform-parameters"></a>

Un parámetro de destino en`InvokeConfiguration`, por ejemplo`SqsParameters.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.

```json
{
    "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 | `$events`se 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}}.StringValue``HttpParameters.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 bytes`0x01 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
<a name="eb-custom-bus-transform-functions"></a>

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
<a name="eb-custom-bus-transform-limits"></a>

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](eb-custom-bus-observability.md) y [Políticas de reintentos y colas de mensajes fallidos](eb-custom-bus-retry.md).