Traiter les événements Amazon DocumentDB avec Lambda

Vous pouvez utiliser une fonction Lambda pour traiter les événements dans un flux de modifications Amazon DocumentDB (compatible avec MongoDB) en configurant un cluster Amazon DocumentDB comme source d'événements. Ensuite, vous pouvez automatiser les charges de travail orientées événements en invoquant votre fonction Lambda chaque fois que les données changent avec votre cluster Amazon DocumentDB.

Lambda traite les événements des flux de modifications Amazon DocumentDB de manière séquentielle dans l'ordre de leur arrivée. De ce fait, votre fonction ne peut gérer qu'un seul appel simultané depuis Amazon DocumentDB à la fois. Pour surveiller votre fonction, vous pouvez suivre ses métriques de simultanéité.

Exemple d'événement 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"
}

Pour plus d'informations sur les événements de cet exemple et leurs formes, consultez la page Événements de modification sur le site Web de la documentation MongoDB.

Conditions préalables et autorisations

Avant de pouvoir utiliser Amazon DocumentDB comme source d'événements pour votre fonction Lambda, veuillez prendre note des conditions préalables suivantes. Vous devez :

Configuration réseau

Pour que Lambda puisse utiliser votre cluster Amazon DocumentDB comme source d'événements, il doit avoir accès à l'VPCAmazon dans lequel réside votre cluster. Nous vous recommandons de déployer des AWS PrivateLink VPCpoints de terminaison pour que Lambda puisse accéder à votre. VPC Déployez un VPC point de terminaison pour Lambda et, si le cluster utilise l'authentification, déployez également un VPC point de terminaison pour Secrets Manager.

Vous pouvez également vous assurer que le cluster VPC associé à votre cluster Amazon DocumentDB inclut une NAT passerelle par sous-réseau public. Pour de plus amples informations, veuillez consulter Activer l'accès à Internet pour les VPC fonctions Lambda connectées.

Si vous utilisez des VPC points de terminaison, vous devez également les configurer pour activer les DNS noms privés.

Lorsque vous créez un mappage de source d'événements pour un cluster Amazon DocumentDB, Lambda vérifie si des interfaces réseau élastiques (ENIs) sont déjà présentes pour les sous-réseaux et les groupes de sécurité de votre cluster. VPC Si Lambda trouve des objets existantsENIs, il essaie de les réutiliser. Sinon, Lambda en crée un nouveau ENIs pour se connecter à la source de l'événement et appeler votre fonction.

VPCrègles du groupe de sécurité

Configurez les groupes de sécurité pour l'Amazon VPC contenant votre cluster avec les règles suivantes (au minimum) :

Utilisation de points de terminaison VPC

Lorsque vous utilisez des VPC points de terminaison, API les appels pour appeler votre fonction sont acheminés via ces points de terminaison à l'aide du. ENIs Le principal du service Lambda doit faire appel à toutes lambda:InvokeFunction les fonctions qui les utilisent. ENIs

Par défaut, les VPC points de terminaison ont IAM des politiques ouvertes. La meilleure pratique consiste à restreindre ces politiques afin de n'autoriser que des principaux spécifiques à effectuer les actions nécessaires à l'aide de ce point de terminaison. Pour garantir que le mappage de votre source d'événements est en mesure d'appeler votre fonction Lambda, la politique du VPC point de terminaison doit autoriser le principe du service Lambda à appeler. lambda:InvokeFunction Le fait de restreindre les politiques de vos VPC terminaux pour n'autoriser que les API appels provenant de votre organisation empêche le mappage des sources d'événements de fonctionner correctement.

Les exemples de politiques de point de VPC terminaison suivants montrent comment accorder l'accès requis aux points de terminaison Lambda.

{
    "Statement": [
        {
            "Action": "lambda:InvokeFunction",
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "lambda.amazonaws.com"
                ]
            },
            "Resource": "*"
        }
    ]
}

Si votre cluster Amazon DocumentDB utilise l'authentification, vous pouvez également restreindre la politique de point de VPC terminaison pour le point de terminaison Secrets Manager. Pour appeler le Secrets ManagerAPI, Lambda utilise votre rôle fonctionnel, et non le principal du service Lambda. L'exemple suivant montre une politique de point de terminaison de Secrets Manager.

{
    "Statement": [
        {
            "Action": "secretsmanager:GetSecretValue",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "customer_function_execution_role_arn"
                ]
            },
            "Resource": "customer_secret_arn"
        }
    ]
}

Création d'un mappage des sources d'événements Amazon DocumentDB (console)

