Steuern Sie, welche Ereignisse Lambda an Ihre Funktion sendet

Sie können die Ereignisfilterung verwenden, um zu steuern, welche Datensätze aus einem Stream oder einer Warteschlange Lambda an Ihre Funktion sendet. Sie können zum Beispiel einen Filter hinzufügen, damit Ihre Funktion nur Amazon-SQS-Nachrichten verarbeitet, die bestimmte Datenparameter enthalten. Die Ereignisfilterung funktioniert nur mit der bestimmten Zuordnung von Ereignisquellen. Sie können den Ereignisquellenzuordnungen Filter für Folgendes hinzufügen: AWS-Services

Spezifische Informationen zum Filtern mit bestimmten Ereignisquellen finden Sie unter Verwenden von Filtern mit verschiedenen AWS-Services. Lambda unterstützt keine Ereignisfilterung für Amazon DocumentDB.

Standardmäßig können Sie bis zu fünf verschiedene Filter für eine einzelne Zuordnung von Ereignisquellen definieren. Ihre Filter sind logisch via OR verknüpft. Wenn ein Datensatz aus Ihrer Ereignisquelle einen oder mehrere Ihrer Filter erfüllt, nimmt Lambda den Datensatz in das nächste Ereignis auf, das es an Ihre Funktion sendet. Wenn keiner Ihrer Filter erfüllt ist, verwirft Lambda den Datensatz.

Grundlagen der Ereignisfilterung verstehen

Ein Filterkriterienobjekt (FilterCriteria) ist eine Struktur, die aus einer Liste von Filtern (Filters) besteht. Jeder Filter ist eine Struktur, die ein Ereignisfiltermuster (Pattern) definiert. Ein Muster ist eine Zeichenkette, die eine JSON-Filterregel darstellt. Die Struktur eines FilterCriteria-Objekts ist wie folgt.

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

Zur Verdeutlichung sehen Sie hier den Wert des Filter-Pattern in reinem JSON.

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

Ihr Filtermuster kann Metadateneigenschaften, Dateneigenschaften oder beides enthalten. Die verfügbaren Metadaten-Parameter und das Format der Daten-Parameter variieren je nach dem AWS-Service , der als Ereignisquelle fungiert. Nehmen wir zum Beispiel an, dass Ihre Zuordnung von Ereignisquellen den folgenden Datensatz von einer Amazon-SQS-Warteschlange empfängt:

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

Verschiedene Arten von Ereignisquellen verwenden unterschiedliche Schlüsselwerte für ihre Datenfelder. Um nach Dateneigenschaften zu filtern, stellen Sie sicher, dass Sie den richtigen Schlüssel im Muster Ihres Filters verwenden. Eine Liste der Datenfilterschlüssel und Beispiele für die jeweils unterstützten AWS-Service Filtermuster finden Sie unterVerwenden von Filtern mit verschiedenen AWS-Services.

Die Ereignisfilterung kann mehrstufige JSON-Filterung verarbeiten. Betrachten Sie zum Beispiel das folgende Fragment eines Datensatzes aus einem DynamoDB-Stream:

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

Angenommen, Sie möchten nur die Datensätze verarbeiten, bei denen die Number des Sortierschlüssels 4567 ist. In diesem Fall würde Ihr FilterCriteria-Objekt wie folgt aussehen:

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

Zur Verdeutlichung sehen Sie hier den Wert des Filter-Pattern in reinem JSON.

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

Umgang mit Datensätzen, die die Filterkriterien nicht erfüllen

Die Art und Weise, wie Lambda mit Datensätzen umgeht, die Ihren Filterkriterien nicht entsprechen, hängt von der Ereignisquelle ab.

Filterregelsyntax

Für Filterregeln unterstützt Lambda die EventBridge Amazon-Regeln und verwendet dieselbe Syntax wie EventBridge. Weitere Informationen finden Sie unter EventBridge Amazon-Ereignismuster im EventBridge Amazon-Benutzerhandbuch.

Im Folgenden finden Sie eine Zusammenfassung aller Vergleichsoperatoren, die für die Lambda-Ereignisfilterung verfügbar sind.

