Exemple d'événement Amazon DocumentDB Conditions préalables et autorisations Configuration réseau Création d'un mappage des sources d'événements Amazon DocumentDB (console)Création d'un mappage des sources d'événements Amazon DocumentDB (kit SDK ou CLI)Positions de départ des interrogations et des flux Surveillance de votre source d'événements Amazon DocumentDB

Utilisation de Lambda avec Amazon DocumentDB

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.

Note

Lambda prend en charge uniquement les versions 4.0 et 5.0 d'Amazon DocumentDB. Lambda ne prend pas en charge la version 3.6.

De plus, pour les mappages des sources d'événements, Lambda ne prend en charge que les clusters basés sur des instances et les clusters régionaux. Lambda ne prend pas en charge les clusters élastiques ni les clusters globaux. Cette limitation ne s'applique pas lorsque vous utilisez Lambda en tant que client pour vous connecter à Amazon DocumentDB. Lambda peut se connecter à tous les types de clusters pour effectuer des opérations CRUD.

Lambda traite les événements des flux de modifications Amazon DocumentDB de manière séquentielle dans l'ordre de leur arrivée. Pour cette raison, votre fonction ne peut gérer qu'une seule invocation simultanée de DocumentDB à la fois. Pour surveiller votre fonction, vous pouvez suivre ses métriques de simultanéité.

Avertissement

Les mappages de sources d'événements Lambda traitent chaque événement au moins une fois, et le traitement des enregistrements peut être dupliqué. Pour éviter les problèmes potentiels liés à des événements dupliqués, nous vous recommandons vivement de rendre votre code de fonction idempotent. Pour en savoir plus, consultez Comment rendre ma fonction Lambda idempotente dans le Knowledge Center. AWS

Rubriques

Exemple d'événement Amazon DocumentDB
Conditions préalables et autorisations
Configuration réseau
Création d'un mappage des sources d'événements Amazon DocumentDB (console)
Création d'un mappage des sources d'événements Amazon DocumentDB (kit SDK ou CLI)
Positions de départ des interrogations et des flux
Surveillance de votre source d'événements Amazon DocumentDB
Tutoriel : utilisation d'AWS Lambda avec Amazon DocumentDB Streams

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 :

Disposez d'un cluster Amazon DocumentDB existant au même endroit Région AWS que votre fonction Compte AWS et en tant que tel. Si vous n'avez pas de cluster existant, vous pouvez en créer un en suivant les étapes de la section Prise en main d'Amazon DocumentDB dans le Guide du développeur Amazon DocumentDB. Sinon, la première série d'étapes de Tutoriel : utilisation d'AWS Lambda avec Amazon DocumentDB Streams vous guide dans la création d'un cluster DocumentDB avec tous les prérequis nécessaires.
Autorisez Lambda à accéder aux ressources Amazon Virtual Private Cloud (Amazon VPC) associées à votre cluster Amazon DocumentDB. Pour plus d’informations, consultez Configuration réseau.
Activez le protocole TLS sur votre cluster Amazon DocumentDB. Il s’agit du paramètre par défaut. Si vous désactivez le protocole TLS, Lambda ne peut pas communiquer avec votre cluster.
Activez les flux de modifications sur votre cluster Amazon DocumentDB. Pour plus d'informations, veuillez consulter la rubrique Utilisation des flux de modifications avec Amazon DocumentDB dans le Guide du développeur Amazon DocumentDB.
Fournissez à Lambda les informations d'identification pour accéder à votre cluster Amazon DocumentDB. Lors de la configuration de la source d'événement, fournissez la clé AWS Secrets Manager qui contient les informations d'authentification (nom d'utilisateur et mot de passe) requises pour accéder à votre cluster. Pour fournir cette clé lors de la configuration, procédez de l'une des manières suivantes :
- Si vous utilisez la console Lambda pour la configuration, saisissez cette clé dans le champ Clé du gestionnaire de secrets.
- Si vous utilisez le AWS Command Line Interface (AWS CLI) pour la configuration, fournissez cette clé dans l'source-access-configurationsoption. Vous pouvez inclure cette option avec la commande create-event-source-mapping ou la commande update-event-source-mapping. Par exemple :
```
aws lambda create-event-source-mapping \
    ...
    --source-access-configurations  '[{"Type":"BASIC_AUTH","URI":"arn:aws:secretsmanager:us-west-2:123456789012:secret:DocDBSecret-AbC4E6"}]' \
    ...
```
Accordez des autorisations à Lambda pour gérer les ressources liées à votre flux Amazon DocumentDB. Ajoutez manuellement les autorisations suivantes au rôle d'exécution de votre fonction :
La taille des événements de flux de modifications Amazon DocumentDB que vous envoyez à Lambda doit être inférieure à 6 Mo. Lambda prend en charge des charges utiles d'une taille maximale de 6 Mo. Si votre flux de modifications essaie d'envoyer à Lambda un événement supérieur à 6 Mo, Lambda supprime le message et émet la métrique OversizedRecordCount. Lambda émet toutes les métriques dans la mesure du possible.

