Contrôlez les événements que Lambda envoie à votre fonction

Vous pouvez utiliser le filtrage d’événements pour contrôler les enregistrements d’un flux ou d’une file d’attente que Lambda envoie à votre fonction. Par exemple, vous pouvez ajouter un filtre afin que votre fonction traite uniquement les SQS messages Amazon contenant certains paramètres de données. Le filtrage des événements ne fonctionne qu'avec certains mappages de sources d'événements. Vous pouvez ajouter des filtres aux mappages de sources d'événements pour les AWS services suivants :

Pour obtenir des informations spécifiques sur le filtrage avec des sources d'événements spécifiques, consultezUtilisation de filtres avec différents Services AWS. Lambda ne prend pas en charge le filtrage d’événements pour Amazon DocumentDB.

Par défaut, vous pouvez définir jusqu’à cinq filtres différents pour un seul mappage des sources d’événements. Vos filtres sont logiquement ORed combinés. Si un enregistrement de votre source d’événement satisfait un ou plusieurs de vos filtres, Lambda inclut l’enregistrement dans le prochain événement qu’il envoie à votre fonction. Si aucun de vos filtres n’est satisfait, Lambda rejette l’enregistrement.

Comprendre les principes de base du filtrage des événements

Un objet (FilterCriteria) de critères de filtre est une structure composée d’une liste de filtres (Filters). Chaque filtre est une structure qui définit un modèle de filtrage d’événements (Pattern). Un modèle est une représentation sous forme de chaîne d'une règle de JSON filtre. La structure d’un objet FilterCriteria est la suivante.

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

Pour plus de clarté, voici la valeur du filtre Pattern expansé en clairJSON.

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

Votre modèle de filtrage peut inclure des propriétés de métadonnées, des propriétés de données ou les deux. Les paramètres de métadonnées disponibles et le format des paramètres de données varient en fonction de l’objet Service AWS qui sert de source d’événements. Supposons, par exemple, que le mappage de la source de votre événement reçoive l'enregistrement suivant d'une SQS file d'attente Amazon :

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

Les différents types de sources d’événements utilisent des valeurs clés différentes pour leurs champs de données. Pour filtrer sur les propriétés de données, assurez-vous d’utiliser la bonne clé dans le modèle de votre filtre. Pour obtenir la liste des clés de filtrage des données et des exemples de modèles de filtre pris en charge pour chacune d'entre elles Service AWS, reportez-vous àUtilisation de filtres avec différents Services AWS.

Le filtrage des événements peut gérer le JSON filtrage à plusieurs niveaux. Par exemple, considérez le fragment suivant d’un enregistrement provenant d’un flux DynamoDB :

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

Supposons que vous vouliez traiter uniquement les enregistrements dont la valeur de la clé de tri Number est 4 567. Dans ce cas, votre objet FilterCriteria se présente comme suit :

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

Pour plus de clarté, voici la valeur du filtre Pattern expansé en clairJSON.

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

Traitement des enregistrements ne répondant pas aux critères de filtrage

La façon dont Lambda gère les enregistrements qui ne répondent pas à vos critères de filtre dépend de la source de l'événement.

Syntaxe des règles de filtrage

Pour les règles de filtrage, Lambda prend en charge EventBridge les règles Amazon et utilise la même syntaxe que. EventBridge Pour plus d'informations, consultez les modèles EventBridge d'événements Amazon dans le guide de EventBridge l'utilisateur Amazon.

Voici un récapitulatif de tous les opérateurs de comparaison disponibles pour le filtrage d’événement Lambda.

Notez que l'opérateur Exists ne fonctionne que sur les nœuds foliaires de votre source d'événementsJSON. Il ne correspond pas aux nœuds intermédiaires. Par exemple, avec ce qui suitJSON, le modèle de filtre { "person": { "address": [ { "exists": true } ] } }" ne trouverait aucune correspondance car il "address" s'agit d'un nœud intermédiaire.

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

Attacher des critères de filtre à un mappage de sources d’événements (console)

Suivez ces étapes pour créer un nouveau mappage de source d’événement avec des critères de filtre à l’aide de la console Lambda.

Lorsque vous saisissez des critères de filtrage à l’aide de la console, vous n’entrez que le modèle de filtrage et n’avez pas besoin d’indiquer la touche Pattern ni d’échapper aux guillemets. À l’étape 6 des instructions précédentes, { "Metadata" : [ 1, 2 ] } correspond à ce qui suit FilterCriteria.

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

Après avoir créé le mappage de la source d’événements dans la console, vous pouvez voir les FilterCriteria formatés dans les détails du déclencheur. Pour plus d’exemples de création de filtres d’événements à l’aide de la console, consultez Utilisation de filtres avec différents Services AWS.

Attacher des critères de filtre à un mappage de sources d’événements (AWS CLI)

Supposons que vous souhaitiez que le mappage d’une source d’événements comporte les suivants  FilterCriteria:

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

Pour créer un nouveau mappage de source d'événements avec ces critères de filtre à l'aide de AWS Command Line Interface (AWS CLI), exécutez la commande suivante.

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 ]}"}]}'

Cette create-event-source-mappingcommande crée un nouveau mappage de source d'SQSévénements Amazon pour la fonction my-function avec le paramètre spécifiéFilterCriteria.

