Appel asynchrone - AWS Lambda
Description de la gestion des appels asynchrones par LambdaConfiguration de la gestion des erreurs pour les appels asynchronesConfiguration des destinations pour les appels asynchronesAPI de configuration d'appel asynchroneFiles d'attente de lettres mortes

Appel asynchrone

Plusieurs services AWS, tels qu'Amazon Simple Storage Service (Amazon S3) et Amazon Simple Notification Service (Amazon SNS), appellent des fonctions de manière asynchrone pour traiter les événements. Lorsque vous appelez une fonction de manière asynchrone, vous n'attendez pas de réponse de la part du code de la fonction. Vous remettez l'événement à Lambda qui se charge du reste. Vous pouvez configurer la façon dont Lambda gère les erreurs, et vous pouvez envoyer des enregistrements d'appel à une ressource en aval telle qu'Amazon Simple Queue Service (Amazon SQS) ou Amazon EventBridge (EventBridge) pour enchaîner les composants de votre application.

Description de la gestion des appels asynchrones par Lambda

Le diagramme suivant montre des clients appelant une fonction Lambda de manière asynchrone. Lambda place les événements en file d'attente avant de les envoyer à la fonction.

Les clients appellent une fonction de manière asynchrone. Lambda place les événements en file d'attente avant de les envoyer à la fonction.

Pour un appel asynchrone, Lambda place l'événement dans une file d'attente et renvoie une réponse de succès sans plus informations. Un processus distinct lit les événements à partir de la file d'attente et les envoie à votre fonction. Pour appeler une fonction de façon asynchrone, définissez le paramètre du type d'appel sur Event.

aws lambda invoke \
  --function-name my-function  \
      --invocation-type Event \
          --cli-binary-format raw-in-base64-out \
              --payload '{ "key": "value" }' response.json

L'option cli-binary-format est obligatoire si vous utilisez AWS CLI version 2. Pour faire de ce paramètre le paramètre par défaut, exécutez aws configure set cli-binary-format raw-in-base64-out. Pour plus d'informations, veuillez consulter les AWS CLI options de ligne de commande.

{
    "StatusCode": 202
}

Le fichier de sortie (response.json) ne contient pas d'informations, mais il est tout de même créé lorsque vous exécutez cette commande. Si Lambda n'est pas en mesure d'ajouter l'événement à la file d'attente, un message d'erreur s'affiche dans la sortie de la commande.

Lambda gère la file d'attente d'événements asynchrones de la fonction, et effectue de nouvelles tentatives en cas d'erreur. Si la fonction renvoie une erreur, Lambda réessaie de l'exécuter à deux reprises, avec une minute d'attente entre les deux premières tentatives, et deux minutes entre la deuxième et la troisième. Les erreurs de fonction comprennent des erreurs renvoyées par le code de la fonction et des erreurs renvoyées par l'environnement d'exécution de la fonction, comme les délais d'expiration.

Si la fonction n'a pas suffisamment de simultanéité disponible pour traiter tous les événements, des demandes supplémentaires sont bloquées. Pour les erreurs de limitation (erreur 429) et les erreurs système (série 500), Lambda renvoie l'événement à la file d'attente et réessaie d'exécuter la fonction pendant jusqu'à 6 heures. L'intervalle de nouvelle tentative augmente de manière exponentielle de 1 seconde après la première tentative jusqu'à un maximum de 5 minutes. Si la file d'attente contient de nombreuses entrées, Lambda augmente l'intervalle entre les tentatives et réduit la fréquence des événements de lecture à partir de la file d'attente.

Même si votre fonction ne renvoie pas d'erreur, elle peut recevoir plusieurs fois le même événement de Lambda, car la file d'attente elle-même est cohérente à terme. Si la fonction ne peut pas à prendre en charge les événements entrants, ils peuvent également être supprimés de la file d'attente sans être envoyés à la fonction. Assurez-vous que le code de votre fonction gère correctement les événements dupliqués et que vous avez suffisamment de simultanéité disponible pour gérer tous les appels.

