Fundamentos de filtragem de eventos Tratamento de registros que não atendem aos critérios de filtragem Sintaxe das regras de filtros Anexar critérios de filtro a um mapeamento de fonte de eventos (console)Anexar critérios de filtros a um mapeamento de fonte de eventos (AWS CLI)Anexar critérios de filtros a um mapeamento de fonte de eventos (AWS SAM)Uso de filtros com diferentes Serviços da AWS Filtragem com DynamoDB Filtragem com o Kinesis Filtragem com o Amazon MQ Filtragem com o Amazon MSK e o Apache Kafka autogerenciado Filtragem com o Amazon SQS

Filtragem de eventos do Lambda

É possível usar filtragem de eventos para controlar quais registros de um stream ou fila que o Lambda enviará para a função. Por exemplo, é possível adicionar um filtro para que sua função processe somente mensagens do Amazon SQS contendo determinados parâmetros de dados. A filtragem de eventos funciona com mapeamentos da origem do evento. É possível adicionar filtros aos mapeamentos da origem do evento para os seguintes serviços da AWS:

Amazon DynamoDB
Amazon Kinesis Data Streams
Amazon MQ
Amazon Managed Streaming for Apache Kafka (Amazon MSK)
Apache Kafka autogerenciado
Amazon Simple Queue Service (Amazon SQS)

O Lambda não oferece suporte à filtragem de eventos para o Amazon DocumentDB.

Por padrão, é possível definir até cinco filtros diferentes para um único mapeamento da origem do evento. Seus filtros estão logicamente relacionados por OR. Se um registro da sua origem de eventos satisfizer um ou mais dos seus filtros, o Lambda incluirá o registro no próximo evento enviado à sua função. Se nenhum dos seus filtros for satisfeito, o Lambda descartará o registro.

nota

Se você precisar definir mais de cinco filtros para uma origem de evento, poderá solicitar um aumento de cota de até 10 filtros para cada origem de evento. Se tentar adicionar mais filtros do que a cota atual permite, o Lambda retornará um erro quando você tentar criar a origem de eventos.

Tópicos

Fundamentos de filtragem de eventos
Tratamento de registros que não atendem aos critérios de filtragem
Sintaxe das regras de filtros
Anexar critérios de filtro a um mapeamento de fonte de eventos (console)
Anexar critérios de filtros a um mapeamento de fonte de eventos (AWS CLI)
Anexar critérios de filtros a um mapeamento de fonte de eventos (AWS SAM)
Uso de filtros com diferentes Serviços da AWS
Filtragem com DynamoDB
Filtragem com o Kinesis
Filtragem com o Amazon MQ
Filtragem com o Amazon MSK e o Apache Kafka autogerenciado
Filtragem com o Amazon SQS

Fundamentos de filtragem de eventos

Um objeto de critérios de filtro (FilterCriteria) é uma estrutura que consiste em uma lista de filtros (Filters). Cada filtro é uma estrutura que define um padrão de filtragem de eventos (Pattern). Um padrão é uma representação em string de uma regra de filtro JSON. A estrutura de um objeto FilterCriteria é descrita a seguir.


