Elaborazione di eventi Amazon DocumentDB con Lambda - AWS Lambda
Esempio di evento Amazon DocumentDBPrerequisiti e autorizzazioniConfigurazione della reteCreazione di una mappatura dell'origine degli eventi Amazon DocumentDB (console)Creazione di una mappatura dell'origine degli eventi Amazon DocumentDB (SDK o CLI)Posizioni di partenza di polling e flussiMonitoraggio dell'origine degli eventi di Amazon DocumentDB

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Elaborazione di eventi Amazon DocumentDB con Lambda

Per elaborare gli eventi in un flusso di modifica di Amazon DocumentDB (compatibile con MongoDB), puoi utilizzare una funzione Lambda configurando un cluster Amazon DocumentDB come origine degli eventi. Successivamente puoi automatizzare i carichi di lavoro basati sugli eventi invocando la funzione Lambda con il cluster Amazon DocumentDB ogni volta che i dati cambiano.

Nota

Lambda supporta solo le versioni 4.0 e 5.0 di Amazon DocumentDB. Lambda non supporta la versione 3.6.

Inoltre, per gli strumenti di mappatura dell'origine degli eventi, Lambda supporta solo cluster basati su istanze e cluster regionali. Lambda non supporta cluster elastici o cluster globali. Questa limitazione non si applica quando si utilizza Lambda come client per connettersi ad Amazon DocumentDB. Lambda può connettersi a tutti i tipi di cluster per eseguire operazioni CRUD.

Lambda elabora gli eventi di Amazon DocumentDB nei flussi di modifica in sequenza secondo l'ordine in cui arrivano. Per questo motivo, la tua funzione può gestire solo una chiamata simultanea da DocumentDB alla volta. Per monitorare la tua funzione, puoi tenere traccia dei relativi parametri di simultaneità.

avvertimento

Le mappature delle sorgenti degli eventi Lambda elaborano ogni evento almeno una volta e può verificarsi un'elaborazione duplicata dei record. Per evitare potenziali problemi legati agli eventi duplicati, ti consigliamo vivamente di rendere idempotente il codice della funzione. Per ulteriori informazioni, consulta Come posso rendere idempotente la mia funzione Lambda nel Knowledge Center. AWS

Argomenti

Esempio di evento Amazon DocumentDB

{
    "eventSourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:canaryclusterb2a659a2-qo5tcmqkcl03",
    "events": [
        {
            "event": {
                "_id": {
                    "_data": "0163eeb6e7000000090100000009000041e1"
                },
                "clusterTime": {
                    "$timestamp": {
                        "t": 1676588775,
                        "i": 9
                    }
                },
                "documentKey": {
                    "_id": {
                        "$oid": "63eeb6e7d418cd98afb1c1d7"
                    }
                },
                "fullDocument": {
                    "_id": {
                        "$oid": "63eeb6e7d418cd98afb1c1d7"
                    },
                    "anyField": "sampleValue"
                },
                "ns": {
                    "db": "test_database",
                    "coll": "test_collection"
                },
                "operationType": "insert"
            }
        }
    ],
    "eventSource": "aws:docdb"
}

Per ulteriori informazioni sugli eventi in questo esempio e sulle loro forme, consulta la sezione Eventi di modifica sul sito Web della documentazione di MongoDB.

Prerequisiti e autorizzazioni

