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. È possibile aggiungere filtri alle mappature delle sorgenti degli eventi per quanto segue: Servizi AWS

Per informazioni specifiche sul filtraggio con origini eventi specifiche, consulta Utilizzo di filtri con diversi Servizi AWS. 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 nello schema del filtro. Per un elenco delle chiavi di filtraggio dei dati e per visualizzare esempi di modelli di filtro per ciascuna di esse supportate Servizio AWS, fai riferimento aUtilizzo di filtri con diversi Servizi AWS.

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 filtro, Lambda supporta le EventBridge regole Amazon e utilizza la stessa sintassi di. EventBridge Per ulteriori informazioni, consulta i modelli di EventBridge eventi di Amazon nella Amazon EventBridge User Guide.

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 diversi Servizi AWS.

Allegare criteri di filtro alla mappatura della sorgente di un 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 della sorgente di eventi con questi criteri di filtro utilizzando 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 di eventi utilizzando il AWS CLI, vedereUtilizzo di filtri con diversi Servizi AWS.

Allegare criteri di filtro a una mappatura della sorgente di un evento (AWS SAM)

Supponiamo di voler configurare una fonte di eventi in modo AWS SAM da 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 AWS SAM modello per la mappatura dell'origine di un evento, consulta la EventSource sezione della AWS SAM Developer Guide. Per altri esempi di creazione di filtri per eventi utilizzando i AWS SAM modelli, consulta. Utilizzo di filtri con diversi Servizi AWS

Crittografia dei criteri di filtro

Per impostazione predefinita, Lambda non crittografa l'oggetto dei criteri di filtro. Per i casi d'uso in cui potresti includere informazioni sensibili nell'oggetto dei criteri di filtro, puoi utilizzare la tua chiave KMS per crittografarle.

Dopo aver crittografato l'oggetto dei criteri di filtro, puoi visualizzarne la versione in testo normale utilizzando una chiamata 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,, o. API/CLI CloudFormation

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

Puoi utilizzarlo AWS CloudTrail per tenere traccia AWS KMS delle richieste effettuate da Lambda per tuo conto. Per esempi di CloudTrail eventi, consultaMonitoraggio 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:

Per utilizzare la tua chiave KMS per crittografare i criteri di filtro, puoi anche usare il seguente CreateEventSourceMapping AWS CLI comando. 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 una mappatura della sorgente degli eventi esistente, utilizza invece il UpdateEventSourceMapping AWS CLI comando. 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. Invece, per impostazione predefinita, Lambda utilizza una chiave. Amazon-owned

Per specificare la tua chiave KMS in un CloudFormation modello, utilizza la KMSKeyArn proprietà 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 chiaro in una chiamata GetEventSourceMapping or DeleteEventSourceMapping API, devi disporre delle autorizzazioni. kms:Decrypt

A partire dal 6 agosto 2024, il FilterCriteria campo non viene più visualizzato nei AWS CloudTrail log di CreateEventSourceMapping e nelle chiamate DeleteEventSourceMapping API se la funzione non utilizza il filtro degli eventi. UpdateEventSourceMapping Se la tua funzione utilizza il filtro degli eventi, il campo FilterCriteria viene visualizzato come vuoto ({}). Puoi comunque visualizzare i criteri di filtro in chiaro nella risposta alle chiamate GetEventSourceMapping API se disponi delle kms:Decrypt autorizzazioni 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 diversi Servizi AWS

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 nello schema del filtro. La tabella seguente fornisce le chiavi di filtro per ciascuna delle chiavi supportate Servizio AWS.

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.