{
   "Filters": [
        {
            "Pattern": "{ \"Metadata1\": [ rule1 ], \"data\": { \"Data1\": [ rule2 ] }}"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "Metadata1": [ rule1 ],
    "data": {
        "Data1": [ rule2 ]
    }
}

Seu padrão de filtro pode incluir propriedades de metadados, propriedades de dados ou ambas. Os parâmetros de metadados disponíveis e o formato dos parâmetros de dados variam de acordo com o AWS service (Serviço da AWS) que está atuando como origem do evento. Por exemplo, suponha que seu mapeamento da origem do evento receba o registro a seguir de uma fila do Amazon SQS:


{
    "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
    "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
    "body": "{\n "City": "Seattle",\n "State": "WA",\n "Temperature": "46"\n}",
    "attributes": {
        "ApproximateReceiveCount": "1",
        "SentTimestamp": "1545082649183",
        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
        "ApproximateFirstReceiveTimestamp": "1545082649185"
    },
    "messageAttributes": {},
    "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
    "eventSource": "aws:sqs",
    "eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
    "awsRegion": "us-east-2"
}

As propriedades dos metadados são os campos que contêm informações sobre o evento que criou o registro. No exemplo de registro do Amazon SQS, as propriedades dos metadados incluem campos como messageID, eventSourceArn, e awsRegion.
As propriedades dos dados são os campos do registro que contêm os dados do seu stream ou fila. No exemplo de evento do Amazon SQS, a chave para o campo de dados é body, e as propriedades dos dados são os campos City, State e Temperature.

Diferentes tipos de origens de eventos usam diferentes valores-chave para seus campos de dados. Para filtrar as propriedades de dados, certifique-se de usar a chave correta no padrão do seu filtro. Para obter uma lista de chaves de filtragem de dados e ver exemplos de padrões de filtro para cada um dos AWS service (Serviço da AWS) com suporte, consulteUso de filtros com diferentes Serviços da AWS.

A filtragem de eventos pode lidar com a filtragem JSON de vários níveis. Por exemplo, considere o fragmento a seguir de um registro de um stream do DynamoDB:


"dynamodb": {
    "Keys": {
        "ID": {
            "S": "ABCD"
        }
        "Number": {
            "N": "1234"
    },
    ...
}

Suponha que você queira processar somente os registros em que o valor da chave de classificação Number seja 4567. Nesse caso, seu objeto FilterCriteria deve ser semelhante a:


{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\": { \"Keys\": { \"Number\": { \"N\": [ "4567" ] } } } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "dynamodb": {
        "Keys": {
            "Number": {
                "N": [ "4567" ]
                }
            }
        }
}

Tratamento de registros que não atendem aos critérios de filtragem

A forma como os registros que não atendem ao seu filtro são tratados depende da origem do evento.

Para o Amazon SQS, se a mensagem não atender aos critérios de filtro, o Lambda removerá automaticamente a mensagem da fila. Não é necessário excluir manualmente essas mensagens no Amazon SQS.
Para o Kinesis e no DynamoDB, quando seus critérios de filtro processam um registro, o iterador de streams avança além desse registro. Se o registro não atender aos critérios de filtro, não será necessário excluir manualmente o registro da fonte de eventos. Após o período de retenção, o Kinesis e o DynamoDB excluem esses registros antigos automaticamente. Se quiser que os registros sejam excluídos antes, consulte Alterar o período de retenção de dados.
Para mensagens do Amazon MSK, do Apache Kafka autogerenciadas e do Amazon MQ, o Lambda descarta as mensagens que não correspondem a todos os campos incluídos no filtro. Para o Apache Kafka autogerenciado, o Lambda confirma desvios para mensagens correspondentes ou não correspondentes depois de invocar a função com êxito. Para o Amazon MQ, o Lambda reconhece as mensagens coincidentes após invocar a função com êxito e reconhece as mensagens não coincidentes ao filtrá-las.

Sintaxe das regras de filtros

Para as regras de filtros, o Lambda é compatível com as regras do Amazon EventBridge e usa a mesma sintaxe que o EventBridge. Para obter mais informações, consulte Padrões de eventos do Amazon EventBridge no Guia do usuário do Amazon EventBridge.

A seguir, há um resumo de todas as operações de comparação disponíveis para a filtragem de eventos do Lambda.

Operador de comparação	Exemplo	Sintaxe da regra
Nulo	UserID é null	"UserID": [ null ]
Vazio	LastName está vazio	"LastName": [""]
Igual	Name é “Alice”	"Name": [ "Alice" ]
É igual a (ignorar maiúsculas e minúsculas)	Name é “Alice”	"Name": [ { "equals-ignore-case": "alice" } ]
E	Location é “Nova York” e o Day é “Monday” (Segunda-feira)	"Location": [ "New York" ], "Day": ["Monday"]
Ou	PaymentType é “Credit” (Crédito) ou “Debit” (Débito)	"PaymentType": [ "Credit", "Debit"]
Ou (vários campos)	Location é “New York” ou Day é “Monday”.	"$or": [ { "Location": [ "New York" ] }, { "Day": [ "Monday" ] } ]
Não	Weather é qualquer valor, exceto “Raining” (Chovendo)	"Weather": [ { "anything-but": [ "Raining" ] } ]
Numeric (equals) (Numérico, igual)	Price é 100	"Price": [ { "numeric": [ "=", 100 ] } ]
Numeric (range) (Numérico, intervalo)	Price é superior a 10 e menor que ou igual a 20	"Price": [ { "numeric": [ ">", 10, "<=", 20 ] } ]
Existe	ProductName existe	"ProductName": [ { "exists": true } ]
Não existe	ProductName não existe	"ProductName": [ { "exists": false } ]
Começa com	Region é nos EUA	"Region": [ {"prefix": "us-" } ]
Termina com	FileName termina com uma extensão .png.	"FileName": [ { "suffix": ".png" } ]

nota

Como o EventBridge, para strings, o Lambda usa correspondência exata caractere por caractere sem case-folding nem qualquer normalização de strings. Para números, o Lambda também usa representação de string. Por exemplo, 300, 300.0 e 3.0e2 não são considerados iguais.

Observe que o operador Exists só funciona em nós terminais em seu JSON de origem de eventos. Não corresponde aos nós intermediários. Por exemplo, com o seguinte JSON, o padrão de filtro { "person": { "address": [ { "exists": true } ] } }" não encontraria uma correspondência porque "address" é um nó intermediário.


{
  "person": {
    "name": "John Doe",
    "age": 30,
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "country": "USA"
    }
  }
}

Anexar critérios de filtro a um mapeamento de fonte de eventos (console)

Siga estas etapas para criar um novo mapeamento de fonte de eventos com critérios de filtro usando o console do Lambda.

Para criar um novo mapeamento de fonte de eventos com critérios de filtro (console)

Abra a página Funções do console do Lambda.
Escolha o nome de uma função para a qual criar um mapeamento de fonte de evento.
Em Visão geral da função, escolha Adicionar gatilho.
Em Trigger configuration (Configuração do acionador), escolha um tipo de acionador com suporte a filtragem de eventos. Para obter uma lista dos serviços com suporte, consulte a lista no início desta página.
Expanda Additional settings (Configurações adicionais).
Em Filter criteria, (Critérios de filtros), escolha Add, (Adicionar) e insira os filtros. Por exemplo, é possível inserir o seguinte.
```
{ "Metadata" : [ 1, 2 ] }
```
Isso instrui o Lambda a processar somente os registros em que o campo Metadata é igual a 1 ou 2. É possível continuar selecionando Adicionar para adicionar mais filtros até o número máximo permitido.
Ao concluir a inclusão de filtros, escolha Salvar.

Ao inserir critérios de filtros usando o console, insira somente o padrão do filtro, pois não é necessário fornecer a chave Pattern ou as aspas escape. Na etapa 6 das instruções anteriores, { "Metadata" : [ 1, 2 ] } corresponde aos FilterCriteria a seguir.


{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

Após criar o mapeamento da fonte de eventos no console, você pode ver os FilterCriteria formatados nos detalhes do acionador. Para obter mais exemplos de criação de filtros de eventos usando o console, consulte Uso de filtros com diferentes Serviços da AWS.

Anexar critérios de filtros a um mapeamento de fonte de eventos (AWS CLI)

Suponha que você queira que um mapeamento de fonte de eventos tenha os seguintes FilterCriteria:


{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

Para criar um novo mapeamento da origem do evento com esses critérios de filtro usando a AWS Command Line Interface (AWS CLI), execute o comando a seguir.


aws lambda create-event-source-mapping \
    --function-name my-function \
    --event-source-arn arn:aws:sqs:us-east-2:123456789012:my-queue \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

Esse comando create-event-source-mapping cria um novo mapeamento da origem do evento do Amazon SQS para a função my-function com os FilterCriteria especificados.

Para adicionar esses critérios de filtro a um mapeamento da origem do evento existente, execute o comando a seguir.


aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria '{"Filters": [{"Pattern": "{ \"Metadata\" : [ 1, 2 ]}"}]}'

Para atualizar um mapeamento de fonte de eventos, você precisa do UUID. É possível obter o UUID com uma chamada a list-event-source-mappings. O Lambda também retorna o UUID na resposta da CLI de create-event-source-mapping.

Para remover critérios de filtro de uma origem de eventos, execute o comando UpdateEventSourceMapping a seguir com um objeto FilterCriteria vazio.


aws lambda update-event-source-mapping \
    --uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
    --filter-criteria "{}"

Para obter mais exemplos de criação de filtros de eventos usando a AWS CLI, consulte Uso de filtros com diferentes Serviços da AWS.

Anexar critérios de filtros a um mapeamento de fonte de eventos (AWS SAM)

Suponha que você deseje configurar uma origem de eventos no AWS SAM para usar os seguintes critérios de filtro:


{
   "Filters": [
      {
          "Pattern": "{ \"Metadata\" : [ 1, 2 ] }"
      }
   ]
}

Para adicionar esses critérios de filtro ao mapeamento da origem do evento, insira o trecho a seguir no modelo YAML da origem do evento.


FilterCriteria: 
  Filters: 
    - Pattern: '{"Metadata": [1, 2]}'

Para obter mais informações sobre como criar e configurar um modelo do AWS SAM para um mapeamento da origem do evento, consulte a seção EventSource do Guia do desenvolvedor do AWS SAM. Para obter mais exemplos de criação de filtros de eventos usando modelos do AWS SAM, consulte Uso de filtros com diferentes Serviços da AWS.

Uso de filtros com diferentes Serviços da AWS

Diferentes tipos de origens de eventos usam diferentes valores-chave para seus campos de dados. Para filtrar as propriedades de dados, certifique-se de usar a chave correta no padrão do seu filtro. A tabela a seguir fornece as chaves de filtragem para cada um dos AWS service (Serviço da AWS) com suporte.

AWS service (Serviço da AWS)	Chave de filtragem
DynamoDB	`dynamodb`
Kinesis	`data`
Amazon MQ	`data`
Amazon MSK	`value`
Apache Kafka autogerenciado	`value`
Amazon SQS	`body`

As seções a seguir fornecem exemplos de padrões de filtro para diferentes tipos de origens de eventos. Eles também fornecem definições de formatos de dados recebidos e formatos de corpo de padrões de filtro para cada serviço com suporte.

Filtragem com DynamoDB

Suponha que você tenha uma tabela do DynamoDB com chave primária CustomerName e atributos AccountManager e PaymentTerms. Veja a seguir um exemplo de registro do stream da sua tabela do DynamoDB.


{
      "eventID": "1",
      "eventVersion": "1.0",
      "dynamodb": {
          "ApproximateCreationDateTime": "1678831218.0",
          "Keys": {
              "CustomerName": {
                  "S": "AnyCompany Industries"
              },
              "NewImage": {
                  "AccountManager": {
                      "S": "Pat Candella"
                  },
                  "PaymentTerms": {
                      "S": "60 days"
                  },
                  "CustomerName": {
                      "S": "AnyCompany Industries"
                  }
              },
              "SequenceNumber": "111",
              "SizeBytes": 26,
              "StreamViewType": "NEW_IMAGE"
          }
      }
  }

Para filtrar com base nos valores de chave e atributo em sua tabela do DynamoDB, use a chave dynamodb no registro. As seções a seguir fornecem exemplos de diferentes tipos de filtro.

Como filtrar com chaves de tabela

Suponha que você queira que sua função processe somente os registros em que a chave primária CustomerName seja “AnyCompany Industries”. O objeto FilterCriteria seria como a seguir.


{
     "Filters": [
          {
              "Pattern": "{ \"dynamodb\" : { \"Keys\" : { \"CustomerName\" : { \"S\" : [ \"AnyCompany Industries\" ] } } } }"
          }
      ]
 }

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
     "dynamodb": {
          "Keys": {
              "CustomerName": {
                  "S": [ "AnyCompany Industries" ]
                  }
              }
          }
 }

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

Como filtrar com atributos de tabela

Com o DynamoDB, você também pode usar as teclas NewImage e OldImage para filtrar os valores dos atributos. Suponha que você queira filtrar registros em que o atributo AccountManager na imagem mais recente da tabela seja “Pat Candella” ou “Shirley Rodriguez”. O objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\" : { \"NewImage\" : { \"AccountManager\" : { \"S\" : [ \"Pat Candella\", \"Shirley Rodriguez\" ] } } } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "dynamodb": {
        "NewImage": {
            "AccountManager": {
                "S": [ "Pat Candella", "Shirley Rodriguez" ]
            }
        }
    }
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

Como filtrar com expressões boolianas

Você também pode criar filtros usando expressões boolianas AND. Essas expressões podem incluir os parâmetros de chave e de atributo da tabela. Suponha que você queira filtrar registros em que o valor de NewImage de AccountManager seja “Pat Candella” e o valor de OldImage seja “Terry Whitlock”. O objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"dynamodb\" : { \"NewImage\" : { \"AccountManager\" : { \"S\" : [ \"Pat Candella\" ] } } } , \"dynamodb\" : { \"OldImage\" : { \"AccountManager\" : { \"S\" : [ \"Terry Whitlock\" ] } } } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{ 
    "dynamodb" : { 
        "NewImage" : { 
            "AccountManager" : { 
                "S" : [ 
                    "Pat Candella" 
                ] 
            } 
        } 
    }, 
    "dynamodb": { 
        "OldImage": { 
            "AccountManager": { 
                "S": [ 
                    "Terry Whitlock" 
                ] 
            } 
        } 
    } 
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

nota

A filtragem de eventos do DynamoDB não oferece suporte ao uso de operadores numéricos (igualdade numérica e intervalo numérico). Mesmo que os itens em sua tabela sejam armazenados como números, esses parâmetros são convertidos em strings no objeto do registro JSON.

Como usar o operador Exists com o DynamoDB

Devido à forma de estruturação dos objetos de evento JSON do DynamoDB, o uso do operador Exists requer cuidados especiais. O operador Exists só funciona em nós terminais no evento JSON. Portanto, se seu padrão de filtro usar Exists para testar um nó intermediário, ele não funcionará. Considere o seguinte item de tabela do DynamoDB:


{
  "UserID": {"S": "12345"},
  "Name": {"S": "John Doe"},
  "Organizations": {"L": [
      {"S":"Sales"},
      {"S":"Marketing"},
      {"S":"Support"}
    ]
  }
}

Talvez você queira criar um padrão de filtro como o seguinte, que teste os eventos que contenham "Organizations":


{ "dynamodb" : { "NewImage" : { "Organizations" : [ { "exists": true } ] } } }

No entanto, esse padrão de filtro nunca retornaria uma correspondência porque "Organizations" não é um nó terminal. O exemplo a seguir mostra como usar corretamente o operador Exists para estruturar o padrão de filtro desejado:


{ "dynamodb" : { "NewImage" : {"Organizations": {"L": {"S": [ {"exists": true } ] } } } } }

Formato JSON para filtragem do DynamoDB

Para filtrar corretamente eventos de origens do DynamoDB, tanto o campo de dados como os critérios de filtro para o campo de dados (dynamodb) devem estar em formato JSON válido. Se algum desses campos não estiver em um formato JSON válido, o Lambda descartará a mensagem ou emitirá uma exceção. A tabela a seguir resume o comportamento específico:

Formato dos dados recebidos	Formato de filtro padrão para propriedades de dados	Ação resultante
JSON válido	JSON válido	Filtros do Lambda com base em seus critérios de filtro.
JSON válido	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	Não JSON	O Lambda emite uma exceção no momento da criação ou atualização do mapeamento da fonte de eventos. O padrão de filtro para propriedades de dados deve estar em um formato JSON válido.
Não JSON	JSON válido	O Lambda descarta o registro.
Não JSON	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
Não JSON	Não JSON	O Lambda emite uma exceção no momento da criação ou atualização do mapeamento da fonte de eventos. O padrão de filtro para propriedades de dados deve estar em um formato JSON válido.

Filtragem com o Kinesis

Suponha que um produtor esteja inserindo dados formatados em JSON em seu fluxo de dados do Kinesis. Um exemplo de registro seria semelhante ao a seguir, com os dados JSON convertidos em uma string codificada em Base64 no campo data.


{
    "kinesis": {
        "kinesisSchemaVersion": "1.0",
        "partitionKey": "1",
        "sequenceNumber": "49590338271490256608559692538361571095921575989136588898",
        "data": "eyJSZWNvcmROdW1iZXIiOiAiMDAwMSIsICJUaW1lU3RhbXAiOiAieXl5eS1tbS1kZFRoaDptbTpzcyIsICJSZXF1ZXN0Q29kZSI6ICJBQUFBIn0=",
        "approximateArrivalTimestamp": 1545084650.987
        },
    "eventSource": "aws:kinesis",
    "eventVersion": "1.0",
    "eventID": "shardId-000000000006:49590338271490256608559692538361571095921575989136588898",
    "eventName": "aws:kinesis:record",
    "invokeIdentityArn": "arn:aws:iam::123456789012:role/lambda-role",
    "awsRegion": "us-east-2",
    "eventSourceARN": "arn:aws:kinesis:us-east-2:123456789012:stream/lambda-stream"
}

Desde que os dados que o produtor coloque no stream sejam JSON válido, é possível usar a filtragem de eventos para filtrar registros usando a chave data. Suponha que um produtor esteja inserindo dados em seu stream do Kinesis no formato JASON a seguir.


{
    "record": 12345,
    "order": {
        "type": "buy",
        "stock": "ANYCO",
        "quantity": 1000
        }
}

Para filtrar somente os registros em que o tipo de pedido é “comprar”, o objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"data\" : { \"order\" : { \"type\" : [ \"buy\" ] } } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "data": {
        "order": {
            "type": [ "buy" ]
            }
      }
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

