Mappage de source d’événement Lambda - AWS Lambda

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Mappage de source d’événement Lambda

Note

Si vous souhaitez envoyer des données à une cible autre qu'une fonction Lambda ou enrichir les données avant de les envoyer, consultez Amazon EventBridge Pipes.

Un mappage de source d’événement est une ressource Lambda qui lit à partir d’une source d’événement et invoque une fonction Lambda. Vous pouvez utiliser des mappages de source d’événement pour traiter des éléments d’un flux ou d’une file d’attente dans des services qui n’invoquent pas directement des fonctions Lambda. Cette page décrit les services que Lambda fournit pour le mappage des sources d’événements et la manière de régler avec précision le comportement de mise en lots.

Un mappage de source d’événement utilise les autorisations du rôle d’exécution de la fonction pour lire et gérer des éléments dans la source de l’événement. Les autorisations, la structure des événements, les paramètres et le comportement d’interrogation varient selon la source de l’événement. Pour en savoir plus, consultez la rubrique liée pour le service que vous utilisez en tant que source d’événement.

Pour gérer une source d’événement à l’aide de la AWS Command Line Interface (AWS CLI) ou d’un SDKAWS, vous pouvez utiliser les opérations d’API suivantes :

Vous pouvez également créer un mappage de source d'événements à l'aide de la console Lambda ou du AWS Serverless Application Model ()AWS SAM. Pour plus d’informations, consultez Invocation de fonctions Lambda depuis un flux ou une file d'attente.

Note

Lorsque vous mettez à jour, désactivez ou supprimez un mappage des sources d’événements pour Amazon MQ, Amazon MSK, Apache Kafka autogéré ou Amazon DocumentDB, la prise en compte de vos modifications peut prendre jusqu’à 15 minutes. Avant la fin de cette période, votre mappage des sources d’événements peut continuer à traiter les événements et à invoquer votre fonction à l’aide de vos paramètres précédents. Cela est vrai même lorsque l’état du mappage des sources d’événements affiché dans la console indique que vos modifications ont été appliquées.

L’exemple suivant utilise la AWS CLI pour mapper une fonction nommée my-function à un flux DynamoDB spécifiée par son Amazon Resource Name (ARN), avec une taille de lot de 500.

aws lambda create-event-source-mapping --function-name my-function --batch-size 500 --maximum-batching-window-in-seconds 5 --starting-position LATEST \ --event-source-arn arn:aws:dynamodb:us-east-2:123456789012:table/my-table/stream/2023-06-10T19:26:16.525

Vous devriez voir la sortie suivante :

{ "UUID": "14e0db71-5d35-4eb5-b481-8945cf9d10c2", "BatchSize": 500, "MaximumBatchingWindowInSeconds": 5, "ParallelizationFactor": 1, "EventSourceArn": "arn:aws:dynamodb:us-east-2:123456789012:table/my-table/stream/2019-06-10T19:26:16.525", "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function", "LastModified": 1560209851.963, "LastProcessingResult": "No records processed", "State": "Creating", "StateTransitionReason": "User action", "DestinationConfig": {}, "MaximumRecordAgeInSeconds": 604800, "BisectBatchOnFunctionError": false, "MaximumRetryAttempts": 10000 }
Avertissement

Les mappages de sources d'événements Lambda traitent chaque événement au moins une fois et le traitement par lots peut se produire en double. 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

Comportement de traitement par lots