Note

Alors que les fonctions Lambda ont généralement un délai d'expiration maximal de 15 minutes, les mappages des sources d'événement pour Amazon MSK, Apache Kafka autogéré, Amazon DocumentDB et Amazon MQ pour ActiveMQ et RabbitMQ ne prennent en charge que les fonctions dont le délai d'expiration maximal est de 14 minutes. Cette contrainte garantit que le mappage des sources d’événements peut gérer correctement les erreurs de fonction et effectuer de nouvelles tentatives.

Configuration réseau

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

Sinon, assurez-vous que le VPC associé à votre cluster Amazon DocumentDB comprend une passerelle NAT par sous-réseau public. Pour plus d’informations, consultez Activer l'accès à Internet pour les fonctions Lambda connectées au VPC.

Si vous utilisez des points de terminaison VPC, vous devez également les configurer pour activer les noms DNS 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 (ENI) sont déjà présentes pour les sous-réseaux et les groupes de sécurité du VPC de votre cluster. Si Lambda trouve des ENI existants, il tente de les réutiliser. Sinon, Lambda crée de nouveaux ENI pour se connecter à la source de l'événement et appeler votre fonction.

Note

Les fonctions Lambda s'exécutent toujours dans des VPC appartenant au service Lambda. Ces VPC sont gérés automatiquement par le service et ne sont pas visibles pour les clients. Vous pouvez également connecter votre fonction à un Amazon VPC. Dans les deux cas, la configuration VPC de votre fonction n'affecte pas le mappage des sources d'événements. Seule la configuration du VPC de la source d'événements détermine la manière dont Lambda se connecte à votre source d'événements.

Règles du groupe de sécurité VPC

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

Règles de trafic entrant : autorisez tout le trafic sur le port du cluster Amazon DocumentDB pour les groupes de sécurité spécifiés pour votre source d'événement. Amazon DocumentDB utilise le port 27017 par défaut.
Règles sortantes : autorisent tout le trafic sur le port 443 pour toutes les destinations. Autorisez tout le trafic sur le port du cluster Amazon DocumentDB. Amazon DocumentDB utilise le port 27017 par défaut.
Si vous utilisez des points de terminaison d’un VPC au lieu de la passerelle NAT, les groupes de sécurité associés aux points de terminaison du VPC doivent autoriser tout le trafic entrant sur le port 443 à partir des groupes de sécurité des sources d’événement.

Utilisation des points de terminaison d'un VPC

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

Par défaut, les points de terminaison VPC ont des politiques IAM 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 de point de terminaison VPC doit autoriser le principe du service Lambda à appeler. lambda:InvokeFunction Le fait de restreindre vos politiques de point de terminaison VPC pour n'autoriser que les appels d'API provenant de votre organisation empêche le mappage des sources d'événements de fonctionner correctement.

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

Exemple Politique de point de terminaison VPC - Point 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 terminaison VPC pour le point de terminaison Secrets Manager. Pour appeler l'API Secrets Manager, Lambda utilise votre rôle de fonction, et non le principal du service Lambda. L'exemple suivant montre une politique de point de terminaison de Secrets Manager.

Exemple Politique relative aux points de terminaison VPC - Point de terminaison 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 le AWS SDK et les AWS CLI instructions, voirCréation d'un mappage des sources d'événements Amazon DocumentDB (kit SDK ou CLI).

Pour créer un mappage des sources d'événements Amazon DocumentDB (console)