Para filtrar corretamente eventos de origens do Kinesis, tanto o campo de dados como os critérios de filtro para o campo de dados devem estar em formato JSON válido. Se algum desses campos não estiver em um formato JSON válido, o Lambda descartará a mensagem ou emitirá uma exceção. A tabela a seguir resume o comportamento específico:

Formato dos dados recebidos	Formato de filtro padrão para propriedades de dados	Ação resultante
JSON válido	JSON válido	Filtros do Lambda com base em seus critérios de filtro.
JSON válido	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	Não JSON	O Lambda emite uma exceção no momento da criação ou atualização do mapeamento da fonte de eventos. O padrão de filtro para propriedades de dados deve estar em um formato JSON válido.
Não JSON	JSON válido	O Lambda descarta o registro.
Não JSON	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
Não JSON	Não JSON	O Lambda emite uma exceção no momento da criação ou atualização do mapeamento da fonte de eventos. O padrão de filtro para propriedades de dados deve estar em um formato JSON válido.

Filtragem de registros agregados do Kinesis

Com o Kinesis, é possível agregar vários registros em um único registro do Kinesis Data Streams para aumentar seu throughput. O Lambda pode aplicar critérios de filtro a registros agregados somente quando você usar a distribuição avançada do Kinesis. Não há suporte para a filtragem de registros agregados com o Kinesis padrão. Ao usar a distribuição avançada, você configura um consumidor de throughput dedicado do Kinesis para atuar como acionador para sua função do Lambda. Em seguida, o Lambda filtra os registros agregados e passa somente os registros que atendam aos seus critérios de filtragem.

