Définir le gestionnaire de fonctions Lambda dans Node.js

Le gestionnaire de fonction Lambda est la méthode dans votre code de fonction qui traite les événements. Lorsque votre fonction est invoquée, Lambda exécute la méthode du gestionnaire. Votre fonction s’exécute jusqu’à ce que le gestionnaire renvoie une réponse, se ferme ou expire.

Notions de base sur le gestionnaire Node.js

L'exemple de fonction suivant enregistre le contenu de l'objet d'événement et renvoie l'emplacement des journaux.

Note

Cette page présente des exemples de gestionnaires de modules CommonJS et ES. Pour en savoir plus sur la différence entre ces deux types de gestionnaires, consultez Désignation d’un gestionnaire de fonctions en tant que module ES.

ES module handler

export const handler = async (event, context) => {
  console.log("EVENT: \n" + JSON.stringify(event, null, 2));
  return context.logStreamName;
};

CommonJS module handler

exports.handler = async function (event, context) {
  console.log("EVENT: \n" + JSON.stringify(event, null, 2));
  return context.logStreamName;
};

Lorsque vous configurez une fonction, la valeur du paramètre du gestionnaire est le nom du fichier et le nom de la méthode du gestionnaire exporté, séparés par un point. La valeur par défaut dans la console et pour les exemples de ce guide est index.handler. Cela indique la méthode handler qui est exportée à partir du fichier index.js.

L’exécution transmet des arguments à la méthode du gestionnaire. Le premier argument est l’objet event, qui contient les informations de l’appelant. L'invocateur transmet ces informations sous forme de chaîne JSON formatée lorsqu'il appelle Invoke, et le moteur d'exécution les convertit en objet. Lorsqu'un AWS service invoque votre fonction, la structure de l'événement varie d'un service à l'autre.

Le deuxième argument est l’objet de contexte, qui contient des informations sur l’invocation, la fonction et l’environnement d’exécution. Dans l’exemple précédent, la fonction obtient le nom du flux de journaux de l’objet de contexte et le renvoie au mécanisme d’invocation.

Vous pouvez également utiliser un argument callback, qui est une fonction que vous pouvez appeler dans les gestionnaires non asynchrones pour envoyer une réponse. Nous vous recommandons d’utiliser async/await plutôt que des callbacks. Async/await améliore la lisibilité, la gestion des erreurs et l’efficacité. Pour plus d’informations sur les différences entre async/await et les callbacks, consultez Utilisation de callbacks.

Dénomination

Lorsque vous configurez une fonction, la valeur du paramètre du gestionnaire est le nom du fichier et le nom de la méthode du gestionnaire exporté, séparés par un point. La valeur par défaut pour les fonctions créées dans la console et pour les exemples présentés dans ce guide estindex.handler. Cela indique la handler méthode qui est exportée depuis le index.mjs fichier index.js or.

Si vous créez une fonction dans la console en utilisant un nom de fichier ou un nom de gestionnaire de fonction différent, vous devez modifier le nom du gestionnaire par défaut.

Pour modifier le nom du gestionnaire de fonction (console)

1. Ouvrez la page Fonctions de la console Lambda et choisissez votre fonction.

2. Cliquez sur l'onglet Code.

3. Faites défiler l'écran jusqu'au volet Paramètres d'exécution et choisissez Modifier.

4. Dans Gestionnaire, saisissez le nouveau nom de votre gestionnaire de fonction.

5. Choisissez Save (Enregistrer).

Utilisation d’async/await

Si votre code exécute une tâche asynchrone, utilisez le modèle async/await pour vous assurer que le gestionnaire termine son exécution. Async/await est un moyen concis et lisible d’écrire du code asynchrone dans Node.js, sans avoir besoin de callbacks imbriqués ou de promesses en chaîne. Avec async/await, vous pouvez écrire du code qui se lit comme du code synchrone, tout en étant asynchrone et non bloquant.

Le mot-clé async marque une fonction comme étant asynchrone, et le mot-clé await met en pause l’exécution de la fonction jusqu’à ce qu’une Promise soit résolue.

Note

Assurez-vous d’attendre la fin des événements asynchrones. Si la fonction retourne avant que les événements asynchrones ne soient terminés, elle risque d’échouer ou de provoquer un comportement inattendu dans votre application. Cela peut se produire lorsqu’une boucle forEach contient un événement asynchrone. Les boucles forEach attendent un appel synchrone. Pour plus d'informations, consultez Array.prototype. forEach() dans la documentation de Mozilla.

ES module handler

Exemple — HTTP demande avec async/await

const url = "https://aws.amazon.com/";

export const handler = async(event) => {
    try {
        // fetch is available in Node.js 18 and later runtimes
        const res = await fetch(url);
        console.info("status", res.status);
        return res.status;
    }
    catch (e) {
        console.error(e);
        return 500;
    }
};

CommonJS module handler

Exemple — HTTP demande avec async/await

const https = require("https");
let url = "https://aws.amazon.com/";