Lorsque la file d'attente est très longue, il peut arriver que de nouveaux événements expirent avant que Lambda ait la possibilité de les envoyer à votre fonction. Quand un événement expire ou échoue à toutes les tentatives de traitement, Lambda le supprime. Vous pouvez configurer la gestion des erreurs pour une fonction de façon à réduire le nombre de nouvelles tentatives que Lambda effectue, ou à supprimer les événements non traités plus rapidement.

Vous pouvez désormais configurer Lambda pour envoyer un enregistrement d'appel à un autre service. Pour l'appel asynchrone, Lambda prend en charge les destinations suivantes. Notez que les files d'attente FIFO SQS et les rubriques FIFO SNS ne sont pas prises en charge.

  • Amazon SQS – File d'attente SQS standard.

  • Amazon SNS : rubrique SNS standard.

  • AWS Lambda – Fonction Lambda.

  • Amazon EventBridge – Bus d'événements EventBridge.

L'enregistrement d'appel contient des détails sur la demande et la réponse au format JSON. Vous pouvez configurer des destinations distinctes pour les événements qui ont été traités avec succès et ceux dont le traitement a échoué. Vous pouvez également configurer une file d'attente Amazon SQS ou une rubrique Amazon SNS standard en tant que file d'attente de lettres mortes pour les événements abandonnés. Pour les files d'attente de lettres mortes, Lambda envoie uniquement le contenu de l'événement, sans plus d'informations sur la réponse.

Si Lambda ne parvient pas à envoyer un enregistrement à une destination que vous avez configurée, il envoie une métrique DestinationDeliveryFailures à Amazon CloudWatch. Cela peut se produire si votre configuration inclut un type de destination non pris en charge, tel qu'une file d'attente FIFO Amazon SQS ou une rubrique FIFO Amazon SNS. Des erreurs de remise peuvent également se produire en raison d'erreurs d'autorisations et de limites de taille. Pour plus d'informations sur les métriques d'appel Lambda, consultez Métriques d’appel.

Note

Pour empêcher une fonction de se déclencher, vous pouvez définir la simultanéité réservée de la fonction sur zéro. Lorsque vous définissez la simultanéité réservée sur zéro pour une fonction appelée de manière asynchrone, Lambda commence à envoyer les nouveaux événements à la file d'attente de lettres mortes ou à la destination d'événement en situation d'échec, sans aucune nouvelle tentative. Pour traiter les événements qui ont été envoyés alors que la simultanéité réservée était définie sur zéro, vous devez consommer les événements de la file d'attente de lettres mortes ou de la destination des événements en situation d'échec.

Configuration de la gestion des erreurs pour les appels asynchrones

Utilisez la console Lambda pour configurer les paramètres de gestion des erreurs sur une fonction, une version ou un alias.

