Controlar quais eventos o Lambda envia para a função

É 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 certos mapeamentos de origens de eventos. É possível adicionar filtros aos mapeamentos da origem de eventos para os seguintes Serviços da AWS:

Para obter informações específicas sobre filtragem com origens de eventos específicas, consulte Uso de filtros com diferentes Serviços da AWS. 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.

Entender os conceitos básicos da 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"
}

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

Como o Lambda trata os registros que não atendem aos seus critérios de filtro depende da origem de eventos.

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 Amazon EventBridge event patterns no Amazon EventBridge User Guide.

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

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.

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. Você pode obter o UUID com uma chamada list-event-source-mappings. O Lambda também retorna o UUID na resposta da CLI a create-event-source-mapping.

Para remover os critérios de filtro de uma origem de eventos, você pode executar o comando update-event-source-mapping 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.

Criptografia de critérios de filtro

Por padrão, o Lambda não criptografa seu objeto de critérios de filtro. Para casos de uso em que você pode incluir informações confidenciais em seu objeto de critérios de filtro, você pode usar sua própria chave do KMS para criptografá-las.

Após criptografar seu objeto de critérios de filtro, você poderá visualizar sua versão em texto simples usando uma chamada de API GetEventSourceMapping. Você deve ter permissões kms:Decrypt para poder visualizar com êxito os critérios do filtro em texto simples.

Você pode especificar sua própria chave do KMS via console, API/CLI ou AWS CloudFormation.

Se você usa sua própria chave do KMS, as seguintes operações de API deverão ser permitidas na política de chaves:

É possível usar o AWS CloudTrail para rastrear solicitações do AWS KMS feitas pelo Lambda em seu nome. Para exemplos de eventos do CloudTrail, consulte Monitorar suas chaves de criptografia para o Lambda.

Também recomendamos usar a chave de condição kms:ViaService para limitar o uso da chave do KMS somente às solicitações do Lambda. O valor dessa chave é a entidade principal do serviço Lambda (lambda.AWS_region.amazonaws.com) regional. Veja a seguir um exemplo de política de chave que concede todas as permissões relevantes:

{
    "Version": "2012-10-17",
    "Id": "example-key-policy-1",
    "Statement": [
        {
            "Sid": "Allow Lambda to decrypt using the key",
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.us-east-1.amazonaws.com"
            },
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "ArnEquals" : {
                    "aws:SourceArn": [
                        "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:<esm_uuid>"
                    ]
                },
                "StringEquals": {
                    "kms:EncryptionContext:aws:lambda:FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:test-function",
                    "kms:EncryptionContext:aws:lambda:EventSourceArn": "arn:aws:sqs:us-east-1:123456789012:test-queue"
                }
            }
        },
        {
            "Sid": "Allow actions by an AWS account on the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow use of the key to specific roles",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
            },
            "Action": [
                "kms:Decrypt",
                "kms:DescribeKey",
                "kms:GenerateDataKey"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals" : {
                    "kms:ViaService": "lambda.us-east-1.amazonaws.com"
                }
            }
        }
    ]
}

Para usar sua própria chave do KMS para criptografar critérios de filtro, você também pode usar o comando da AWS CLI CreateEventSourceMapping a seguir. Especifique o ARN da chave do KMS com o sinalizador --kms-key-arn.

aws lambda create-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

Se você tiver um mapeamento da origem do evento existente, use o comando da AWS CLI UpdateEventSourceMapping em vez disso. Especifique o ARN da chave do KMS com o sinalizador --kms-key-arn.

aws lambda update-event-source-mapping --function-name my-function \
    --maximum-batching-window-in-seconds 60 \
    --event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
    --filter-criteria "{\"filters\": [{\"pattern\": \"{\"a\": [\"1\", \"2\"]}\" }]}" \
    --kms-key-arn arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

Essa operação substitui qualquer chave do KMS especificada anteriormente. Se você especificar o sinalizador --kms-key-arn junto com um argumento vazio, o Lambda deixará de usar sua chave do KMS para criptografar critérios de filtro. Em vez disso, o Lambda retorna ao padrão de usar uma chave pertencente à Amazon.

Para especificar sua própria chave do KMS em um modelo do AWS CloudFormation, use a propriedade KMSKeyArn do tipo de recurso AWS::Lambda::EventSourceMapping. Por exemplo, você pode inserir o trecho a seguir no modelo YAML da origem do evento.

MyEventSourceMapping:
  Type: AWS::Lambda::EventSourceMapping
  Properties:
    ...
    FilterCriteria:
      Filters:
        - Pattern: '{"a": [1, 2]}'
    KMSKeyArn: "arn:aws:kms:us-east-1:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599"
    ...

Para poder visualizar seus critérios de filtro criptografados em texto simples em uma chamada de API GetEventSourceMapping ou DeleteEventSourceMapping, é necessário ter permissões kms:Decrypt.

A partir de 6 de agosto de 2024, o campo FilterCriteria não aparecerá mais nos logs do AWS CloudTrail das chamadas de API CreateEventSourceMapping, UpdateEventSourceMapping e DeleteEventSourceMapping se sua função não usar a filtragem de eventos. Se sua função usa filtragem de eventos, o campo FilterCriteria aparece como vazio ({}). Você ainda poderá visualizar seus critérios de filtro em texto simples na resposta das chamadas de API GetEventSourceMapping se tiver permissões kms:Decrypt para a chave do KMS correta.

{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "AROA123456789EXAMPLE:userid1",
        "arn": "arn:aws:sts::123456789012:assumed-role/Example/example-role",
        "accountId": "123456789012",
        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "AROA987654321EXAMPLE",
                "arn": "arn:aws:iam::123456789012:role/User1",
                "accountId": "123456789012",
                "userName": "User1"
            },
            "webIdFederationData": {},
            "attributes": {
                "creationDate": "2024-05-09T20:35:01Z",
                "mfaAuthenticated": "false"
            }
        },
        "invokedBy": "AWS Internal"
    },
    "eventTime": "2024-05-09T21:05:41Z",
    "eventSource": "lambda.amazonaws.com",
    "eventName": "CreateEventSourceMapping20150331",
    "awsRegion": "us-east-2",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "AWS Internal",
    "requestParameters": {
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "functionName": "example-function",
        "enabled": true,
        "batchSize": 10,
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "scalingConfig": {},
        "maximumBatchingWindowInSeconds": 0,
        "sourceAccessConfigurations": []
    },
    "responseElements": {
        "uUID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
        "batchSize": 10,
        "maximumBatchingWindowInSeconds": 0,
        "eventSourceArn": "arn:aws:sqs:us-east-2:123456789012:example-queue",
        "filterCriteria": {},
        "kMSKeyArn": "arn:aws:kms:us-east-2:123456789012:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:example-function",
        "lastModified": "May 9, 2024, 9:05:41 PM",
        "state": "Creating",
        "stateTransitionReason": "USER_INITIATED",
        "functionResponseTypes": [],
        "eventSourceMappingArn": "arn:aws:lambda:us-east-2:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLEbbbbb"
    },
    "requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
    "eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "sessionCredentialFromConsole": "true"
}

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.

As seções a seguir dão 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.