Transformação de entrada do Amazon EventBridge Pipes - Amazon EventBridge
Variáveis reservadasExemplo de transformação de entradaAnálise implícita de dados do corpoProblemas comuns com a transformação de entrada

Transformação de entrada do Amazon EventBridge Pipes

O Amazon EventBridge Pipes é compatível com transformadores de entrada opcionais ao transmitir dados para o enriquecimento e o destino. É possível usar transformadores de entrada para remodelar a carga útil de entrada de eventos JSON para atender às necessidades do serviço de enriquecimento ou de destino. Para o Amazon API Gateway e destinos de API, é assim que o evento de entrada é moldado para o modelo RESTful da sua API. Os transformadores de entrada são modelados como um parâmetro InputTemplate. Eles podem ser texto livre, um caminho JSON para a carga do evento ou um objeto JSON que inclui caminhos JSON embutidos para a carga do evento. Para enriquecimento, a carga útil do evento vem da origem. Para destinos, a carga útil do evento é o que é retornado do enriquecimento, se estiver configurado no pipe. Além dos dados específicos do serviço na carga útil do evento, é possível usar variáveis reservadas InputTemplate para referenciar os dados do seu pipe.

Para acessar itens em uma matriz, use a notação de colchetes.

nota

O EventBridge não suporta toda a sintaxe do JSON Path e a avalia em runtime. A sintaxe compatível inclui:

  • notação de pontos (por exemplo, $.detail)

  • traços

  • sublinhados

  • caracteres alfanuméricos

  • índices de matriz

  • curingas (*)

Os seguintes são parâmetros InputTemplate de amostra que fazem referência a uma carga útil de eventos do Amazon SQS:

String estática

InputTemplate: "Hello, sender"

Caminho JSON

InputTemplate: <$.attributes.SenderId>

String 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>
}

Use a notação de colchetes para usar itens em uma matriz:

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

O EventBridge substitui os transformadores de entrada em runtime para garantir uma saída JSON válida. Por isso, coloque aspas nas variáveis que se referem aos parâmetros de caminho JSON, mas não coloque aspas nas variáveis que se referem a objetos ou matrizes JSON.

Variáveis reservadas

Os modelos de entrada podem usar as seguintes variáveis reservadas:

  • <aws.pipes.pipe-arn>: o nome do recurso da Amazon (ARN) do pipe.

  • <aws.pipes.pipe-name>: o nome do pipe.

  • <aws.pipes.source-arn>: o ARN de origem de evento do pipe.

  • <aws.pipes.enrichment-arn>: o ARN de enriquecimento do pipe.

  • <aws.pipes.target-arn>: o ARN de destino do pipe.

  • <aws.pipes.event.ingestion-time>: o momento em que o evento foi recebido pelo transformador de entrada. Este é um carimbo de data/hora ISO 8601. Este tempo é diferente para o transformador de entrada de enriquecimento e o transformador de entrada de destino, dependendo de quando o enriquecimento concluiu o processamento do evento.

  • <aws.pipes.event>: o evento conforme recebido pelo transformador de entrada.

    Para um transformador de entrada de enriquecimento, esse é o evento da origem. Ele contém a carga original da origem, além de metadados específicos do serviço adicionais. Para obter exemplos específicos deste serviço, consulte Origens do Amazon EventBridge Pipes.

    Para um transformador de entrada de destino, esse é o evento retornado pelo enriquecimento, se um estiver configurado, sem metadados adicionais. Dessa forma, uma carga útil retornada por enriquecimento pode não ser JSON. Se nenhum enriquecimento estiver configurado no pipe, esse é o evento da origem com metadados.

  • <aws.pipes.event.json>: o mesmo que aws.pipes.event, mas a variável só tem um valor se a carga original, da origem ou retornada pelo enriquecimento, for JSON. Se o pipe tiver um campo codificado, como o campo body do Amazon SQS ou os data do Kinesis, esses campos serão decodificados e transformados em JSON válido. Como não passou por um escape, a variável só pode ser usada como um valor para um campo JSON. Para ter mais informações, consulte Análise implícita de dados do corpo.

Exemplo de transformação de entrada

Veja a seguir um exemplo de evento do Amazon EC2 que podemos usar como nosso exemplo de evento.


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

Vamos usar o seguinte JSON como nosso Transformador.

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