Prima di utilizzare Amazon DocumentDB come origine degli eventi della funzione Lambda, è necessario tenere a mente i seguenti prerequisiti. Devi:

  • Disponi di un cluster Amazon DocumentDB esistente nella stessa Account AWS Regione AWS funzione. Se non hai un cluster esistente, puoi crearlo seguendo i passaggi riportati nella sezione Nozioni di base su Amazon DocumentDB nella Guida per gli sviluppatori di Amazon DocumentDB. In alternativa, la prima serie di passaggi riportati in Tutorial: Utilizzo AWS Lambda con Amazon DocumentDB Streams ti guideranno nella creazione di un cluster DocumentDB con tutti i prerequisiti necessari.

  • Concedere a Lambda l'accesso alle risorse di Amazon Virtual Private Cloud (Amazon VPC) associate al cluster Amazon DocumentDB. Per ulteriori informazioni, consulta Configurazione della rete.

  • Abilitare TLS sul cluster Amazon DocumentDB. Si tratta dell'impostazione di default. Se TLS è disabilitato, Lambda non è in grado di comunicare con il cluster.

  • È necessario attivare i flussi di modifica sul cluster Amazon DocumentDB. Per ulteriori informazioni, consulta la sezione Utilizzo dei flussi di modifica di Amazon DocumentDB nella Guida per gli sviluppatori di Amazon DocumentDB.

  • Fornire a Lambda le credenziali per accedere al cluster Amazon DocumentDB. Quando configuri l'origine degli eventi, fornisci la chiave AWS Secrets Manager che contiene i dettagli di autenticazione (nome utente e password) necessari per accedere al cluster. Per fornire questa chiave durante la configurazione, esegui una delle seguenti operazioni:

    • Se per la configurazione stai utilizzando la console Lambda, fornisci la chiave nel campo Chiave di Secrets manager.

    • Se utilizzi AWS Command Line Interface (AWS CLI) per la configurazione, fornisci questa chiave nell'source-access-configurationsopzione. È possibile includere questa opzione sia con il comando create-event-source-mapping sia con il comando update-event-source-mapping. Per esempio:

      aws lambda create-event-source-mapping \
    ...
    --source-access-configurations  '[{"Type":"BASIC_AUTH","URI":"arn:aws:secretsmanager:us-west-2:123456789012:secret:DocDBSecret-AbC4E6"}]' \
    ...

  • Concedere a Lambda le autorizzazioni per gestire le risorse correlate al flusso di Amazon DocumentDB. Aggiungi le seguenti autorizzazioni al ruolo di esecuzione della tua funzione:

  • È necessario mantenere la dimensione degli eventi del flusso di modifica di Amazon DocumentDB che invii a Lambda inferiore a 6 MB. Lambda supporta payload di dimensioni massime di 6 MB. Se il flusso di modifica tenta di inviare a Lambda un evento di dimensioni superiori a 6 MB, Lambda tralascia il messaggio ed emette il parametro OversizedRecordCount. Lambda emette tutte i parametri sulla base del miglior tentativo.

Nota

Sebbene le funzioni Lambda abbiano di solito un timeout massimo di 15 minuti, le mappature dell'origine degli eventi per Amazon MSK, Apache Kafka autogestito, Amazon DocumentDB e Amazon MQ per ActiveMQ e RabbitMQ supportano soltanto funzioni con timeout massimi di 14 minuti. Questa limitazione garantisce che lo strumento di mappatura dell'origine degli eventi possa gestire correttamente errori di funzioni e nuovi tentativi.

Configurazione della rete

Affinché Lambda possa utilizzare il cluster Amazon DocumentDB come origine di eventi, Lambda deve accedere all'Amazon VPC in cui risiede il cluster. Ti consigliamo di implementare gli endpoint AWS PrivateLink VPC per Lambda per accedere al tuo VPC. Implementa un endpoint VPC per Lambda e, se il cluster utilizza l'autenticazione, implementa anche un endpoint VPC per Secrets Manager.

In alternativa, verifica che il VPC associato al cluster Amazon DocumentDB includa un gateway NAT per sottorete pubblica. Per ulteriori informazioni, consulta Abilita l'accesso a Internet per le funzioni Lambda connesse a VPC.

Se utilizzi endpoint VPC, devi anche configurarli in modo da abilitare i nomi DNS privati.

Quando crei una mappatura dell'origine degli eventi per un cluster Amazon DocumentDB, Lambda verifica se le Interfacce di rete elastiche (ENI) sono già presenti per le sottoreti e i gruppi di sicurezza del VPC del cluster. Se Lambda trova ENI esistenti, tenta di riutilizzarli. Altrimenti, Lambda crea nuovi ENI per connettersi all'origine dell'evento e richiamare la tua funzione.

Nota

Le funzioni Lambda vengono sempre eseguite all'interno di VPC di proprietà del servizio Lambda. Questi VPC vengono gestiti automaticamente dal servizio e non sono visibili ai clienti. Puoi anche connettere la tua funzione a un Amazon VPC. In entrambi i casi, la configurazione VPC della funzione non influisce sulla mappatura delle sorgenti degli eventi. Solo la configurazione del VPC dell'origine dell'evento determina il modo in cui Lambda si connette alla fonte dell'evento.

Regole del gruppo di sicurezza VPC

Configura i gruppi di sicurezza per l'Amazon VPC contenente il tuo cluster con le seguenti regole (come minimo):

  • Regole in entrata: consenti tutto il traffico sulla porta del cluster Amazon DocumentDB per i gruppi di sicurezza specificati per l'origine dell'evento. Amazon DocumentDB utilizza la porta 27017 per impostazione predefinita.

  • Regole in uscita: consenti tutto il traffico sulla porta 443 per tutte le destinazioni. Consenti tutto il traffico sulla porta del cluster Amazon DocumentDB. Amazon DocumentDB utilizza la porta 27017 per impostazione predefinita.

  • Se si utilizzano endpoint VPC anziché gateway NAT, i gruppi di sicurezza associati agli endpoint VPC devono consentire tutto il traffico in entrata sulla porta 443 dai gruppi di sicurezza dell'origine eventi.