exports.handler = async function (event) {
  let statusCode;
  await new Promise(function (resolve, reject) {
    https.get(url, (res) => {
        statusCode = res.statusCode;
        resolve(statusCode);
      }).on("error", (e) => {
        reject(Error(e));
      });
  });
  console.log(statusCode);
  return statusCode;
};

L’exemple suivant utilise async/await pour répertorier vos compartiments Amazon Simple Storage Service.

Note

Avant d’utiliser cet exemple, assurez-vous que le rôle d’exécution de votre fonction dispose d’autorisations de lecture Amazon S3.

ES module handler

Exemple — AWS SDK v3 avec async/await

Cet exemple utilise la AWS SDK for JavaScript version 3, qui est disponible dans les environnements d'exécution nodejs18.x et ultérieurs.

import {S3Client, ListBucketsCommand} from '@aws-sdk/client-s3';
const s3 = new S3Client({region: 'us-east-1'});
   
export const handler = async(event) => {
  const data = await s3.send(new ListBucketsCommand({}));
  return data.Buckets;
        
};

CommonJS module handler

Exemple — AWS SDK v3 avec async/await

Cet exemple utilise la AWS SDK for JavaScript version 3, qui est disponible dans les environnements d'exécution nodejs18.x et ultérieurs.

const { S3Client, ListBucketsCommand } = require('@aws-sdk/client-s3');
const s3 = new S3Client({ region: 'us-east-1' });

exports.handler = async (event) => {
  const data = await s3.send(new ListBucketsCommand({}));
  return data.Buckets;
};

Utilisation de callbacks

Nous vous recommandons d’utiliser async/await pour déclarer le gestionnaire de fonctions au lieu d’utiliser des callbacks. Async/await est un meilleur choix pour plusieurs raisons :

• Lisibilité : le code Async/await est plus facile à lire et à comprendre que le code callback, qui peut rapidement devenir difficile à suivre et entraîner l’enfer du callback.

• Débogage et gestion des erreurs : le débogage du code basé sur des callbacks peut être difficile. La pile d’appels peut devenir difficile à suivre et les erreurs peuvent facilement se perdre. Avec async/await, vous pouvez utiliser des blocs try/catch pour gérer les erreurs.

• Efficacité : les callbacks nécessitent souvent de basculer entre différentes parties du code. Async/await permet de réduire le nombre de changements de contexte, ce qui se traduit par un code plus efficace.

Lorsque vous utilisez des callbacks dans votre gestionnaire, la fonction continue à s’exécuter jusqu’à ce que la boucle d’événement soit vide ou que la fonction s’arrête. La réponse n’est pas envoyée à l’appelant tant que toutes les tâches d’événement de boucle ne sont pas terminées. Si la fonction expire, une erreur est renvoyée à la place. Vous pouvez configurer le moteur d'exécution pour envoyer la réponse immédiatement en définissant le contexte. callbackWaitsForEmptyEventLoopà faux.

La fonction de rappel accepte deux arguments : un(e) Error et une réponse. L’objet de réponse doit être compatible avec JSON.stringify.

L'exemple de fonction suivant vérifie a URL et renvoie le code d'état à l'invocateur.

ES module handler

Exemple — HTTP demande avec rappel

import https from "https";
let url = "https://aws.amazon.com/";

export function handler(event, context, callback) {
  https.get(url, (res) => {
      callback(null, res.statusCode);
    }).on("error", (e) => {
      callback(Error(e));
    });
}

CommonJS module handler

Exemple — HTTP demande avec rappel

const https = require("https");
let url = "https://aws.amazon.com/";

exports.handler = function (event, context, callback) {
  https.get(url, (res) => {
      callback(null, res.statusCode);
    }).on("error", (e) => {
      callback(Error(e));
    });
};

Dans l’exemple suivant, la réponse du Simple Storage Service (Amazon S3) est renvoyée au mécanisme d’invocation dès qu’elle est disponible. Le délai d’expiration de l’événement en boucle est gelé et reprend lors de l’invocation suivante de la fonction.

Note

Avant d’utiliser cet exemple, assurez-vous que le rôle d’exécution de votre fonction dispose d’autorisations de lecture Amazon S3.

ES module handler

Exemple — AWS SDK v3 avec callbackWaitsFor EmptyEventLoop

Cet exemple utilise la AWS SDK for JavaScript version 3, qui est disponible dans les environnements d'exécution nodejs18.x et ultérieurs.

import AWS from "@aws-sdk/client-s3";
const s3 = new AWS.S3({});

export const handler = function (event, context, callback) {
  context.callbackWaitsForEmptyEventLoop = false;
  s3.listBuckets({}, callback);
  setTimeout(function () {
    console.log("Timeout complete.");
  }, 5000);
};

CommonJS module handler

Exemple — AWS SDK v3 avec callbackWaitsFor EmptyEventLoop

Cet exemple utilise la AWS SDK for JavaScript version 3, qui est disponible dans les environnements d'exécution nodejs18.x et ultérieurs.

