Transformação EventBridge de insumos da Amazon - Amazon EventBridge
Variáveis predefinidasExemplos de transformação de entradaTransformando a entrada usando a API EventBridgeTransformando a entrada usando AWS CloudFormationProblemas comuns com a transformação de entrada

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á.

Transformação EventBridge de insumos da Amazon

Você pode personalizar o texto de um evento antes de EventBridge passar 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 o transformador de entrada para personalizar o que o EventBridge aprova para o evento de destino.

nota

EventBridge não suporta toda a sintaxe do JSON Path e a avalia em tempo de execução. A sintaxe compatível inclui:

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

  • traços

  • sublinhados

  • caracteres alfanuméricos

  • índices de matriz

  • curingas (*)

Neste tópico:

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— O Amazon Resource Name (ARN) da EventBridge regra.

  • aws.events.rule-name— O nome da EventBridge regra.

  • aws.events.event.ingestion-time— A hora em que o evento foi recebido por EventBridge. Este é um carimbo de data/hora ISO 8601. Essa variável é gerada por 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).

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

EventBridge substitui os transformadores de entrada em tempo de execução 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.

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 EventBridge console. 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 de CloudWatch registros da Amazon

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

Transformando a entrada usando a API EventBridge

Para obter informações sobre como usar a EventBridge API para transformar a entrada, consulte Usar o Input Transformer para extrair dados de um evento e inserir esses dados no destino.

Transformando a entrada usando AWS CloudFormation

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

Problemas comuns com a transformação de entrada

Esses são alguns problemas comuns ao transformar a entrada em: 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.

  • EventBridge não escapa dos valores extraídos pelo caminho de entrada, ao preencher o modelo de entrada de um destino.

  • Se um caminho JSON fizer referência a um objeto ou matriz JSON, mas a variável for referenciada em uma string, 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 EventBridge remoção de aspas do objeto.

    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. Elas são permitidas, mas adicionam EventBridge 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. 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 cadeias de caracteres de várias linhas, coloque cada linha separada em seu modelo de entrada entre aspas duplas.

    Por exemplo, se você estivesse comparando Amazon Inspector Finding events com o seguinte padrão de evento:

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