Controllare gli eventi che Lambda invia alla funzione

Puoi utilizzare il filtraggio degli eventi per controllare quali record di un flusso o di una coda Lambda invia alla funzione. Ad esempio, puoi aggiungere un filtro in modo che la tua funzione elabori solo i messaggi Amazon SQS contenenti determinati parametri di dati. Il filtraggio degli eventi funziona solo con determinati strumenti di mappatura dell'origine degli eventi. Puoi aggiungere filtri allo strumento di mappatura dell'origine degli eventi per i seguenti Servizi AWS:

Per informazioni specifiche sul filtraggio con origini eventi specifiche, consulta Utilizzo di filtri con Servizi AWS diversi. Lambda non supporta il filtraggio degli eventi per Amazon DocumentDB.

Per impostazione predefinita, è possibile definire fino a cinque filtri diversi per una singola mappatura dell'origine degli eventi. I filtri sono logicamente elaborati come alternative nel loro insieme. Se un record proveniente dall'origine dell'evento soddisfa uno o più filtri, Lambda include il record nell'evento successivo che invia alla funzione. Se nessuno dei filtri è soddisfatto, Lambda scarta il record.

Nozioni di base sul filtraggio di eventi

Un oggetto criterio di filtro (FilterCriteria) è una struttura costituita da un elenco di filtri (Filters). Ogni filtro è una struttura che definisce un modello di filtraggio degli eventi (Pattern). Un modello è una rappresentazione di stringa di una regola di filtraggio JSON. La struttura di un oggetto FilterCriteria è come segue.

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

Per una maggiore chiarezza, ecco il valore del Pattern del filtro espanso in JSON semplice.

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

Il modello di filtraggio può includere proprietà dei metadati, proprietà dei dati o entrambe. I parametri dei metadati disponibili e il formato dei parametri dei dati variano a seconda del Servizio AWS che funge da origine dell'evento. Ad esempio, supponiamo che la mappatura dell'origine degli eventi riceva il seguente record da una coda 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"
}

Diversi tipi di origine degli eventi utilizzano valori di chiave differenti per i rispettivi campi di dati. Per filtrare le proprietà dei dati, assicurati di utilizzare la chiave corretta nel modello del filtraggio. Per un elenco delle chiavi di filtraggio dei dati e per degli esempi dei modelli di filtraggio per ogni Servizio AWS supportato, consulta la sezione Utilizzo di filtri con Servizi AWS diversi.

Il filtraggio degli eventi è in grado di gestire il filtraggio JSON multi-livello. Considera, ad esempio, il seguente frammento di un record da un flusso DynamoDB:

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

Supponi di voler elaborare solo i record in cui il valore della chiave di ordinamento Number è 4567. In questo caso, l'oggetto FilterCriteria appare così:

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

Per una maggiore chiarezza, ecco il valore del Pattern del filtro espanso in JSON semplice.

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

Gestione dei record che non soddisfano i criteri di filtraggio

Il modo in cui Lambda gestisce i record che non soddisfano i criteri di filtro dipende dall'origine eventi.

Sintassi delle regole di filtro

Per le regole di filtraggio, Lambda supporta le regole di Amazon EventBridge e utilizza la medesima sintassi di EventBridge. Per ulteriori informazioni, consulta Modelli di eventi Amazon EventBridge nella Guida per l'utente di Amazon EventBridge.

Di seguito è riportato un riepilogo di tutti gli operatori di confronto disponibili per il filtro eventi Lambda.

Tieni presente che l'operatore Exists funziona solo sui nodi foglia nell'origine eventi JSON. Non corrisponde ai nodi intermedi. Ad esempio, con il seguente codice JSON, lo schema di filtro { "person": { "address": [ { "exists": true } ] } }" non troverebbe una corrispondenza perché "address" è un nodo intermedio.

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

Collegamento dei criteri di filtro a una mappatura dell'origine evento (console)

Seguire questi passaggi per creare una nuova mappatura delle origini eventi con criteri di filtro utilizzando la console Lambda.

Quando si inseriscono i criteri di filtraggio utilizzando la console, si inserisce solo il modello di filtraggio e non è necessario fornire la chiave Pattern o le virgolette di escape. Nel passaggio 6 delle istruzioni precedenti, { "Metadata" : [ 1, 2 ] } corrisponde ai FilterCriteria seguenti.

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

Dopo aver creato la mappatura dell'origine eventi nella console, è possibile visualizzare il FilterCriteria formattato nei dettagli del trigger. Per altri esempi di creazione di filtri per gli eventi utilizzando la console, consulta la pagina Utilizzo di filtri con Servizi AWS diversi.

Collegamento dei criteri di filtro a una mappatura dell'origine evento (AWS CLI)

Supponiamo che si desideri che una mappatura dell'origine eventi abbia i seguenti FilterCriteria:

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

Per creare una nuova mappatura dell'origine degli eventi con questi criteri di filtraggio utilizzando l'AWS Command Line Interface (AWS CLI), esegui il comando seguente.

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

Il comando create-event-source-mapping crea una nuova mappatura dell'origine degli eventi Amazon SQS per la funzione my-function con i FilterCriteria specificati.

Per aggiungere questi criteri di filtraggio a una mappatura dell'origine degli eventi esistente, esegui il comando seguente.

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

