Transformando eventos com JSonata

Para alterar o que um alvo recebe, Transformer defina CreateSubscriber ouUpdateSubscriber. Transformer.TypeRAW, o padrão, entrega somente os dados publicados; WITH_METADATA entrega os dados com seus metadados; e JSONATA entrega o resultado de uma expressão, por exemplo{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}. Um assinante cujo alvo é um barramento de eventos personalizado - suporte apenas RAW para o Classic. Um alvo universal não usaTransformer; ele molda sua solicitação emUniversalTargetParameters.Input, que usa as mesmas expressões.

Tipo de transformador	Use quando	Carga útil alvo
RAW	O alvo precisa dos dados publicados do evento	Os dados publicados, inalterados. Corresponde ao padrão.
WITH_METADATA	O alvo precisa dos dados e de seus metadados	Um envelope JSON comData, e Metadata SystemMetadata
JSONATA	O alvo precisa de valores selecionados ou de uma nova forma	O resultado de uma expressão JSOnata por evento

O que $events contém

WITH_METADATA,JSONATA, e cada expressão de parâmetro de destino lê o mesmo objeto de entrada, que uma expressão JSOnata vê como. $events Tem três 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"
    }
}

• Datasão os dados publicados e mantêm seu tipo JSON: um objeto, matriz, string, número, booleano ou nulo. Pois PutRawEvents é o Data valor da entrada, então um identificador de pedido está em$events.Data.orderId. Pois PutEvents é o EventBridge envelope inteiro, com,version,id,detail-type,source,account, timeregion, eresources, portantodetail, o mesmo identificador está em$events.Data.detail.orderId. Pois application/octet-stream é uma string Base64; vejaTransformação de dados binários.

• Metadataé o mapa de string a string com o qual o produtor definiu. PutRawEvents PutEventsnão usa metadados, portanto, para seus eventos, o mapa está vazio.

• SystemMetadatamantém os campos EventBridge atribuídos. Cada valor é uma string. EventBridgeomite um campo opcional que não tem valor e um campo omitido é avaliado como undefined em JSonata; somente está sempre presente. aws:DeliveryType ContentTypemantém o valor publicado, então os dados do Avro e do Protobuf EventBridge decodificados para JSON ainda são exibidos application/avro ou application/protobuf aqui, e um evento é exibido. PutEvents application/eventbridge+json Para cada campo, consulteSystemMetadata campos.

Cite um nome de campo que contenha dois pontos, como em$events.SystemMetadata."aws:EventId".

Construindo uma carga útil de destino com JSOnata

Transformer.TypeDefina como JSONATA e coloque uma expressão completa, entre {% e %} dentroJsonataConfiguration.Expression. Para uma PutRawEvents entrada cujos dados são{"orderId": "12345", "priority": "high", "items": [...]}, o transformador a seguir fornece somente os dois campos nomeados.

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

O alvo recebe{"orderId": "12345", "priority": "high"}. EventBridge avalia a expressão uma vez para cada evento, antes do agrupamento. O tipo do resultado decide o que o alvo recebe.

Resultado da expressão	Carga útil alvo
String	A string, sem aspas JSON
Objeto ou matriz	O objeto ou matriz JSON serializado. Um null aninhado dentro dele permanece null JSON.
Número ou booleano	O valor JSON serializado
null ou undefined	Uma falha de transformação; veja Limites e falhas

Transformação de dados binários

Quando SystemMetadata.ContentType éapplication/octet-stream, EventBridge armazena os bytes publicados sem analisá-los e os expõe a uma expressão como uma string Base64 em. $events.Data Os bytes de hello chegam como$events.Data = "aGVsbG8=". EventBridge não analisa essa string como JSON, mesmo quando os bytes decodificados são texto JSON, portanto, verifique ContentType antes de interpretar Data e use $base64decode($events.Data) somente quando os bytes originais forem texto.

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

O tipo de transformador decide como os bytes atingem o alvo. Só RAW pode encaminhar a matriz de bytes original.

Tipo de transformador	O que o alvo recebe
RAW	Os bytes originais, para destinos do Kinesis, Firehose, API Gateway e Custom Event Bus. Texto Base64, para destinos do Amazon SQS e do Amazon SNS. Uma string JSON contendo o texto Base64, para destinos Lambda, Step Functions, Custom Event Bus - Classic e API; uma invocação de Lambda ou Step Functions em lote recebe uma matriz dessas strings.
WITH_METADATA	O envelope como UTF-8 JSON, Data segurando o texto Base64
JSONATA	O resultado da expressão como UTF-8 texto ou JSON; a expressão lê o texto Base64