Les mappages de source d’événements lisent les éléments d’une source d’événement cible. Par défaut, un mappage de source d’événements regroupe des enregistrements dans une même charge utile que Lambda envoie à votre fonction. Pour affiner le comportement du traitement par lots, vous pouvez configurer une fenêtre de traitement par lots (MaximumBatchingWindowInSeconds) et une taille de lot (BatchSize). Une fenêtre de traitement par lots représente l’intervalle de temps maximal pour collecter des enregistrements dans une même charge utile. La taille d’un lot est le nombre maximal d’enregistrements dans un même lot. Lambda invoque votre fonction en présence de l’un des trois critères suivants :

  • La fenêtre de traitement par lots atteint sa valeur maximale. Le comportement de la fenêtre de traitement par lots varie selon la source d’événement spécifique.

    • Pour les sources d’événements Kinesis, DynamoDB et Amazon SQS : la fenêtre de traitement par lot par défaut est de 0 seconde. Cela signifie que Lambda envoie des lots à votre fonction le plus rapidement possible. Si vous configurez un MaximumBatchingWindowInSeconds, la fenêtre de traitement par lots suivante commence dès que l’invocation de fonction précédente est terminée.

    • Pour les sources d’événements Amazon MSK, Apache Kafka autogérées, Amazon MQ et Amazon DocumentDB : la fenêtre de traitement par lots par défaut est de 500 ms. Vous pouvez configurer MaximumBatchingWindowInSeconds à n’importe quelle valeur comprise entre 0 et 300 secondes par incréments de secondes. Une fenêtre de traitement par lots commence dès l’arrivée du premier registre.

      Note

      Parce que vous ne pouvez que changer MaximumBatchingWindowInSeconds par incréments de secondes, vous ne pouvez pas revenir à la fenêtre de traitement par lots par défaut de 500 ms après l’avoir modifiée. Pour restaurer la fenêtre de traitement par lots par défaut, vous devez créer un mappage de source d’événement.

  • La taille du lot est atteinte. La taille minimale du lot est de 1. La taille par défaut et la taille maximale du lot dépendent de la source d’événement. Pour plus d’informations sur ces valeurs, consultez la spécification BatchSize pour l’opération de l’API CreateEventSourceMapping.

  • La taille de la charge utile atteint 6 Mo. Vous ne pouvez pas modifier cette limite.

Le diagramme suivant illustre ces trois conditions. Supposons qu’une fenêtre de traitement par lots commence à t = 7 secondes. Dans le premier scénario, la fenêtre de traitement par lots atteint son maximum de 40 secondes à t = 47 secondes après avoir accumulé 5 enregistrements. Dans le second scénario, la taille du lot atteint 10 avant l’expiration de la fenêtre de traitement par lots, de sorte que la fenêtre de traitement par lots se termine plus tôt. Dans le troisième scénario, la taille maximale de la charge utile est atteinte avant l’expiration de la fenêtre de traitement par lots, de sorte que la fenêtre de traitement par lots se termine plus tôt.


        Une fenêtre de traitement par lots expire lorsque l’un des trois critères suivants est satisfait : la fenêtre de traitement par lots atteint sa valeur maximale, la taille du lot est satisfaite ou la taille de la charge utile atteint 6 Mo.

L’exemple suivant montre un mappage de source d’événement qui effectue une lecture à partir d’un flux Kinesis. Si un lot d’événements échoue à toutes les tentatives de traitement, le mappage de source d’événement envoie les détails du lot à une file d’attente SQS.


        Un mappage de source d’événement est lu à partir d’un flux Kinesis. Il met en file d’attente les enregistrements localement avant de les envoyer à la fonction.

Le lot d’événements correspond à l’événement que Lambda envoie à la fonction. Il s’agit d’un lot de registres ou de messages compilés à partir des éléments que le mappage de source d’événement lit jusqu’à l’expiration de la fenêtre de lot actuelle.

Pour les flux Kinesis et DynamoDB, un mappage des sources d’événements crée un itérateur pour chaque partition dans le flux et traite les éléments dans chaque partition dans l’ordre. Vous pouvez configurer le mappage de source d’événement pour lire uniquement les nouveaux éléments qui apparaissent dans le flux, ou pour démarrer avec des éléments plus anciens. Les éléments traités ne sont pas supprimés du flux et peuvent être traités par d’autres fonctions ou d’autres consommateurs.

