As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Transformando eventos com JSonata Para alterar o que um alvo recebe, `Transformer` defina `CreateSubscriber` ou`UpdateSubscriber`. `Transformer.Type``RAW`, 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 usa`Transformer`; ele molda sua solicitação em`UniversalTargetParameters.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" } } ``` + `Data`sã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`, `time``region`, e`resources`, portanto`detail`, o mesmo identificador está em`$events.Data.detail.orderId`. Pois `application/octet-stream` é uma string Base64; veja[Transformação de dados binários](#eb-custom-bus-transform-binary). + `Metadata`é o mapa de string a string com o qual o produtor definiu. `PutRawEvents` `PutEvents`não usa metadados, portanto, para seus eventos, o mapa está vazio. + `SystemMetadata`manté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` `ContentType`manté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, consulte[SystemMetadata campos](eb-custom-bus-addressing.md#eb-custom-bus-addressing-system). Cite um nome de campo que contenha dois pontos, como em`$events.SystemMetadata."aws:EventId"`. ## Construindo uma carga útil de destino com JSOnata `Transformer.Type`Defina como `JSONATA` e coloque uma expressão completa, entre `{%` e `%}` dentro`JsonataConfiguration.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](#eb-custom-bus-transform-limits) | ## 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 configurado`ContentType`. 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 em`InvokeConfiguration`, como`SqsParameters.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 | `$events`segura | | --- | --- | | 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}}.StringValue``HttpParameters.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 bytes`0x01 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 seguida`RetryPolicy`, 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](eb-custom-bus-observability.md) e [Políticas de repetição e filas de cartas mortas](eb-custom-bus-retry.md).