Para saber mais sobre a agregação de registros do Kinesis, consulte a seção Agregação na página Conceitos principais da Kinesis Producer Library (KPL). Para saber mais sobre como usar o Lambda com a distribuição avançada do Kinesis, consulte Aumento do desempenho do processamento de streams em tempo real com a distribuição avançada do Amazon Kinesis Data Streams e o AWS Lambda no blog de computação da AWS.

Filtragem com o Amazon MQ

Suponha que sua fila de mensagens do Amazon MQ contenha mensagens em formato JSON válido ou como strings simples. Um exemplo de registro seria semelhante ao a seguir, com os dados convertidos em uma string codificada em Base64 no campo data.

Para os agentes Active MQ e Rabbit MQ, é possível usar a filtragem de eventos para filtrar registros usando a chave data. Suponha que a fila do Amazon MQ contenha mensagens no formato JSON a seguir.


{
    "timeout": 0,
    "IPAddress": "203.0.113.254"
}

Para filtrar somente os registros onde o campo timeout é maior que 0, o objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"data\" : { \"timeout\" : [ { \"numeric\": [ \">\", 0] } } ] } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "data": {
        "timeout": [ { "numeric": [ ">", 0 ] } ]
        }
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

Com o Amazon MQ, você também pode filtrar registros onde a mensagem é uma string simples. Suponha que você queira processar somente registros onde a mensagem comece com “Resultado: ”. O objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"data\" : [ { \"prefix\": \"Result: \" } ] }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "data": [
        {
        "prefix": "Result: "
        }
    ]
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