Beachten Sie, dass der Exists-Operator nur für Blattknoten in Ihrer JSON-Ereignisquelle funktioniert. Es passt nicht zu Zwischenknoten. Bei der folgenden JSON-Datei { "person": { "address": [ { "exists": true } ] } }" würde das Filtermuster beispielsweise keine Übereinstimmung finden, da es sich um einen Zwischenknoten "address" handelt.

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

Anhängen von Filterkriterien an eine Ereignisquellenzuordnung (Konsole)

Führen Sie diese Schritte aus, um eine neue Ereignisquellenzuordnung mit Filterkriterien über die Lambda-Konsole zu erstellen.

Wenn Sie Filterkriterien über die Konsole eingeben, geben Sie nur das Filtermuster ein und müssen weder den Pattern-Schlüssel noch Escape-Anführungszeichen angeben. In Schritt 6 der Anweisungen oben entspricht { "Metadata" : [ 1, 2 ] } den folgenden FilterCriteria.

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

Nachdem Sie Ihre Ereignisquellenzuordnung in der Konsole erstellt haben, sehen Sie die formatierten FilterCriteria in den Auslöserdetails. Weitere Beispiele zum Erstellen von Ereignisfiltern mithilfe der -Konsole finden Sie unter Verwenden von Filtern mit verschiedenen AWS-Services.

Hinzufügen von Filterkriterien zu einer Ereignisquellenzuordnung (AWS CLI)

Angenommen, Sie möchten, dass eine Ereignisquellenzuordnung folgende hat FilterCriteria:

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

Führen Sie den folgenden Befehl aus, um mithilfe von AWS Command Line Interface (AWS CLI) eine neue Ereignisquellenzuordnung mit diesen Filterkriterien zu erstellen.

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

Dieser create-event-source-mapping-Befehl erstellt eine neue Amazon SQS Zuordnung von Ereignisquellen für Funktion my-function mit den angegebenen FilterCriteria.

Führen Sie den folgenden Befehl aus, um diese Filterkriterien zu einer vorhandenen Zuordnung von Ereignisquellen hinzuzufügen.

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

Beachten Sie, dass Sie zum Aktualisieren einer Ereignisquellenzuordnung ihre UUID benötigen. Sie können die UUID über einen list-event-source-mappings-Aufruf erhalten. Lambda gibt die UUID auch in der create-event-source-mapping-CLI-Antwort zurück.

Um Filterkriterien aus einer Ereignisquelle zu entfernen, können Sie den folgenden Befehl update-event-source-mapping mit einem leeren FilterCriteria-Objekt ausführen.

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

Weitere Beispiele für das Erstellen von Ereignisfiltern mithilfe von finden Sie unterVerwenden von Filtern mit verschiedenen AWS-Services. AWS CLI

Hinzufügen von Filterkriterien zu einer Ereignisquellenzuordnung (AWS SAM)

Angenommen, Sie möchten eine Ereignisquelle so konfigurieren AWS SAM , dass sie die folgenden Filterkriterien verwendet:

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

Um diese Filterkriterien zu Ihrer Zuordnung von Ereignisquellen hinzuzufügen, fügen Sie das folgende Snippet in die YAML-Vorlage für Ihre Ereignisquelle ein.

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

Weitere Informationen zum Erstellen und Konfigurieren einer AWS SAM Vorlage für eine Ereignisquellenzuordnung finden Sie im EventSource Abschnitt des AWS SAM Entwicklerhandbuchs. Weitere Beispiele für das Erstellen von Eventfiltern mithilfe von AWS SAM Vorlagen finden Sie unterVerwenden von Filtern mit verschiedenen AWS-Services.

Verschlüsselung der Filterkriterien

Standardmäßig verschlüsselt Lambda Ihr Filterkriterienobjekt nicht. In Anwendungsfällen, in denen Sie möglicherweise vertrauliche Informationen in Ihr Filterkriterienobjekt aufnehmen, können Sie es mit Ihrem eigenen KMS-Schlüssel verschlüsseln.

Nachdem Sie Ihr Filterkriterienobjekt verschlüsselt haben, können Sie seine Klartextversion mithilfe eines GetEventSourceMapping API-Aufrufs anzeigen. Sie müssen über kms:Decrypt-Berechtigungen verfügen, um die Filterkriterien im Klartext anzeigen zu können.