Si noti che per aggiornare una mappatura di origine eventi, è necessario il suo UUID. È possibile ottenere l'UUID tramite una chiamata list-event-source-mappings. Lambda restituisce anche l'UUID nella risposta della CLI create-event-source-mapping.

Per rimuovere i criteri di filtraggio da un'origine degli eventi, è possibile eseguire il comando update-event-source-mapping con un oggetto FilterCriteria vuoto.

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

Per altri esempi di creazione di filtri per gli eventi utilizzando la AWS CLI, consulta la pagina Utilizzo di filtri con Servizi AWS diversi.

Collegamento dei criteri di filtro a una mappatura dell'origine evento (AWS SAM)

Supponiamo di voler configurare un'origine eventi AWS SAM per utilizzare i seguenti criteri di filtro:

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

Per aggiungere questi criteri di filtro allo strumento di mappatura dell'origine degli eventi, inserisci il seguente frammento nel modello YAML delle origini eventi.

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

Per ulteriori informazioni sulla creazione e la configurazione di un modello AWS SAM per uno strumento di mappatura dell'origine degli eventi, consulta la sezione EventSource della Guida per gli sviluppatori di AWS SAM. Per altri esempi di creazione di filtri per gli eventi utilizzando i modelli AWS SAM, consulta la pagina Utilizzo di filtri con Servizi AWS diversi.

Crittografia dei criteri di filtro

Per impostazione predefinita, Lambda non crittografa l'oggetto dei criteri di filtro. Nei casi d'uso in cui è possibile includere informazioni riservate nell'oggetto dei criteri di filtro, è possibile utilizzare la propria chiave KMS per crittografarlo.

Dopo aver crittografato l'oggetto dei criteri di filtro, puoi visualizzarne la versione in testo semplice utilizzando una chiamata all'API GetEventSourceMapping. È necessario disporre delle autorizzazioni kms:Decrypt per poter visualizzare correttamente i criteri di filtro in testo non crittografato.

Puoi specificare la tua chiave KMS tramite la console, l'API, la CLI o AWS CloudFormation.

Se utilizzi la tua chiave KMS, le seguenti operazioni API devono essere permesse nella policy della chiave:

È possibile utilizzare AWS CloudTrail per monitorare le richieste AWS KMS che Lambda invia per tuo conto. Per eventi CloudTrail di esempio, consulta Monitoraggio delle chiavi di crittografia per Lambda.

Consigliamo inoltre di utilizzare la chiave di condizione kms:ViaService per limitare l'uso della chiave KMS solo alle richieste provenienti da Lambda. Il valore di questa chiave è il principale del servizio Lambda regionale (lambda.AWS_region.amazonaws.com). Di seguito è riportata una policy della chiave di esempio che concede tutte le autorizzazioni pertinenti:

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

Per utilizzare la tua chiave KMS per crittografare i criteri di filtro, puoi anche utilizzare il seguente comando CreateEventSourceMapping della AWS CLI. Specifica l'ARN della chiave KMS con il flag --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 disponi di uno strumento di mappatura dell'origine degli eventi esistente, utilizza invece il comando UpdateEventSourceMapping della AWS CLI. Specifica l'ARN della chiave KMS con il flag --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

Questa operazione sovrascrive qualsiasi chiave KMS specificata in precedenza. Se specifichi il flag --kms-key-arn insieme a un argomento vuoto, Lambda smette di usare la chiave KMS per crittografare i criteri di filtro. Torna invece a utilizzare per impostazione predefinita una chiave di proprietà di Amazon.

Per specificare la tua chiave KMS in un modello AWS CloudFormation, utilizza la proprietà KMSKeyArn del tipo di risorsa AWS::Lambda::EventSourceMapping. Ad esempio, puoi inserire il seguente frammento di codice nel modello YAML dell'origine eventi.

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

Per poter visualizzare i criteri di filtro crittografati in testo semplice in una chiamata all'API GetEventSourceMapping o DeleteEventSourceMapping, è necessario disporre delle autorizzazioni kms:Decrypt.

A partire dal 6 agosto 2024, il campo FilterCriteria non viene più visualizzato nei log AWS CloudTrail delle chiamate API CreateEventSourceMapping, UpdateEventSourceMapping e DeleteEventSourceMapping se la funzione non utilizza il filtro degli eventi. Se la tua funzione utilizza il filtro degli eventi, il campo FilterCriteria viene visualizzato come vuoto ({}). Puoi comunque visualizzare i criteri di filtro in testo semplice nella risposta alle chiamate all'API GetEventSourceMapping se disponi delle autorizzazioni kms:Decrypt per la chiave KMS corretta.

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

Utilizzo di filtri con Servizi AWS diversi

Diversi tipi di origine degli eventi utilizzano valori di chiave differenti per i rispettivi campi di dati. Per filtrare le proprietà dei dati, assicurati di utilizzare la chiave corretta nel modello del filtraggio. La tabella seguente fornisce le chiavi di filtraggio per ciascun Servizio AWS supportato.

Le sezioni seguenti forniscono esempi di modelli di filtraggio per diversi tipi di origini eventi. Forniscono inoltre definizioni dei formati di dati in entrata supportati e dei formati del corpo dei modelli di filtraggio per ciascun servizio supportato.