Uso di endpoint VPC

Quando utilizzi gli endpoint VPC, le chiamate API per richiamare la tua funzione vengono instradate attraverso questi endpoint utilizzando gli ENI. Il principale del servizio Lambda deve richiamare tutte lambda:InvokeFunction le funzioni che utilizzano tali ENI.

Per impostazione predefinita, gli endpoint VPC dispongono di policy IAM aperte. La migliore pratica consiste nel limitare queste policy per consentire solo a soggetti specifici di eseguire le azioni necessarie utilizzando quell'endpoint. Per garantire che la mappatura delle sorgenti degli eventi sia in grado di richiamare la funzione Lambda, la policy degli endpoint VPC deve consentire la chiamata al principio del servizio Lambda. lambda:InvokeFunction Limitare le policy degli endpoint VPC per consentire solo le chiamate API provenienti dall'organizzazione impedisce il corretto funzionamento della mappatura delle sorgenti degli eventi.

Il seguente esempio di policy degli endpoint VPC mostra come concedere l'accesso richiesto per gli endpoint Lambda.

Esempio Politica degli endpoint VPC - Endpoint Lambda
{
    "Statement": [
        {
            "Action": "lambda:InvokeFunction",
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "lambda.amazonaws.com"
                ]
            },
            "Resource": "*"
        }
    ]
}

Se il tuo cluster Amazon DocumentDB utilizza l'autenticazione, puoi anche limitare la policy degli endpoint VPC per l'endpoint Secrets Manager. Per chiamare l'API Secrets Manager, Lambda utilizza il ruolo della funzione, non il responsabile del servizio Lambda. L'esempio seguente mostra una policy per gli endpoint di Secrets Manager.

Esempio Politica degli endpoint VPC - Endpoint Secrets Manager
{
    "Statement": [
        {
            "Action": "secretsmanager:GetSecretValue",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "customer_function_execution_role_arn"
                ]
            },
            "Resource": "customer_secret_arn"
        }
    ]
}

Creazione di una mappatura dell'origine degli eventi Amazon DocumentDB (console)

Per configurare una funzione Lambda per la lettura dal flusso di modifica di un cluster Amazon DocumentDB, crea una mappatura dell'origine degli eventi. In questa sezione viene descritto come eseguire questa operazione dalla console Lambda. Per AWS SDK e AWS CLI istruzioni, consulta. Creazione di una mappatura dell'origine degli eventi Amazon DocumentDB (SDK o CLI)

Creazione di una mappatura dell'origine degli eventi per Amazon DocumentDB (console)

  1. Aprire la pagina Functions (Funzioni) della console Lambda.

  2. Scegliere il nome della funzione.

  3. In Function overview (Panoramica delle funzioni), scegliere Add trigger (Aggiungi trigger).

  4. In Configurazione del trigger, nell'elenco a discesa, scegli DocumentDB.

  5. Configurare le opzioni richieste, quindi scegliere Add (Aggiungi).