Pour configurer la gestion des erreurs

  1. Ouvrez la page Functions (Fonctions) de la console Lambda.

  2. Choisissez une fonction.

  3. Sélectionnez Configuration, puis Asynchronous invocation (Appel asynchrone).

  4. Sous Asynchronous invocation (Appel asynchrone), choisissez Edit (Modifier).

  5. 以下を設定します。

    • Maximum age of event (Âge maximal de l'événement) – Durée maximale, jusqu'à 6 heures, pendant laquelle Lambda conserve un événement dans la file d'attente d'événements asynchrones.

    • Retry attempts (Nouvelles tentatives) – Nombre de nouvelles tentatives, entre 0 et 2, que Lambda effectue lorsque la fonction renvoie une erreur.

  6. Choisissez Enregistrer.

Quand un événement d'appel dépasse l'âge maximum ou échoue à toutes les tentatives, Lambda le supprime. Pour conserver une copie des événements supprimés, configurez une destination en cas d'échec.

Configuration des destinations pour les appels asynchrones

Pour envoyer des enregistrements d'appel asynchrone à un autre service, ajoutez une destination à votre fonction. Vous pouvez configurer des destinations distinctes pour les événements dont le traitement échoue et ceux dont le traitement aboutit. Comme les paramètres de gestion des erreurs, vous pouvez configurer des destinations au niveau d'une fonction, d'une version ou d'un alias.

L'exemple suivant montre une fonction qui traite les appels asynchrones. Quand la fonction renvoie une réponse de succès ou quitte sans lever d'erreur, Lambda envoie un enregistrement de l'appel à un bus d'événements EventBridge. Quand un événement échoue à toutes les tentatives de traitement, Lambda envoie un enregistrement d'appel à une file d'attente Amazon SQS standard.

Lambda envoie les enregistrements d'appel à une destination de bus d'événements ou de file d'attente, selon le résultat.

Pour envoyer des événements à une destination, votre fonction a besoin d'autorisations supplémentaires. Ajoutez une stratégie avec les autorisations requises au rôle d'exécution de votre fonction. Chaque service de destination nécessite une autorisation différente, comme suit :

Ajoutez des destinations à votre fonction dans la visualisation de la fonction sur la console Lambda.

Pour configurer une destination pour des enregistrements d'appel asynchrone

  1. Ouvrez la page Functions (Fonctions) de la console Lambda.

  2. Choisissez une fonction.

  3. Sous Function overview (Vue d'ensemble de la fonction), choisissez Add destination (Ajouter une destination).

  4. Pour Source, choisissez Asynchronous invocation (Appel asynchrone).

  5. Pour Condition choisissez l'une des options suivantes :

    • On failure (En cas d'échec) – Envoyer un enregistrement quand l'événement échoue à toutes les tentatives de traitement ou dépasse l'âge maximal.

    • On success (En cas de succès) – Envoyer un enregistrement quand la fonction traite avec succès un appel asynchrone.

  6. Pour Type de destination, choisissez le type de ressource qui reçoit l'enregistrement d'appel.

  7. Pour Destination, choisissez une ressource.

  8. Choisissez Enregistrer.

Quand un appel correspond à la condition, Lambda envoie à la destination un document JSON avec des détails sur l'appel.

Format JSON spécifique à la destination

  • Pour Amazon SQS et Amazon SNS (SnsDestination et SqsDestination), l'enregistrement d'appel est transmis en tant que Message jusqu'à la destination.

  • Pour Lambda (LambdaDestination), l'enregistrement d'appel est transmis en tant que charge utile à la fonction.

  • Pour EventBridge (EventBridgeDestination), l'enregistrement d'appel est transmis en tant que detail dans l'appel PutEvents. La valeur du champ événement source est lambda. La valeur du champ événement detail-type est soit Résultat de l'invocation de la fonction lambda – Succès, soit Résultat de l'invocation de la fonction lambda – Échec. Le champ d'événement resource contient la fonction et les Amazon Resource Names (ARNs) de destination. Pour les autres champs d'événements, voir Événements Amazon EventBridge.

L'exemple suivant illustre un enregistrement d'appel pour un événement dont le traitement a échoué à trois reprises en raison d'une erreur de fonction.

Exemple enregistrement d'appel
{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

L'enregistrement d'appel contient des détails sur l'événement, la réponse et la raison pour laquelle l'enregistrement a été envoyé.

Suivi des demandes vers les destinations

Vous pouvez utiliser X-Ray pour visualiser une vue connectée de chaque demande lorsqu'elle est placée en file d'attente, traitée par une fonction Lambda et transmise au service de destination. Lorsque vous activez le suivi X-Ray pour une fonction ou un service qui appelle une fonction, Lambda ajoute un en-tête X-Ray à la demande et transmet l'en-tête au service de destination. Les traces des services en amont sont automatiquement liées aux traces des fonctions Lambda et des services de destination en aval, créant ainsi une vue de bout en bout de l'application entière. Pour plus d'informations sur le suivi, consultez Utilisation de AWS Lambda avec AWS X-Ray.

API de configuration d'appel asynchrone

Pour gérer les paramètres d'appel asynchrone avec AWS CLI ou le kit SDK AWS, utilisez les opérations d'API suivantes.

Pour configurer l'appel asynchrone avec la AWS CLI, utilisez la commande put-function-event-invoke-config. L'exemple suivant montre comment configurer une fonction avec un âge d'événement maximal de 1 heure et aucune nouvelle tentative.

aws lambda put-function-event-invoke-config --function-name error \
--maximum-event-age-in-seconds 3600 --maximum-retry-attempts 0

Vous devriez voir la sortie suivante:

{
    "LastModified": 1573686021.479,
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
    "MaximumRetryAttempts": 0,
    "MaximumEventAgeInSeconds": 3600,
    "DestinationConfig": {
        "OnSuccess": {},
        "OnFailure": {}
    }
}

La commande put-function-event-invoke-config remplace toute configuration existante sur la fonction, la version ou l'alias. Pour configurer une option sans en réinitialiser d'autres, utilisez update-function-event-invoke-config. L'exemple suivant illustre la configuration de Lambda pour l'envoie d'un enregistrement à une file d'attente SQS standard nommée destination lorsqu'un événement ne peut pas être traité.

aws lambda update-function-event-invoke-config --function-name error \
--destination-config '{"OnFailure":{"Destination": "arn:aws:sqs:us-east-2:123456789012:destination"}}'

Vous devriez voir la sortie suivante :

{
    "LastModified": 1573687896.493,
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
    "MaximumRetryAttempts": 0,
    "MaximumEventAgeInSeconds": 3600,
    "DestinationConfig": {
        "OnSuccess": {},
        "OnFailure": {
            "Destination": "arn:aws:sqs:us-east-2:123456789012:destination"
        }
    }
}

Files d'attente de lettres mortes

Comme alternative à une destination réservée aux échecs, vous pouvez configurer votre fonction avec une file d'attente de lettres mortes pour enregistrer les événements ignorés en vue d'un traitement ultérieur. Une file d'attente de lettres mortes agit de la même manière qu'une destination réservée aux échecs en ce sens qu'elle est utilisée lorsqu'un événement échoue à toutes les tentatives de traitement ou expire sans être traité. Toutefois, une file d'attente de lettres mortes fait partie d'une configuration spécifique à la version de la fonction. Elle est donc verrouillée lorsque vous publiez une version. Les destinations réservées aux échecs prennent également en charge des cibles supplémentaires et incluent des détails sur la réponse de la fonction dans l'enregistrement d'appel.

Pour retraiter les événements d'une file d'attente de lettres mortes, vous pouvez la définir comme source d'événements pour votre fonction Lambda. Vous pouvez également récupérer manuellement les événements.

Vous pouvez choisir une file d'attente Amazon SQS standard ou une rubrique Amazon SNS standanrd pour votre file d'attente de lettres mortes. Les files d'attente FIFO et les rubriques FIFO Amazon SNS ne sont pas prises en charge. Si vous n'avez pas de file d'attente ou de rubrique, créez-en une. Choisissez le type de cible qui correspond à votre cas d'utilisation.

  • File d'attente Amazon SQS – Une file d'attente conserve les événements qui ont échoué jusqu'à ce qu'ils soient récupérés. Choisissez une file d'attente Amazon SQS standard si vous voulez qu'une seule entité, telle qu'une fonction Lambda ou une alarme CloudWatch, traite l'événement ayant échoué. Pour de plus amples informations, veuillez consulter Utilisation de Lambda avec Amazon SQS.

    Dans la console Amazon SQS, créez une file d'attente.

  • Rubrique Amazon SNS – Une rubrique relaie les événements qui ont échoué vers une ou plusieurs destinations. Choisissez une rubrique Amazon SNS standard si vous voulez que plusieurs entités agissent sur un événement ayant échoué. Par exemple, vous pouvez configurer une rubrique pour envoyer des événements à une adresse e-mail, à une fonction Lambda ou à un point de terminaison HTTP. Pour de plus amples informations, veuillez consulter Utilisation d'Amazon SNS avec un kit SDK AWS Lambda.

    Créez une rubrique SNS avec la console Amazon SNS.

Pour envoyer des événements à une file d'attente ou une rubrique, votre fonction a besoin d'autorisations supplémentaires. Ajoutez une stratégie avec les autorisations requises au rôle d'exécution de votre fonction.

Si la file d'attente ou la rubrique cible est chiffrée avec une clé gérée par le client, le rôle d'exécution doit également être un utilisateur dans la stratégie basée sur les ressources de la clé.

Après avoir créé la cible et mis à jour votre rôle d'exécution de la fonction, ajoutez la file d'attente de lettres mortes à votre fonction. Vous pouvez configurer plusieurs fonctions pour envoyer des événements à la même cible.

Configuration d'une file d'attente de lettres mortes

  1. Ouvrez la page Functions (Fonctions) de la console Lambda.

  2. Choisissez une fonction.

  3. Sélectionnez Configuration, puis Asynchronous invocation (Appel asynchrone).

  4. Sous Asynchronous invocation (Appel asynchrone), choisissez Edit (Modifier).

  5. Définissez DLQ resource (ressource DLQ) sur Amazon SQS ou Amazon SNS.

  6. Choisissez la file d'attente ou la rubrique cible.

  7. Choisissez Enregistrer.

Pour configurer une file d'attente de lettres mortes avec la AWS CLI, utilisez la commande update-function-configuration.

aws lambda update-function-configuration --function-name my-function \
--dead-letter-config TargetArn=arn:aws:sns:us-east-2:123456789012:my-topic

Lambda envoie l'événement à la file d'attente de lettres mortes en l'état, avec des informations supplémentaires dans les attributs. Vous pouvez utiliser ces informations pour identifier l'erreur que la fonction a renvoyée ou établir une corrélation entre l'événement et des journaux ou une trace AWS X-Ray.

Attributs de message de file d'attente de lettres mortes

  • RequestID (Chaîne) – ID de la demande d'appel. Les ID de demande apparaissent dans les journaux de la fonction. Vous pouvez également utiliser le kit SDK X-Ray pour enregistrer l'ID de demande sur un attribut dans le suivi. Vous pouvez ensuite rechercher des suivis par ID de demande dans la console X-Ray. Consultez l'exemple de processeur d'erreur.

  • ErrorCode (Nombre) – Code d'état HTTP.

  • ErrorMessage (Chaîne) – Premier Ko du message d'erreur.

Attributs d'événement de file d'attente de lettres mortes dans la console Amazon SQS.

Si Lambda ne peut pas envoyer un message à la file d'attente de lettres mortes, il supprime l'événement et émet la métrique DeadLetterErrors. Cela peut se produire en raison d'un manque d'autorisations ou si la taille totale du message est supérieure à la limite de la file d'attente cible ou rubrique. Par exemple, si une notification Amazon SNS dont le corps a une taille proche de 256 Ko déclenche une fonction qui génère une erreur, le message risque de dépasser la taille maximale autorisée dans la file d'attente de lettres mortes en raison des données d'événement supplémentaires ajoutées par Amazon SNS et de attributs ajoutés par Lambda.

Si vous utilisez Amazon SQS en tant que source d'événement, configurez une file d'attente de lettres mortes sur la file d'attente Amazon SQS elle-même, non sur la fonction Lambda. Pour de plus amples informations, veuillez consulter Utilisation de Lambda avec Amazon SQS.