Ouvrez la page Functions (Fonctions) de la console Lambda.
Choisissez le nom d’une fonction.
Sous Function overview (Présentation de la fonction), choisissez Add trigger (Ajouter un déclencheur).
Sous Configuration du déclencheur, dans la liste déroulante, choisissez DocumentDB.
Configurez les options requises, puis choisissez Add (Ajouter).

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

Cluster DocumentDB : sélectionnez un cluster Amazon DocumentDB.
Activer le déclencheur : choisissez si vous voulez activer le déclencheur maintenant. Si vous cochez cette case, votre fonction commence immédiatement à recevoir du trafic provenant du flux de modifications Amazon DocumentDB spécifié lors de la création du mappage des sources d'événements. Nous vous recommandons de décocher la case pour créer le mappage des sources d'événements dans un état désactivé à des fins de test. Après la création, vous pouvez activer le mappage des sources d'événements à tout moment.
Nom de la base de données – Saisissez le nom de la base de données du cluster à utiliser.
(Facultatif) Nom de la collection : saisissez le nom d'une collection de la base de données à utiliser. Si vous n'indiquez pas de collection, Lambda écoute tous les événements de chaque collection de la base de données.
Taille de lot – Définissez le nombre maximum de messages à extraire dans un lot, jusqu'à 10 000. La taille du lot par défaut est de 100.
Position de départ – Choisissez la position dans le flux à partir de laquelle commencer la lecture des enregistrements.
- Derniers – Traiter uniquement les nouveaux enregistrements qui sont ajoutés au flux. Votre fonction ne commence à traiter les enregistrements que lorsque Lambda a fini de créer votre source d'événements. Cela signifie que certains enregistrements peuvent être supprimés jusqu'à ce que la source de votre événement soit correctement créée.
- Trim horizon (Supprimer l’horizon) – Traiter tous les enregistrements figurant dans le flux. Lambda utilise la durée de conservation des journaux de votre cluster pour déterminer par où commencer la lecture des événements. Plus précisément, Lambda commence à lire à partir de current_time - log_retention_duration. Votre flux de modifications doit déjà être actif avant cet horodatage pour que Lambda puisse lire correctement tous les événements.
- At timestamp (À l’horodatage) – Traitez les enregistrements à partir d’une heure spécifique. Votre flux de modifications doit déjà être actif avant l'horodatage spécifié pour que Lambda puisse lire correctement tous les événements.
Authentication – Choisissez la méthode d'authentification pour accéder aux agents de votre cluster.
- BASIC_AUTH – Avec l'authentification de base, vous devez fournir la clé Secrets Manager qui contient les informations d'identification pour accéder à votre cluster.
Clé Secrets Manager : choisissez la clé Secrets Manager qui contient les informations d'authentification (nom d'utilisateur et mot de passe) requises pour accéder à votre cluster Amazon DocumentDB.
(Facultatif) Fenêtre de traitement par lot : définissez l'intervalle de temps maximum (en secondes) pour collecter des enregistrements avant d'invoquer votre fonction, jusqu'à 300.
(Facultatif) Configuration complète du document : pour les opérations de mise à jour des documents, choisissez ce que vous voulez envoyer au flux. La valeur par défaut est Default, ce qui signifie que pour chaque événement de flux de modifications, Amazon DocumentDB envoie uniquement un delta décrivant les modifications apportées. Pour plus d'informations sur ce champ, consultez la documentation FullDocumentde l'API MongoDB Javadoc.
- Par défaut – Lambda n'envoie qu'un document partiel décrivant les modifications apportées.
- UpdateLookup— Lambda envoie un delta décrivant les modifications, ainsi qu'une copie de l'intégralité du document.

Création d'un mappage des sources d'événements Amazon DocumentDB (kit SDK ou CLI)

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

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 d'é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 de l'UUID de votre mappage des sources d'événements, que vous pouvez récupérer à l'aide de la commande list-event-source-mapping 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.

Lors de la création du mappage des sources d’événements, le démarrage de l’interrogation des événements depuis le flux peut prendre plusieurs minutes.
Lors des mises à jour du mappage des sources d’événements, l’arrêt et le redémarrage de l’interrogation des événements depuis le flux peuvent prendre plusieurs minutes.

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 plus d’informations, consultez Utilisation des métriques de fonction 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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Connexion

Didacticiel