Transformação de entrada do Amazon EventBridge - Amazon EventBridge

Transformação de entrada do Amazon EventBridge

Também é possível personalizar o texto de um evento antes que o EventBridge passe as informações para o destino de uma regra. Ao usar o transformador de entrada no console ou na API, são definidas variáveis que usam o caminho JSON para referenciar valores na origem original do evento. O evento transformado é enviado para um destino em vez do evento original. No entanto, os parâmetros do caminho dinâmico devem fazer referência ao evento original, não ao evento transformado. É possível definir até 100 variáveis, atribuindo a cada um valor da entrada. Depois, use essas variáveis no modelo de entrada como <variable-name>.

Para obter um tutorial sobre como usar o transformador de entrada, consulte Tutorial: usar transformadores de entrada para transformar eventos no EventBridge.

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 (*)

Variáveis predefinidas

Há variáveis predefinidas que podem ser usadas sem definir um caminho JSON. Estas variáveis são reservadas e não é possível criar variáveis com esses nomes:

  • aws.events.rule-arn: nome do recurso da Amazon (ARN) da regra do EventBridge.

  • aws.events.rule-name: o nome da regra do EventBridge.

  • aws.events.event.ingestion-time: a hora em que o evento foi recebido pelo EventBridge. Este é um carimbo de data/hora ISO 8601. Esta variável é gerada pelo EventBridge e não pode ser substituída.

  • aws.events.event: a carga útil do evento original como JSON (sem o campo detail). Só pode ser usado como um valor para um campo JSON, pois o conteúdo não tem escape.

  • aws.events.event.json: a carga útil completa do evento original como JSON (com o campo detail). Só pode ser usado como um valor para um campo JSON, pois o conteúdo não tem escape.

Exemplos de transformação de entrada

Veja a seguir um exemplo de evento do Amazon EC2.

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

Ao definir uma regra no console, selecione a opção Input Transformer (Transformador de entrada) em Configure input (Configurar entrada). Essa opção exibe duas caixas de texto: uma para o Input Path (Caminho de Entrada) e outra para o Input Template (Modelo de entrada).

Caminho de entrada

O Caminho de entrada é usado para definir variáveis. Use o caminho JSON para fazer referência a itens em seu evento e armazenar esses valores em variáveis. Por exemplo, é possível criar um caminho de entrada para fazer referência a valores no evento de exemplo inserindo o seguinte na primeira caixa de texto: Também é possível usar colchetes e índices para obter itens de matrizes.

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.

{ "timestamp" : "$.time", "instance" : "$.detail.instance-id", "state" : "$.detail.state", "resource" : "$.resources[0]" }

Isto definirá duas variáveis, <timestamp>, <instance>, <state> e <resource>. É possível pode fazer referência a essas variáveis ao criar o modelo de entrada.

nota

Os destinos do Amazon CloudWatch Logs e do SSM não comportam o uso de Input e InputPath em seus transformadores de entrada.

Modelo de entrada

O modelo de entrada é um modelo para as informações que você deseja passar para seu destino. É possível criar um modelo que transmita uma string ou JSON para o destino. Usando o evento anterior e o caminho de entrada, os exemplos de modelo de entrada a seguir transformarão o evento na saída de exemplo antes de fazer o roteamento dele para um destino.

Descrição Modelo Saída
String simples
"instance <instance> is in <state>"
"instance i-0123456789 is in RUNNING"

String com aspas de escape

"instance \"<instance>\" is in <state>"
"instance \"i-0123456789\" is in RUNNING"

Observe que esse é o comportamento no console do EventBridge. A AWS CLI faz o escape dos caracteres de barra e o resultado é "instance "i-0123456789" is in RUNNING".

JSON simples

{ "instance" : <instance>, "state": <state> }
{ "instance" : "i-0123456789", "state": "RUNNING" }

JSON com strings e variáveis

{ "instance" : <instance>, "state": "<state>", "instanceStatus": "instance \"<instance>\" is in <state>" }
{ "instance" : "i-0123456789", "state": "RUNNING", "instanceStatus": "instance \"i-0123456789\" is in RUNNING" }

JSON com uma mistura de variáveis e informações estáticas

{ "instance" : <instance>, "state": [ 9, <state>, true ], "Transformed" : "Yes" }
{ "instance" : "i-0123456789", "state": [ 9, "RUNNING", true ], "Transformed" : "Yes" }

Incluir variáveis reservadas no JSON

{ "instance" : <instance>, "state": <state>, "ruleArn" : <aws.events.rule-arn>, "ruleName" : <aws.events.rule-name>, "originalEvent" : <aws.events.event.json> }
{ "instance" : "i-0123456789", "state": "RUNNING", "ruleArn" : "arn:aws:events:us-east-2:123456789012:rule/example", "ruleName" : "example", "originalEvent" : { ... // commented for brevity } }

Incluir variáveis reservadas em uma string

"<aws.events.rule-name> triggered"
"example triggered"

Grupo do Amazon CloudWatch Logs

{ "timestamp" : <timestamp>, "message": "instance \"<instance>\" is in <state>" }
{ "timestamp" : 2015-11-11T21:29:54Z, "message": "instance "i-0123456789" is in RUNNING }

Como transformar a entrada usando a API do EventBridge

Para obter informações e exemplos sobre como usar transformações de entrada com a API do EventBridge, consulte Usar transformador de entrada para extrair dados de um evento e inserir esses dados no destino.

Como transformar a entrada usando o AWS CloudFormation

Para obter informações sobre como usar o AWS CloudFormation para transformar a entrada, consulte AWS::Events::Rule InputTransformer.

Problemas comuns com a transformação de entrada

Estes são alguns problemas comuns ao transformar a entrada no 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.events.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, para uma variável <detail> apontada $.detail, "Detalhe é<detail>" resultaria na remoção de 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, {"detail": <detail>}.

  • As aspas não são necessárias para variáveis que representam cadeias de caracteres. Eles são permitidos, mas o EventBridge 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 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:

    { "ruleArn" : <aws.events.rule-arn>, "ruleName" : <aws.events.rule-name>, "originalEvent" : <aws.events.event.json> }

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

    { "ruleArn" : "arn:aws:events:us-east-2:123456789012:rule/example", "ruleName" : "example", "originalEvent" : { ... // commented for brevity } }
  • Para saída de texto (não JSON) como strings de várias linhas, coloque cada linha separada em seu modelo de entrada entre aspas duplas.

    Por exemplo, se estiver fazendo a correspondência de eventos de descoberta do Amazon Inspector com o seguinte padrão de eventos:

    { "detail": { "severity": ["HIGH"], "status": ["ACTIVE"] }, "detail-type": ["Inspector2 Finding"], "source": ["inspector2"] }

    E usando o seguinte caminho de entrada:

    { "account": "$.detail.awsAccountId", "ami": "$.detail.resources[0].details.awsEc2Instance.imageId", "arn": "$.detail.findingArn", "description": "$.detail.description", "instance": "$.detail.resources[0].id", "platform": "$.detail.resources[0].details.awsEc2Instance.platform", "region": "$.detail.resources[0].region", "severity": "$.detail.severity", "time": "$.time", "title": "$.detail.title", "type": "$.detail.type" }

    Você pode usar o modelo de entrada abaixo para gerar uma saída de string de várias linhas:

    "<severity> severity finding <title>" "Description: <description>" "ARN: \"<arn>\"" "Type: <type>" "AWS Account: <account>" "Region: <region>" "EC2 Instance: <instance>" "Platform: <platform>" "AMI: <ami>"