Um transformador não pode ser configuradoContentType. Quando o destino é outro barramento de eventos personalizado, EventBridge copia o valor publicado, exceto que os dados Avro e Protobuf são entregues como JSON e, portanto, chegam como. application/json

Usando JSoData nos parâmetros de destino

Um parâmetro de destino emInvokeConfiguration, comoSqsParameters.MessageGroupId, contém um valor literal ou uma expressão JSonata completa entre e. {% %} EventBridge não avalia uma expressão incorporada em uma string mais longa. As expressões de parâmetros de destino lêem o objeto de entrada original, não a carga útil Transformer produzida. Os seguintes parâmetros do Amazon SQS usam os 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\" %}"
        }
    }
}

O que $events vale depende do parâmetro. Os parâmetros que são EventBridge resolvidos por evento veem um objeto de entrada. Os parâmetros que ele resolve uma vez por invocação de destino veem uma matriz de objetos de entrada, um por evento no lote, então o primeiro evento é. $events[0].Data

Parâmetros	$eventssegura
SqsParameters, SnsParameters, KinesisParameters, HttpParameters, e EventBusV2Parameters.Metadata	Um objeto de entrada, por evento
LambdaParameters, StepFunctionsParameters, e EventBusV2Parameters.DeduplicationConfiguration	Uma matriz de objetos de entrada, por invocação
UniversalTargetParameters.Input	Uma matriz de objetos de entrada, por invocação

Uma expressão de parâmetro de destino deve retornar uma string, a menos que o campo defina outro tipo; UniversalTargetParameters.Input pode retornar qualquer valor JSON que forme a solicitação da API. Em um parâmetro com valor de mapa, tanto as chaves quanto os valores da string podem ser expressões:SqsParameters.MessageAttributes.name.StringValue,SqsParameters.MessageSystemAttributes.name.StringValue, SnsParameters.MessageAttributes.name.StringValueHttpParameters.QueryStringParameters.key, e. EventBusV2Parameters.Metadata.key O atributo BinaryValue de mensagem de um Amazon SQS ou Amazon SNS é um valor literal de Base64 que EventBridge nunca é avaliado, portanto, "BinaryValue": "AQID" atinge o destino como bytes0x01 0x02 0x03; use para uma expressão. StringValue

Para uma meta do API Gateway, cada HttpParameters.HeaderParameters chave deve ser literal; uma meta de destino da API também permite expressões em chaves de cabeçalho. EventBridge rejeita um cabeçalho que substituiria a assinatura da solicitação:Authorization,Host, e qualquer cabeçalho que comece com. X-Amz Cada $millis() chamada $now() e dentro de uma resolução dos parâmetros de um assinante retorna o mesmo timestamp.

Funções além do JSONATA padrão

Além da biblioteca JSonata padrão, seis funções estão disponíveis.

Função	Resultado
$hash(input, algorithm)	Resumo hexadecimal em minúsculas. algorithmdiferencia maiúsculas de minúsculas:MD5,SHA-1,SHA-256, ou SHA-384 SHA-512
$uuid()	Um UUID versão 4
$parse(jsonString)	O JSON analisado; um erro se a string não for um JSON válido
$partition(array, chunkSize)	A matriz dividida em pedaços
$range(start, end, delta)	Um intervalo numérico; todos os três argumentos são obrigatórios e o resultado é limitado a 10.000.000 de elementos
$random(seed)	Um número em [0, 1); a mesma semente dá o mesmo número

A $eval função não está disponível.

Limites e falhas

Uma Transformer expressão e cada expressão de parâmetro de destino podem ter até 8.192 caracteres; a Input expressão de um alvo universal pode ter até 262.144. EventBridge verifica a sintaxe ao criar ou atualizar o assinante e rejeita uma expressão inválida com. InvalidInputException Na entrega, uma expressão pode ser executada por um segundo, usar uma profundidade de pilha de 100 e alocar 10 MiB.

Uma expressão que lança, excede esses limites, produz null ou undefined falha na entrega desse evento. EventBridge tenta novamente sob o comando do assinante e, em seguidaRetryPolicy, envia o evento para o destino em caso de falha, se um estiver configurado. A EventTransformationFailures métrica conta cada falha, um registro de EVENT_TRANSFORMATION_FAILURE log carrega o erro e o registro de letra morta é. errorCode INPUT_TRANSFORMATION_FAILURE Consulte Observabilidade do barramento de eventos personalizado: métricas, registros e CloudTrail e Políticas de repetição e filas de cartas mortas.