const AWS = require("@aws-sdk/client-s3");
const s3 = new AWS.S3({});

exports.handler = function (event, context, callback) {
  context.callbackWaitsForEmptyEventLoop = false;
  s3.listBuckets({}, callback);
  setTimeout(function () {
    console.log("Timeout complete.");
  }, 5000);
};

Meilleures pratiques en matière de code pour les fonctions Lambda de Node.js

Respectez les directives de la liste suivante pour utiliser les meilleures pratiques de codage lors de la création de vos fonctions Lambda :

• Séparez le gestionnaire Lambda de votre logique principale. Cela vous permet de créer une fonction testable plus unitaire. Dans Node.js, vous obtenez ce qui suit :

  exports.myHandler = function(event, context, callback) {
  	var foo = event.foo;
  	var bar = event.bar;
  	var result = MyLambdaFunction (foo, bar);
  
  	callback(null, result);
  }
  
  function MyLambdaFunction (foo, bar) {
  	// MyLambdaFunction logic here
  }

• Contrôlez les dépendances du package de déploiement de vos fonctions. L'environnement AWS Lambda d'exécution contient un certain nombre de bibliothèques. Pour les environnements d'exécution Node.js et Python, ceux-ci incluent le AWS SDKs. Pour activer le dernier ensemble de mises à jour des fonctionnalités et de la sécurité, Lambda met régulièrement à jour ces bibliothèques. Ces mises à jour peuvent introduire de subtiles modifications dans le comportement de votre fonction Lambda. Pour disposer du contrôle total des dépendances que votre fonction utilise, empaquetez toutes vos dépendances avec votre package de déploiement.

• Réduisez la complexité de vos dépendances. Privilégiez les infrastructures plus simples qui se chargent rapidement au démarrage de l’environnement d’exécution.

• Réduisez la taille de votre package de déploiement selon ses besoins d’exécution. Cela contribue à réduire le temps nécessaire au téléchargement et à la décompression de votre package de déploiement avant l’invocation.

• Tirez parti de la réutilisation de l’environnement d’exécution pour améliorer les performances de votre fonction. Initialisez les SDK clients et les connexions à la base de données en dehors du gestionnaire de fonctions et mettez en cache les actifs statiques localement dans le /tmp répertoire. Les invocations ultérieures traitées par la même instance de votre fonction peuvent réutiliser ces ressources. Cela permet d’économiser des coûts, tout en réduisant le temps d’exécution de la fonction.

  Pour éviter des éventuelles fuites de données entre les invocations, n’utilisez pas l’environnement d’exécution pour stocker des données utilisateur, des événements ou d’autres informations ayant un impact sur la sécurité. Si votre fonction repose sur un état réversible qui ne peut pas être stocké en mémoire dans le gestionnaire, envisagez de créer une fonction distincte ou des versions distinctes d’une fonction pour chaque utilisateur.

• Utilisez une directive keep-alive pour maintenir les connexions persistantes. Lambda purge les connexions inactives au fil du temps. Si vous tentez de réutiliser une connexion inactive lorsque vous invoquez une fonction, cela entraîne une erreur de connexion. Pour maintenir votre connexion persistante, utilisez la directive Keep-alive associée à votre environnement d’exécution. Pour obtenir un exemple, consultez Réutilisation des connexions avec Keep-Alive dans Node.js.

• Utilisez des variables d’environnement pour transmettre des paramètres opérationnels à votre fonction. Par exemple, si vous écrivez dans un compartiment Amazon S3 au lieu de coder en dur le nom du compartiment dans lequel vous écrivez, configurez le nom du compartiment comme variable d’environnement.

• Évitez d’utiliser du code récursif dans votre fonction Lambda, dans lequel la fonction s’appelle elle-même automatiquement jusqu’à ce que certains critères arbitraires soient réunis. Cela peut entraîner un volume involontaire d’invocations de fonction et des coûts accrus. Si vous le faites par inadvertance, définissez immédiatement la simultanéité réservée de la fonction sur 0 afin de bloquer toutes les invocations de la fonction pendant que vous mettez à jour le code.

• N'utilisez pas de code non documenté ni public APIs dans votre code de fonction Lambda. Pour les AWS Lambda environnements d'exécution gérés, Lambda applique régulièrement des mises à jour de sécurité et fonctionnelles aux applications internes de Lambda. APIs Ces API mises à jour internes peuvent être rétroincompatibles, ce qui peut entraîner des conséquences imprévues, telles que des échecs d'invocation si votre fonction dépend de ces mises à jour non publiques. APIs Voir la API référence pour une liste des documents accessibles au publicAPIs.

• Écriture du code idempotent. L’écriture de code idempotent pour vos fonctions garantit ne gestion identique des événements dupliqués. Votre code doit valider correctement les événements et gérer correctement les événements dupliqués. Pour de plus amples informations, veuillez consulterComment faire en sorte que ma fonction Lambda soit idempotente ?.