As mensagens do Amazon MQ devem ser strings codificadas em UTF-8, sejam em strings simples ou no formato JSON. Isso porque o Lambda decodifica as matrizes de bytes do Amazon MQ em UTF-8 antes de aplicar os critérios de filtragem. Se as mensagens usarem outra codificação, como UTF-16 ou ASCII, ou se o formato da mensagem não corresponder ao formato dos FilterCriteria, o Lambda processará somente os filtros de metadados. A tabela a seguir resume o comportamento específico:

Formato do da mensagem recebida	Formato padrão de filtro para propriedades de mensagem	Ação resultante
String simples	String simples	Filtros do Lambda com base em seus critérios de filtro.
String simples	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
String simples	JSON válido	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	String simples	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	JSON válido	Filtros do Lambda com base em seus critérios de filtro.
String não codificada em UTF-8	JSON, string de texto simples ou nenhum padrão	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.

Filtragem com o Amazon MSK e o Apache Kafka autogerenciado

Suponha que um produtor esteja escrevendo mensagens para um tópico em seu cluster do Amazon MSK ou do Apache Kafka autogerenciado, em formato JSON válido ou como strings simples. Um exemplo de registro seria semelhante ao a seguir, com a mensagem convertida em uma string codificada em Base64 no campo value.


{
    "mytopic-0":[
        {
            "topic":"mytopic",
            "partition":0,
            "offset":15,
            "timestamp":1545084650987,
            "timestampType":"CREATE_TIME",
            "value":"SGVsbG8sIHRoaXMgaXMgYSB0ZXN0Lg==",
            "headers":[]
        }
    ]
}