Lambda envoi le prochain lot pour traitement sans attendre que les Extensions Lambda configurées soient terminées. En d’autres termes, vos extensions peuvent continuer à s’exécuter pendant que Lambda traite le prochain lot d’enregistrements. Cela peut causer des problèmes de limitation si vous enfreignez l’un des paramètres ou l’une des limites de simultanéité de votre compte. Pour détecter s’il s’agit d’un problème éventuel, surveillez vos fonctions et vérifiez si vous observez des métriques de simultanéité plus élevées que prévu pour votre mappage des sources d’événements. En raison de la brièveté des intervalles entre les invocations, Lambda peut brièvement signaler une utilisation simultanée supérieure au nombre de partitions. Cela peut être vrai même pour les fonctions Lambda sans extensions.

Par défaut, si votre fonction renvoie une erreur, le mappage de la source d’événements retraite l’ensemble du lot jusqu’à ce que la fonction réussisse ou que les éléments du lot arrivent à expiration. Pour s’assurer d’un traitement dans l’ordre, le mappage de la source d’événement met en pause le traitement dans la partition concernée jusqu’à la résolution de l’erreur. Vous pouvez configurer le mappage des sources d’événements pour ignorer les anciens événements ou traiter plusieurs lots en parallèle. Si vous traitez plusieurs lots en parallèle, le traitement dans l’ordre est toujours garanti pour chaque clé de partition, mais le mappage de la source d’événement traite simultanément plusieurs clés de partition dans la même partition.

Pour les sources de flux (DynamoDB et Kinesis), vous pouvez configurer le nombre maximal de tentatives que Lambda effectue lorsque votre fonction renvoie une erreur. Les erreurs de service ou les limitations où le lot n’atteint pas votre fonction ne comptent pas dans les tentatives de réessai.

Vous pouvez également configurer le mappage de source d’événement pour envoyer un enregistrement d’invocation à un autre service lorsqu’il rejette un lot d’événements. Lambda prend en charge les destinations suivantes pour les mappages de source d’événement.

  • Amazon SQS – File d’attente SQS.

  • Amazon SNS – Rubrique SNS.

L’enregistrement d’invocation contient des détails sur le lot d’événements ayant échoué au format JSON.

L’exemple suivant illustre un enregistrement d’invocation pour un flux Kinesis.

Exemple enregistrement d’invocation
{ "requestContext": { "requestId": "c9b8fa9f-5a7f-xmpl-af9c-0c604cde93a5", "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myfunction", "condition": "RetryAttemptsExhausted", "approximateInvokeCount": 1 }, "responseContext": { "statusCode": 200, "executedVersion": "$LATEST", "functionError": "Unhandled" }, "version": "1.0", "timestamp": "2019-11-14T00:38:06.021Z", "KinesisBatchInfo": { "shardId": "shardId-000000000001", "startSequenceNumber": "49601189658422359378836298521827638475320189012309704722", "endSequenceNumber": "49601189658422359378836298522902373528957594348623495186", "approximateArrivalOfFirstRecord": "2019-11-14T00:38:04.835Z", "approximateArrivalOfLastRecord": "2019-11-14T00:38:05.580Z", "batchSize": 500, "streamArn": "arn:aws:kinesis:us-east-2:123456789012:stream/mystream" } }

Lambda prend également en charge le traitement dans l’ordre pour les files d’attente FIFO (premier entré, premier sorti), en effectuant une augmentation d’échelle en fonction du nombre de groupes de messages actifs. Pour les files d’attente standard, les éléments ne sont pas nécessairement traités dans l’ordre. Lambda adapte son échelle pour traiter une file d’attente standard le plus rapidement possible. Lorsqu’une erreur se produit, Lambda renvoie les lots à la file d’attente en tant qu’éléments individuels et peut les traiter dans un regroupement différent de celui du lot d’origine. Parfois, le mappage de source d’événement peut recevoir deux fois le même élément de la file d’attente, même en l’absence d’erreur de fonction. Lambda supprime de la file d’attente les éléments qui ont été traités avec succès. Vous pouvez configurer la file d’attente source pour envoyer des éléments vers une file d’attente de lettres mortes ou une destination si Lambda ne peut pas les traiter.

Pour en savoir plus sur les services qui invoquent directement des fonctions Lambda, consultez Utilisation de AWS Lambda avec d’autres services.

Configuration des destinations pour les invocations de mappage de sources d’événements