Sie können Ihren eigenen KMS-Schlüssel über die Konsole angeben API/CLI, oder. CloudFormation

Wenn Sie Ihren eigenen KMS-Schlüssel verwenden, müssen die folgenden API-Vorgänge in der Schlüsselrichtlinie zugelassen sein:

Sie können AWS CloudTrail es verwenden, um AWS KMS Anfragen zu verfolgen, die Lambda in Ihrem Namen stellt. CloudTrail Beispielereignisse finden Sie unterÜberwachen Ihrer Verschlüsselungsschlüssel für Lambda.

Wir empfehlen außerdem, den kms:ViaService-Bedingungsschlüssel zu verwenden, um die Verwendung des KMS-Schlüssels nur auf Anfragen von Lambda zu beschränken. Der Wert dieses Schlüssels ist der regionale Lambda-Serviceprinzipal (lambda.AWS_region.amazonaws.com). Im Folgenden finden Sie ein Beispiel für eine Schlüsselrichtlinie, die alle relevanten Berechtigungen gewährt:

Um Ihren eigenen KMS-Schlüssel zum Verschlüsseln von Filterkriterien zu verwenden, können Sie auch den folgenden CreateEventSourceMapping AWS CLI Befehl verwenden. Geben Sie den KMS-Schlüssel ARN mit dem --kms-key-arn-Flag an.

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

Wenn Sie bereits über eine Ereignisquellenzuordnung verfügen, verwenden Sie stattdessen den UpdateEventSourceMapping AWS CLI Befehl. Geben Sie den KMS-Schlüssel ARN mit dem --kms-key-arn-Flag an.

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

Dieser Vorgang überschreibt alle zuvor angegebenen KMS-Schlüssel. Wenn Sie das --kms-key-arn-Flag zusammen mit einem leeren Argument angeben, verwendet Lambda Ihren KMS-Schlüssel nicht mehr zum Verschlüsseln von Filterkriterien. Stattdessen verwendet Lambda standardmäßig wieder einen Amazon-owned Schlüssel.

Um Ihren eigenen KMS-Schlüssel in einer CloudFormation Vorlage anzugeben, verwenden Sie die KMSKeyArn Eigenschaft des AWS::Lambda::EventSourceMapping Ressourcentyps. Sie können beispielsweise das folgende Snippet in die YAML-Vorlage für Ihre Ereignisquelle einfügen.

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

Um Ihre verschlüsselten Filterkriterien in einem GetEventSourceMapping oder DeleteEventSourceMapping API-Aufruf im Klartext anzeigen zu können, benötigen Sie entsprechende kms:Decrypt Berechtigungen.

Ab dem 6. August 2024 wird das FilterCriteria Feld nicht mehr in AWS CloudTrail Protokollen von und DeleteEventSourceMapping API-Aufrufen angezeigt CreateEventSourceMapping UpdateEventSourceMapping, wenn Ihre Funktion keine Ereignisfilterung verwendet. Wenn Ihre Funktion die Ereignisfilterung verwendet, wird das FilterCriteria-Feld als leer ({}) angezeigt. Sie können Ihre Filterkriterien in der Antwort auf GetEventSourceMapping API-Aufrufe weiterhin im Klartext anzeigen, wenn Sie über kms:Decrypt Berechtigungen für den richtigen KMS-Schlüssel verfügen.

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

Verwenden von Filtern mit verschiedenen AWS-Services

Verschiedene Arten von Ereignisquellen verwenden unterschiedliche Schlüsselwerte für ihre Datenfelder. Um nach Dateneigenschaften zu filtern, stellen Sie sicher, dass Sie den richtigen Schlüssel in Ihrem Filtermuster verwenden. Die folgende Tabelle enthält die Filterschlüssel für jeden unterstützten Schlüssel AWS-Service.

In den folgenden Abschnitten finden Sie Beispiele für Filtermuster für verschiedene Arten von Ereignisquellen. Sie enthalten auch Definitionen der unterstützten Formate für eingehende Daten und Filtermuster für jeden unterstützten Service.