Suponha que o produtor do Apache Kafka esteja escrevendo mensagens para o tópico no formato JSON a seguir.


{
    "device_ID": "AB1234",
    "session":{
        "start_time": "yyyy-mm-ddThh:mm:ss",
        "duration": 162
    }
}

É possível usar a chave value para filtrar registros. Suponha que você queira filtrar somente os registros onde device_ID comece com as letras AB. O objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"value\" : { \"device_ID\" : [ { \"prefix\": \"AB\" } ] } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "value": {
        "device_ID": [ { "prefix": "AB" } ]
      }
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

Com o Amazon MSK e o Apache Kafka autogerenciado, também é possível filtrar registros onde a mensagem seja uma sequência de caracteres simples. Suponha que você queira ignorar as mensagens em que a string seja “erro”. O objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"value\" : [ { \"anything-but\": [ \"error\" ] } ] }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "value": [
        {
        "anything-but": [ "error" ]
        }
    ]
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

As mensagens do Amazon MSK e do Apache Kafka autogerenciado devem ser strings codificadas em UTF-8, sejam em texto simples ou no formato JSON. Isso porque o Lambda decodifica as matrizes de bytes do Amazon MSK em UTF-8 antes de aplicar os critérios de filtragem. Se as mensagens usarem outra codificação, como UTF-16 ou ASCII, ou se o formato da mensagem não corresponder ao formato dos FilterCriteria, o Lambda processará somente os filtros de metadados. A tabela a seguir resume o comportamento específico:

Formato do da mensagem recebida	Formato padrão de filtro para propriedades de mensagem	Ação resultante
String simples	String simples	Filtros do Lambda com base em seus critérios de filtro.
String simples	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
String simples	JSON válido	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	String simples	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	JSON válido	Filtros do Lambda com base em seus critérios de filtro.
String não codificada em UTF-8	JSON, string de texto simples ou nenhum padrão	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.

Filtragem com o Amazon SQS

Suponha que sua fila do Amazon SQS contenha mensagens no formato JSON a seguir.


{
    "RecordNumber": 0000,
    "TimeStamp": "yyyy-mm-ddThh:mm:ss",
    "RequestCode": "AAAA"
}

Um exemplo de registro para essa fila seria como a seguir.


{
    "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
    "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
    "body": "{\n "RecordNumber": 0000,\n "TimeStamp": "yyyy-mm-ddThh:mm:ss",\n "RequestCode": "AAAA"\n}",
    "attributes": {
        "ApproximateReceiveCount": "1",
        "SentTimestamp": "1545082649183",
        "SenderId": "AIDAIENQZJOLO23YVJ4VO",
        "ApproximateFirstReceiveTimestamp": "1545082649185"
        },
    "messageAttributes": {},
    "md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
    "eventSource": "aws:sqs",
    "eventSourceARN": "arn:aws:sqs:us-west-2:123456789012:my-queue",
    "awsRegion": "us-west-2"
}