Pour qu'une fonction Lambda puisse lire le flux de modifications d'un cluster Amazon DocumentDB, créez un mappage des sources d'événements. Cette section explique comment procéder à partir de la console Lambda. Pour les AWS CLI instructions AWS SDK et les instructions, voirCréation d'un mappage de source d'événements Amazon DocumentDB (ou) SDK CLI.

Lambda prend en charge les options suivantes pour les sources d'événement Amazon DocumentDB :

Création d'un mappage de source d'événements Amazon DocumentDB (ou) SDK CLI

Pour créer ou gérer un mappage de source d'événements Amazon DocumentDB avec un AWS SDK, vous pouvez utiliser les opérations suivantes : API

Pour créer le mappage des sources d'événements avec le AWS CLI, utilisez la create-event-source-mappingcommande. L'exemple suivant utilise cette commande pour mapper une fonction nommée my-function à un flux de modifications Amazon DocumentDB. La source de l'événement est spécifiée par un Amazon Resource Name (ARN), avec une taille de lot de 500, à partir de l'horodatage en heure Unix. La commande spécifie également la clé Secrets Manager que Lambda utilise pour se connecter à Amazon DocumentDB. De plus, elle inclut des paramètres document-db-event-source-config qui spécifient la base de données et la collection à partir de laquelle lire.

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

Vous devriez obtenir un résultat du type suivant :

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

Après la création, vous pouvez utiliser la commande update-event-source-mapping pour mettre à jour les paramètres de votre source d'événements Amazon DocumentDB. L'exemple suivant met à jour la taille du lot à 1 000 et la fenêtre de traitement par lots à 10 secondes. Pour cette commande, vous avez besoin du mappage UUID de la source de votre événement, que vous pouvez récupérer à l'aide de la list-event-source-mapping commande ou de la console Lambda.

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

Vous devriez obtenir un résultat du type suivant :

{
    "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 met à jour les paramètres de façon asynchrone, il se peut donc que vous ne voyiez pas ces modifications dans la sortie tant que le processus n'est pas terminé. Pour afficher les paramètres actuels de votre mappage des sources d'événements, utilisez la commande get-event-source-mapping.

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

Vous devriez obtenir un résultat du type suivant :

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

Pour supprimer le mappage des sources d'événements Amazon DocumentDB, utilisez la commande delete-event-source-mapping.

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

Positions de départ des interrogations et des flux

Sachez que l’interrogation des flux lors des mises à jour et de la création du mappage des sources d’événements est finalement cohérente.

Ce comportement signifie que si vous spécifiez LATEST comme position de départ du flux, le mappage des sources d’événements peut manquer des événements lors de la création ou des mises à jour. Pour vous assurer de ne manquer aucun événement, spécifiez la position de départ du flux comme TRIM_HORIZON ou AT_TIMESTAMP.

Surveillance de votre source d'événements Amazon DocumentDB

Pour vous aider à surveiller votre source d'événements Amazon DocumentDB, Lambda émet la métrique IteratorAge lorsque votre fonction termine le traitement d'un lot d'enregistrements. L'âge de l'itérateur est la différence entre l'horodatage de l'événement le plus récent et l'horodatage actuel. La métrique IteratorAge indique essentiellement l'ancienneté du dernier enregistrement traité dans le lot. Si votre fonction traite actuellement de nouveaux événements, vous pouvez utiliser l'âge de l'itérateur pour estimer la latence entre le moment où un enregistrement est ajouté et celui où votre fonction le traite. Une tendance à la hausse de IteratorAge peut indiquer des problèmes liés à votre fonction. Pour de plus amples informations, veuillez consulter Afficher les métriques des fonctions Lambda.

Les flux de modifications d'Amazon DocumentDB ne sont pas optimisés pour gérer les intervalles de temps importants entre les événements. Si votre source d'événements Amazon DocumentDB ne reçoit aucun événement pendant une période prolongée, Lambda peut désactiver le mappage de la source d'événements. La durée de cette période peut varier de quelques semaines à quelques mois en fonction de la taille du cluster et des autres charges de travail.

Lambda prend en charge des charges utiles allant jusqu'à 6 Mo. Cependant, les événements du flux de modification d'Amazon DocumentDB peuvent avoir une taille allant jusqu'à 16 Mo. Si votre flux de modifications tente d'envoyer à Lambda un événement d'une taille supérieure à 6 Mo, Lambda supprime le message et émet la métrique OversizedRecordCount. Lambda émet toutes les métriques dans la mesure du possible.