Lambda supporta le seguenti opzioni per le origini degli eventi Amazon DocumentDB:

  • Cluster DocumentDB: seleziona un cluster Amazon DocumentDB.

  • Attiva il trigger: seleziona l'opzione se vuoi attivare il trigger immediatamente. Se selezioni questa casella, la funzione inizia immediatamente a ricevere traffico dal flusso di modifica specificato di Amazon DocumentDB al momento della creazione della mappatura dell'origine degli eventi. Ai fini del test, è preferibile deselezionare la casella in modo da creare una mappatura dell'origine degli eventi non attiva. Dopo la creazione, puoi attivare lo strumento di mappatura dell'origine degli eventi in qualsiasi momento.

  • Nome database: immetti il nome di un database da utilizzare nel cluster.

  • (Facoltativo) Nome della raccolta: immetti il nome di una raccolta da utilizzare nel database. Se non specifichi una raccolta, Lambda ascolta tutti gli eventi di ciascuna raccolta del database.

  • Dimensioni batch: imposta, fino a 10.000, il numero massimo di messaggi da recuperare in un singolo batch. La dimensione predefinita del batch è pari a 100.

  • Posizione iniziale: scegli la posizione del flusso da cui iniziare a leggere i record.

    • Ultimi: elabora solo i nuovi record aggiunti al flusso. La funzione inizia a elaborare i record solo dopo che Lambda ha terminato la creazione dell'origine degli eventi. Ciò significa che alcuni record potrebbero essere tralasciati fino a quando l'origine degli eventi non viene creata correttamente.

    • Trim Horizon (Orizzonte di taglio): elabora tutti i record contenuti nel flusso. Lambda utilizza la durata di conservazione dei log del tuo cluster per stabilire da dove iniziare a leggere gli eventi. In particolare Lambda inizia a leggere da current_time - log_retention_duration. Il flusso di modifica deve essere già attivo prima di questo timestamp affinché Lambda legga tutti gli eventi correttamente.

    • At timestamp (Al timestamp): elaborare record a partire da una determinata ora. Il flusso di modifica deve essere già attivo prima del timestamp specificato affinché Lambda legga tutti gli eventi correttamente.

  • .Autenticazione: scegli il metodo di autenticazione per l'accesso dei broker al cluster.

    • BASIC_AUTH: con l'autenticazione di base è necessario fornire la chiave Secrets Manager che contiene le credenziali per accedere al cluster.

  • Chiave Secrets Manager: scegli la chiave Secrets Manager che contiene i dettagli di autenticazione (nome utente e password) necessari per accedere al cluster Amazon DocumentDB.

  • (Facoltativo) Finestra batch: specifica il tempo massimo, espresso in secondi fino a un massimo di 300, per la raccolta dei record prima che la funzione venga richiamata.

  • (Facoltativo) Configurazione completa del documento: per le operazioni di aggiornamento del documento, scegli che cosa inviare al flusso. Il valore predefinito è Default, il che significa che Amazon DocumentDB invia solo un delta che descrive le modifiche apportate per ogni evento del flusso di modifica. Per ulteriori informazioni su questo campo, consulta la documentazione dell'FullDocumentAPI Javadoc di MongoDB.

    • Impostazione predefinita: Lambda invia solo un documento parziale che descrive le modifiche apportate.

    • UpdateLookup— Lambda invia un delta che descrive le modifiche, insieme a una copia dell'intero documento.

Creazione di una mappatura dell'origine degli eventi Amazon DocumentDB (SDK o CLI)

Per creare o gestire una mappatura dell'origine degli eventi Amazon DocumentDB tramite un SDK AWS, puoi utilizzare le seguenti operazioni dell'API:

Per creare la mappatura della sorgente degli eventi con AWS CLI, usa il comando. create-event-source-mapping L'esempio seguente utilizza questo comando per mappare una funzione denominata my-function a un flusso di modifica Amazon DocumentDB. L'origine degli eventi è indicata da un nome della risorsa Amazon (ARN), con una dimensione batch di 500, a partire dal timestamp in formato Unix. Il comando specifica anche la chiave Secrets Manager che Lambda utilizza per connettersi ad Amazon DocumentDB. Inoltre, include document-db-event-source-config parametri che specificano il database e la raccolta da cui leggere.

aws lambda create-event-source-mapping --function-name my-function \
    --event-source-arn arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy
    --batch-size 500 \
    --starting-position AT_TIMESTAMP \
    --starting-position-timestamp 1541139109 \
    --source-access-configurations '[{"Type":"BASIC_AUTH","URI":"arn:aws:secretsmanager:us-east-1:123456789012:secret:DocDBSecret-BAtjxi"}]' \
    --document-db-event-source-config '{"DatabaseName":"test_database", "CollectionName": "test_collection"}' \

L'output visualizzato dovrebbe essere di questo tipo:

{
    "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
    "BatchSize": 500,
    "DocumentDBEventSourceConfig": {
        "CollectionName": "test_collection",
        "DatabaseName": "test_database",
        "FullDocument": "Default"
    },
    "MaximumBatchingWindowInSeconds": 0,
    "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy",
    "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
    "LastModified": 1541348195.412,
    "LastProcessingResult": "No records processed",
    "State": "Creating",
    "StateTransitionReason": "User action"
}

Dopo la creazione, puoi utilizzare il comando update-event-source-mapping per modificare le impostazioni di aggiornamento relative all'origine degli eventi di Amazon DocumentDB. Nell'esempio seguente, la dimensione del batch viene aggiornata a 1.000 e la finestra batch a 10 secondi. Per questo comando è necessario l'UUID della mappatura dell'origine degli eventi, recuperabile utilizzando il comando list-event-source-mapping o dalla console Lambda.

aws lambda update-event-source-mapping --function-name my-function \
    --uuid f89f8514-cdd9-4602-9e1f-01a5b77d449b \
    --batch-size 1000 \
    --batch-window 10