A seguir estárá a Saída resultante:

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

Análise implícita de dados do corpo

Os campos a seguir na carga de entrada podem ser escapados por JSON, como o objeto body do Amazon SQS, ou codificados em base64, como o objeto data do Kinesis. Tanto para filtragem quanto para transformação de entrada, o EventBridge transforma esses campos em JSON válido para que os subvalores possam ser referenciados diretamente. Por exemplo, <$.data.someKey> para o Kinesis.

Para que o destino receba a carga original sem nenhum metadado adicional, use um transformador de entrada com esses dados do corpo, específicos da origem. Por exemplo, <$.body> para o Amazon SQS ou <$.data> para o Kinesis. Se a carga original for uma string JSON válida (por exemplo, {"key": "value"}), o uso do transformador de entrada com dados específicos do corpo da origem resultará na remoção das aspas dentro da carga da origem original. Por exemplo, {"key": "value"} se tornará "{key: value}" quando for entregue ao destino. Se seu destino exigir cargas JSON válidas (por exemplo, EventBridge Lambda ou Step Functions), isso causará falha na entrega. Para que o destino receba os dados de origem originais sem gerar JSON inválido, envolva o transformador de entrada de dados do corpo de origem em JSON. Por exemplo, {"data": <$.data>}.

A análise implícita do corpo também pode ser usada para preencher dinamicamente os valores da maioria dos parâmetros de enriquecimento ou destino do pipe. Para ter mais informações, consulte Parâmetros dinâmicos do caminho.

nota

Se a carga original for um JSON válido, este campo conterá o JSON sem escape e sem codificação em base64. No entanto, se a carga útil não for um JSON válido, o EventBridge codifica em base64 para os campos listados abaixo, com exceção do Amazon SQS.

  • MQ ativo: data

  • Kinesis: data

  • Amazon MSK: key e value

  • Rabbit MQ: data

  • Apache Kafka autogerenciado: key e value

  • Amazon SQS: body

Problemas comuns com a transformação de entrada

Estes são alguns problemas comuns ao transformar a entrada nos pipes do EventBridge:

  • Para strings, as aspas são necessárias.

  • Não há validação ao criar o caminho JSON para o modelo.

  • Se especificar uma variável para corresponder a um caminho JSON que não existe no evento, essa variável não será criada e não aparecerá na saída.

  • Propriedades JSON, como aws.pipes.event.json, só podem ser usadas como o valor de um campo JSON, não embutidas em outras strings.

  • O EventBridge não faz o escape de valores extraídos pelo Caminho de entrada, ao preencher o Modelo de entrada para um destino.

  • Se um caminho JSON fizer referência a um objeto ou matriz JSON, mas a variável for referenciada em uma string, o EventBridge removerá todas as aspas internas para garantir uma string válida. Por exemplo, "Body is <$.body>" resultaria na remoção das aspas do objeto pelo EventBridge.

    Portanto, se quiser gerar um objeto JSON com base em uma única variável de caminho JSON, deverá colocá-lo como uma chave. Neste exemplo, {"body": <$.body>}.

  • As aspas não são necessárias para variáveis que representam cadeias de caracteres. Eles são permitidos, mas o EventBridge Pipes adiciona automaticamente aspas aos valores das variáveis de string durante a transformação, para garantir que a saída da transformação seja um JSON válido. O EventBridge Pipes não adiciona aspas às variáveis que representam objetos ou matrizes JSON. Não adicione aspas para variáveis que representem objetos ou matrizes JSON.

    Por exemplo, o seguinte modelo de entrada inclui variáveis que representam cadeias de caracteres e objetos JSON:

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

    Resultando em JSON válido com cotação adequada:

    {
  "pipeArn" : "arn:aws:events:us-east-2:123456789012:pipe/example",
  "pipeName" : "example",
  "originalEvent" : {
    ... // commented for brevity
  }
}

  • Para enriquecimentos ou destinos do Lambda ou Step Functions, os lotes são entregues ao destino como matrizes JSON, mesmo que o tamanho do lote seja 1. No entanto, os transformadores de entrada ainda serão aplicados a registros individuais na matriz JSON, não à matriz como um todo. Para ter mais informações, consulte Processamento de lotes e simultaneidade do Amazon EventBridge Pipes.