Para filtrar com base no conteúdo de suas mensagens do Amazon SQS, use a chave body no registro de mensagens do Amazon SQS. Suponha que você queira processar somente os registros onde o RequestCode na sua mensagem do Amazon SQS seja “BBBB”. O objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"body\" : { \"RequestCode\" : [ \"BBBB\" ] } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "body": {
        "RequestCode": [ "BBBB" ]
        }
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

Suponha que você queira que sua função processe somente os registros onde RecordNumber seja maior que 9999. O objeto FilterCriteria seria como a seguir.


{
    "Filters": [
        {
            "Pattern": "{ \"body\" : { \"RecordNumber\" : [ { \"numeric\": [ \">\", 9999 ] } ] } }"
        }
    ]
}

Para maior clareza, aqui está o valor de Pattern do filtro expandido em JSON simples.


{
    "body": {
        "RecordNumber": [
            {
                "numeric": [ ">", 9999 ]
            }
        ]
    }
}

É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.

No Amazon SQS, o corpo da mensagem pode ser qualquer string. Porém, isso pode ser problemático se os FilterCriteria esperarem que o body esteja em um formato JSON válido. O cenário oposto também é verdadeiro: se o corpo da mensagem recebida estiver em formato JSON, mas seus critérios de filtragem esperarem que o body seja uma string simples, isso poderá levar um comportamento não pretendido.

Para evitar esse problema, certifique-se de que o formato do corpo nos seus FilterCriteria corresponda ao formato esperado do body nas mensagens que você receber da fila. Antes de filtrar suas mensagens, o Lambda avalia automaticamente o formato do corpo da mensagem recebida e do seu padrão de filtro para o body. Se houver incompatibilidade, o Lambda descartará a mensagem. A tabela a seguir resume essa avaliação:

Formato do `body` da mensagem recebida	Formato do `body` do padrão de filtro	Ação resultante
String simples	String simples	Filtros do Lambda com base em seus critérios de filtro.
String simples	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
String simples	JSON válido	O Lambda descarta a mensagem.
JSON válido	String simples	O Lambda descarta a mensagem.
JSON válido	Nenhum padrão de filtro para propriedades de dados	Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro.
JSON válido	JSON válido	Filtros do Lambda com base em seus critérios de filtro.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Tutorial

Testes no console