L'output visualizzato dovrebbe essere di questo tipo:

{
    "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
    "BatchSize": 500,
    "DocumentDBEventSourceConfig": {
        "CollectionName": "test_collection",
        "DatabaseName": "test_database",
        "FullDocument": "Default"
    },
    "MaximumBatchingWindowInSeconds": 0,
    "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy",
    "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
    "LastModified": 1541359182.919,
    "LastProcessingResult": "OK",
    "State": "Updating",
    "StateTransitionReason": "User action"
}

Lambda aggiorna le impostazioni in modo asincrono, pertanto potresti non essere in grado di visualizzare queste modifiche nell'output fino al completamento del processo. Per visualizzare le impostazioni correnti della mappatura dell'origine degli eventi, utilizza il comando get-event-source-mapping.

aws lambda get-event-source-mapping --uuid f89f8514-cdd9-4602-9e1f-01a5b77d449b

L'output visualizzato dovrebbe essere di questo tipo:

{
    "UUID": "2b733gdc-8ac3-cdf5-af3a-1827b3b11284",
    "DocumentDBEventSourceConfig": {
        "CollectionName": "test_collection",
        "DatabaseName": "test_database",
        "FullDocument": "Default"
    },
    "BatchSize": 1000,
    "MaximumBatchingWindowInSeconds": 10,
    "EventSourceArn": "arn:aws:rds:us-west-2:123456789012:cluster:privatecluster7de2-epzcyvu4pjoy",
    "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
    "LastModified": 1541359182.919,
    "LastProcessingResult": "OK",
    "State": "Enabled",
    "StateTransitionReason": "User action"
}

Per eliminare la mappatura dell'origine degli eventi di Amazon DocumentDB, utilizza il comando delete-event-source-mapping:

aws lambda delete-event-source-mapping \
    --uuid 2b733gdc-8ac3-cdf5-af3a-1827b3b11284

Posizioni di partenza di polling e flussi

Tieni presente che il polling dei flussi durante la creazione e gli aggiornamenti dello strumento di mappatura dell’origine degli eventi alla fine è coerente.

  • Durante la creazione dello strumento di mappatura dell'origine degli eventi, potrebbero essere necessari alcuni minuti per l'avvio degli eventi di polling dal flusso.

  • Durante gli aggiornamenti dello strumento di mappatura dell'origine degli eventi, potrebbero essere necessari alcuni minuti per l'avvio degli eventi di polling dal flusso.

Questo comportamento implica che se specifichi LATEST come posizione iniziale del flusso, lo strumento di mappatura dell'origine degli eventi potrebbe perdere eventi durante la creazione o gli aggiornamenti. Per non perdere alcun evento, specifica la posizione iniziale del flusso come TRIM_HORIZON o AT_TIMESTAMP.

Monitoraggio dell'origine degli eventi di Amazon DocumentDB

Per aiutarti a monitorare l'origine degli eventi Amazon DocumentDB, Lambda emette il parametro IteratorAge quando la funzione termina l'elaborazione di un batch di record. L'età dell'iteratore è la differenza tra il timestamp dell'evento più recente e il timestamp corrente. Sostanzialmente, il parametro IteratorAge indica l'età dell'ultimo record elaborato nel batch. Se la funzione continua a elaborare nuovi eventi, puoi utilizzare la cronologia di iterazione per stimare la latenza tra il momento in cui un record viene aggiunto e il momento in cui viene elaborato dalla tua funzione. Una tendenza in aumento in IteratorAge può indicare problemi con la funzione. Per ulteriori informazioni, consulta Utilizzo dei parametri delle funzioni Lambda.

I flussi di modifiche di Amazon DocumentDB non sono ottimizzati per gestire ampi intervalli di tempo tra gli eventi. Se la fonte di eventi Amazon DocumentDB non riceve alcun evento per un periodo di tempo prolungato, Lambda può disabilitare la mappatura delle sorgenti degli eventi. La durata di questo periodo di tempo può variare da alcune settimane a qualche mese a seconda delle dimensioni del cluster e di altri carichi di lavoro.

Lambda supporta payload di dimensioni massime di 6 MB. Tuttavia, gli eventi del flusso di modifica di Amazon DocumentDB possono avere dimensioni fino a 16 MB. Se il flusso di modifica tenta di inviare a Lambda un evento di flusso di modifica di dimensioni superiori a 6 MB, Lambda tralascia il messaggio ed emette il parametro OversizedRecordCount. Lambda emette tutti i parametri sulla base del miglior tentativo.