Pour ajouter ces critères de filtre à un mappage des sources d’événements existant, exécutez la commande suivante.

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

Notez que pour mettre à jour le mappage d'une source d'événement, vous en avez besoinUUID. Vous pouvez les obtenir grâce UUID à un list-event-source-mappingsappel. Lambda renvoie également le UUID dans la create-event-source-mappingCLIréponse.

Pour supprimer les critères de filtre d'une source d'événement, vous pouvez exécuter la update-event-source-mappingcommande suivante avec un FilterCriteria objet vide.

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

Pour plus d'exemples de création de filtres d'événements à l'aide du AWS CLI, voirUtilisation de filtres avec différents Services AWS.

Attacher des critères de filtre à un mappage de sources d’événements (AWS SAM)

Supposons que vous souhaitiez configurer une source d'événements AWS SAM pour utiliser les critères de filtre suivants :

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

Pour ajouter ces critères de filtre au mappage de votre source d'événement, insérez l'extrait suivant dans le YAML modèle de votre source d'événement.

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

Pour plus d'informations sur la création et la configuration d'un AWS SAM modèle pour un mappage de sources d'événements, consultez la EventSourcesection du guide du AWS SAM développeur. Pour plus d'exemples de création de filtres d'événements à l'aide AWS SAM de modèles, consultezUtilisation de filtres avec différents Services AWS.

Chiffrement des critères de filtre

Par défaut, Lambda ne chiffre pas votre objet de critères de filtre. Dans les cas d'utilisation où vous pouvez inclure des informations sensibles dans votre objet de critères de filtre, vous pouvez utiliser votre propre KMSclé pour les chiffrer.

Une fois que vous avez chiffré votre objet de critères de filtre, vous pouvez consulter sa version en texte brut à l'aide d'un GetEventSourceMappingAPIappel. Vous devez disposer kms:Decrypt des autorisations nécessaires pour afficher correctement les critères de filtre en texte brut.

Vous pouvez spécifier votre propre KMS clé via la console,API/CLI, ou AWS CloudFormation.

Si vous utilisez votre propre KMS clé, les API opérations suivantes doivent être autorisées dans la politique des clés :

Vous pouvez l'utiliser AWS CloudTrail pour suivre les AWS KMS demandes que Lambda fait en votre nom. Pour des exemples CloudTrail d'événements, voirSurveillance de vos clés de chiffrement pour Lambda.

Nous recommandons également d'utiliser la clé de kms:ViaServicecondition pour limiter l'utilisation de la KMS clé aux demandes provenant de Lambda uniquement. La valeur de cette clé est le principal de service Lambda régional ()lambda.AWS_region.amazonaws.com. Voici un exemple de politique clé qui accorde toutes les autorisations pertinentes :

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

Pour utiliser votre propre KMS clé afin de chiffrer les critères de filtre, vous pouvez également utiliser la CreateEventSourceMapping AWS CLI commande suivante. Spécifiez la KMS clé ARN avec le --kms-key-arn drapeau.

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

Si vous disposez déjà d'un mappage de source d'événements, utilisez plutôt la UpdateEventSourceMapping AWS CLI commande. Spécifiez la KMS clé ARN avec le --kms-key-arn drapeau.

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

Cette opération remplace toute KMS clé précédemment spécifiée. Si vous spécifiez l'--kms-key-arnindicateur avec un argument vide, Lambda cesse d'utiliser votre KMS clé pour chiffrer les critères de filtre. Lambda utilise à nouveau par défaut une clé appartenant à Amazon.

Pour spécifier votre propre KMS clé dans un AWS CloudFormation modèle, utilisez la KMSKeyArn propriété du type de AWS::Lambda::EventSourceMapping ressource. Par exemple, vous pouvez insérer l'extrait suivant dans le YAML modèle de votre source d'événement.

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

Pour pouvoir afficher vos critères de filtre chiffrés en texte clair dans un DeleteEventSourceMappingAPIappel GetEventSourceMappingou, vous devez disposer d'kms:Decryptautorisations.

À compter du 6 août 2024, le FilterCriteria champ n'apparaît plus dans AWS CloudTrail les journaux de CreateEventSourceMappinget dans UpdateEventSourceMappingles DeleteEventSourceMappingAPIappels si votre fonction n'utilise pas le filtrage des événements. Si votre fonction utilise le filtrage des événements, le FilterCriteria champ apparaît vide ({}). Vous pouvez toujours afficher vos critères de filtre en texte clair en réponse aux GetEventSourceMappingAPIappels si vous êtes autorisé à kms:Decrypt utiliser la bonne KMS clé.

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

Utilisation de filtres avec différents Services AWS

Les différents types de sources d’événements utilisent des valeurs clés différentes pour leurs champs de données. Pour filtrer sur les propriétés de données, assurez-vous d’utiliser la bonne clé dans le modèle de votre filtre. Le tableau suivant indique les clés de filtrage pour chacune des clés prises en charge Service AWS.

Les sections suivantes présentent des exemples de modèles de filtres pour différents types de sources d'événements. Elles fournissent également des définitions des formats de données entrantes pris en charge et des formats de corps de modèle de filtre pour chaque service pris en charge.