Pour retenir les enregistrements des invocations de mappage de sources d’événements qui ont échoué, ajoutez une destination au mappage des sources d’événements de votre fonction. La configuration des destinations pour les invocations de mappage des sources d’événements est prise en charge uniquement pour les sources d’événements basées sur Kinesis, DynamoDB et Kafka. Chaque enregistrement envoyé à la destination est un document JSON avec des détails sur l’invocation. Comme les paramètres de gestion des erreurs, vous pouvez configurer des destinations au niveau d’une fonction, d’une version de fonction ou d’un alias.

Note

Pour les appels de mappage des sources d’événements, vous pouvez retenir les enregistrements des invocations ayant échoué uniquement. Pour les autres invocations asynchrones, vous pouvez retenir les enregistrements des invocations réussies et échouées. Pour plus d’informations, consultez Configuration des destinations pour les invocations asynchrones.

Vous pouvez configurer n’importe quelle rubrique Amazon SNS ou n’importe quelle file d’attente Amazon SQS comme destination. Pour ces types de destination, Lambda envoie les métadonnées d’enregistrement à la destination. Pour les sources d’événements basées sur Kafka uniquement, vous pouvez également choisir un compartiment Amazon S3 comme destination. Si vous spécifiez un compartiment S3, Lambda envoie l’intégralité de l’enregistrement d’invocation ainsi que les métadonnées à la destination.

Le tableau suivant résume les types de destinations pris en charge pour les invocations de mappage des sources d’événements. Pour que Lambda envoie correctement les enregistrements vers la destination que vous avez choisie, assurez-vous que le rôle d’exécution de votre fonction contient également les autorisations appropriées. Le tableau décrit également comment chaque type de destination reçoit l’enregistrement d’invocation JSON.

Type de destination Pris en charge pour les sources d’événements suivantes Autorisations nécessaires Format JSON spécifique à la destination

File d’attente Amazon SQS

  • Kinesis

  • DynamoDB

  • Apache Kafka autogéré et Apache Kafka géré

Lambda transmet les métadonnées d’enregistrement d’invocation en tant que Message à la destination.

Rubrique Amazon SNS

  • Kinesis

  • DynamoDB

  • Apache Kafka autogéré et Apache Kafka géré

Lambda transmet les métadonnées d’enregistrement d’invocation en tant que Message à la destination.

Compartiment Amazon S3

  • Apache Kafka autogéré et Apache Kafka géré

Lambda stocke l’enregistrement d’invocation ainsi que ses métadonnées à la destination.

L’exemple suivant montre ce que Lambda envoie à une file d’attente SQS ou à une rubrique SNS en cas d’échec de l’invocation d’une source d’événement Kinesis. Comme Lambda envoie uniquement les métadonnées pour ces types de destination, utilisez les champs streamArn, shardId, startSequenceNumber et endSequenceNumber, et pour obtenir l’enregistrement original complet.

{ "requestContext": { "requestId": "c9b8fa9f-5a7f-xmpl-af9c-0c604cde93a5", "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myfunction", "condition": "RetryAttemptsExhausted", "approximateInvokeCount": 1 }, "responseContext": { "statusCode": 200, "executedVersion": "$LATEST", "functionError": "Unhandled" }, "version": "1.0", "timestamp": "2019-11-14T00:38:06.021Z", "KinesisBatchInfo": { "shardId": "shardId-000000000001", "startSequenceNumber": "49601189658422359378836298521827638475320189012309704722", "endSequenceNumber": "49601189658422359378836298522902373528957594348623495186", "approximateArrivalOfFirstRecord": "2019-11-14T00:38:04.835Z", "approximateArrivalOfLastRecord": "2019-11-14T00:38:05.580Z", "batchSize": 500, "streamArn": "arn:aws:kinesis:us-east-2:123456789012:stream/mystream" } }

Pour un exemple de sources d’événements DynamoDB, consultez Gestion des erreurs. Pour un exemple de sources d’événements Kafka, consultez les destinations en cas de défaillance pour Apache Kafka autogéré ou les destinations en cas d’échec pour Amazon MSK.