Déployer des fonctions Lambda en Node.js avec des archives de fichiers .zip

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.

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.

Le code de votre AWS Lambda fonction comprend un fichier .js ou .mjs contenant le code du gestionnaire de votre fonction, ainsi que les packages et modules supplémentaires dont dépend votre code. Pour déployer ce code de fonction vers Lambda, vous utilisez un package de déploiement. Ce package peut être une archive de fichier .zip ou une image de conteneur. Pour plus d’informations sur l’utilisation d’images de conteneur avec Node.js, consultez la page Déployer des fonctions Lambda Node.js avec des images de conteneur.

Pour créer votre package de déploiement sous forme d’archive de fichier .zip, vous pouvez utiliser l’utilitaire d’archivage .zip intégré à votre outil de ligne de commande, ou tout autre utilitaire .zip tel que 7zip. Les exemples présentés dans les sections suivantes supposent que vous utilisez un outil zip de ligne de commande dans un environnement Linux ou macOS. Pour utiliser les mêmes commandes sous Windows, vous pouvez installer le sous-système Windows pour Linux afin d’obtenir une version intégrée à Windows d’Ubuntu et de Bash.

Notez que Lambda utilise les autorisations de fichiers POSIX. Ainsi, vous pourriez devoir définir des autorisations pour le dossier du package de déploiement avant de créer l’archive de fichiers .zip.

Dépendances d’exécution dans Node.js

Pour les fonctions Lambda qui utilisent l’exécution Node.js, une dépendance peut être n’importe quel package ou module Node.js. L'exécution Node.js comprend un certain nombre de bibliothèques courantes, ainsi qu'une version de AWS SDK pour JavaScript. Le moteur d’exécution nodejs16.x Lambda inclut la version 2.x du kit SDK. Les versions d’exécution nodejs18.x et ultérieures incluent la version 3 du kit SDK. Pour utiliser la version 2 du kit SDK avec les versions d’exécution nodejs18.x et ultérieures, ajoutez le kit SDK à votre package de déploiement de fichiers .zip. Si l’exécution choisie comprend la version du kit SDK que vous utilisez, il n’est pas nécessaire d’inclure la bibliothèque du kit SDK dans votre fichier .zip. Pour savoir quelle version du kit SDK est incluse dans l’environnement d’exécution que vous utilisez, consultez Versions du SDK incluses dans l’environnement d’exécution.

Lambda met régulièrement à jour les bibliothèques du kit SDK dans l’exécution Node.js afin d’inclure les dernières fonctionnalités et mises à jour de sécurité. Lambda applique également des correctifs de sécurité et des mises à jour aux autres bibliothèques incluses dans l’exécution. Pour avoir un contrôle total sur les dépendances de votre package, vous pouvez ajouter votre version préférée de n’importe quelle dépendance incluse dans l’exécution à votre package de déploiement. Par exemple, si vous souhaitez utiliser une version particulière du SDK pour JavaScript, vous pouvez l'inclure dans votre fichier .zip en tant que dépendance. Pour plus d’informations sur l’ajout de dépendances incluses dans l’exécution à votre fichier .zip, consultez Chemin de recherche des dépendances et bibliothèques incluses dans l’exécution.

Dans le cadre du modèle de responsabilité partagée AWS, vous êtes responsable de la gestion de toutes les dépendances dans les packages de déploiement de vos fonctions. Cela inclut l’application de mises à jour et de correctifs de sécurité. Pour mettre à jour les dépendances dans le package de déploiement de votre fonction, créez d’abord un nouveau fichier .zip, puis chargez-le sur Lambda. Pour plus d’informations, consultez Création d’un package de déploiement .zip avec dépendances et Création et mise à jour de fonctions Lambda Node.js à l’aide de fichiers .zip.

Création d’un package de déploiement .zip sans dépendances

Si le code de votre fonction ne comporte aucune dépendance à l’exception des bibliothèques incluses dans l’exécution Lambda, votre fichier .zip contient uniquement le fichier index.js ou index.mjs avec le code du gestionnaire de votre fonction. Utilisez votre utilitaire zip préféré pour créer un fichier .zip avec votre fichier index.js ou index.mjs à la racine. Si le fichier contenant le code de votre gestionnaire ne se trouve pas à la racine de votre fichier .zip, Lambda ne sera pas en mesure d’exécuter votre code.

Pour savoir comment déployer votre fichier .zip pour créer une nouvelle fonction Lambda ou mettre à jour une fonction Lambda existante, veuillez consulter la rubrique Création et mise à jour de fonctions Lambda Node.js à l’aide de fichiers .zip.

Création d’un package de déploiement .zip avec dépendances

Si votre code de fonction dépend de packages ou de modules qui ne sont pas inclus dans l’environnement d’exécution Lambda Node.js, vous pouvez soit ajouter ces dépendances à votre fichier .zip avec votre code de fonction, soit utiliser une couche Lambda. Les instructions de cette section vous indiquent comment inclure vos dépendances dans votre package de déploiement .zip. Pour obtenir des instructions sur la façon d’inclure vos dépendances dans une couche, voir Création d’une couche Node.js pour vos dépendances.

L’exemple de commandes de CLI suivant crée un fichier .zip nommé my_deployment_package.zip contenant le fichier index.js ou index.mjs avec le gestionnaire de code de votre fonction et ses dépendances. Dans l’exemple, vous installez les dépendances à l’aide du gestionnaire de packages npm.

Création d’une couche Node.js pour vos dépendances

Les instructions de cette section vous indiquent comment inclure les dépendances dans une couche. Pour obtenir des instructions sur la façon d’inclure vos dépendances dans votre package de déploiement, voir Création d’un package de déploiement .zip avec dépendances.

Lorsque vous ajoutez une couche à une fonction, Lambda charge le contenu de la couche dans le répertoire /opt de cet environnement d’exécution. Pour chaque exécution Lambda, la variable PATH inclut déjà des chemins de dossiers spécifiques dans le répertoire /opt. Pour que Lambda récupère le contenu de votre couche, les dépendances de votre fichier .zip de couche doivent se trouver dans les chemins de dossier suivants :

Par exemple, la structure du fichier .zip de votre couche peut ressembler à ce qui suit :

xray-sdk.zip
└ nodejs/node_modules/aws-xray-sdk

En outre, Lambda détecte automatiquement toutes les bibliothèques dans le répertoire /opt/lib et tous les fichiers binaires dans le répertoire /opt/bin. Pour que Lambda trouve correctement le contenu de votre couche, vous pouvez aussi créer une couche avec la structure suivante :

custom-layer.zip
└ lib
    | lib_1
    | lib_2
└ bin
    | bin_1
    | bin_2

Après avoir empaqueté votre couche, reportez-vous à Création et suppression de couches dans Lambda et à Ajout de couches aux fonctions pour terminer la configuration de votre couche.

Chemin de recherche des dépendances et bibliothèques incluses dans l’exécution

L’exécution Node.js comprend un certain nombre de bibliothèques courantes, ainsi qu’une version de AWS SDK pour JavaScript. Si vous souhaitez utiliser une version différente d’une bibliothèque incluse dans l’exécution, vous pouvez le faire en l’associant à votre fonction ou en l’ajoutant en tant que dépendance dans votre package de déploiement. Par exemple, vous pouvez utiliser une version différente du kit SDK en l’ajoutant à votre package de déploiement .zip. Vous pouvez également l’inclure dans une couche Lambda pour votre fonction.

Lorsque vous utilisez une instruction import ou require dans votre code, l’exécution Node.js recherche les répertoires dans le chemin NODE_PATH jusqu’à ce qu’elle trouve le module. Par défaut, le premier emplacement dans lequel recherche l’exécution est le répertoire dans lequel votre package de déploiement .zip est décompressé et monté (/var/task). Si vous ajoutez une version d’une bibliothèque incluse dans l’exécution dans votre package de déploiement, cette version prévaudra sur la version incluse dans l’exécution. Les dépendances de votre package de déploiement ont également la priorité sur les dépendances des couches.

Lorsque vous ajoutez une dépendance à une couche, Lambda l’extrait vers /opt/nodejs/nodexx/node_modules, où nodexx représente la version de l’exécution que vous utilisez. Dans le chemin de recherche, ce répertoire a la priorité sur le répertoire contenant les bibliothèques incluses dans l’exécution (/var/lang/lib/node_modules). Les bibliothèques des couches de fonctions ont donc la priorité sur les versions incluses dans l’exécution.

Vous pouvez voir le chemin de recherche complet de votre fonction Lambda en ajoutant la ligne de code suivante.

console.log(process.env.NODE_PATH)

Vous pouvez également ajouter des dépendances dans un dossier distinct au sein de votre package .zip. Par exemple, vous pouvez ajouter un module personnalisé à un dossier votre package .zip appelé common. Lorsque votre package .zip est décompressé et monté, ce dossier est placé dans le répertoire /var/task. Pour utiliser une dépendance provenant d’un dossier de votre package de déploiement .zip dans votre code, utilisez une instruction import { } from ou const { } = require(), selon que vous utilisez la résolution du module CJS ou ESM. Par exemple :

import { myModule } from './common'

Si vous regroupez votre code à esbuild, rollup, ou similaire, les dépendances utilisées par votre fonction sont regroupées dans un ou plusieurs fichiers. Nous vous recommandons d’utiliser cette méthode pour vendre des dépendances chaque fois que cela est possible. Par rapport à l’ajout de dépendances à votre package de déploiement, le regroupement de votre code permet d’améliorer les performances en raison de la réduction des opérations d’E/S.

Création et mise à jour de fonctions Lambda Node.js à l’aide de fichiers .zip

Une fois que vous avez créé votre package de déploiement .zip, vous pouvez l’utiliser pour créer une nouvelle fonction Lambda ou mettre à jour une fonction Lambda existante. Vous pouvez déployer votre package .zip à l'aide de la console Lambda, de l'API Lambda et AWS Command Line Interface de l'API Lambda. Vous pouvez également créer et mettre à jour des fonctions Lambda à l’aide de l’ AWS Serverless Application Model (AWS SAM) et de AWS CloudFormation.

La taille maximale d’un package de déploiement .zip pour Lambda est de 250 Mo (décompressé). Notez que cette limite s’applique à la taille combinée de tous les fichiers que vous chargez, y compris les couches Lambda.

Le runtime Lambda a besoin d’une autorisation pour lire les fichiers de votre package de déploiement. Dans la notation octale des autorisations Linux, Lambda a besoin de 644 autorisations pour les fichiers non exécutables (rw-r--r--) et de 755 autorisations () pour les répertoires et les fichiers exécutables. rwxr-xr-x

Sous Linux et macOS, utilisez la commande chmod pour modifier les autorisations de fichiers sur les fichiers et les répertoires de votre package de déploiement. Par exemple, pour octroyer à un fichier non exécutable les autorisations correctes, exécutez la commande suivante.

chmod 644 <filepath>

Pour modifier les autorisations relatives aux fichiers dans Windows, voir Définir, afficher, modifier ou supprimer des autorisations sur un objet dans la documentation Microsoft Windows.

Création et mise à jour de fonctions avec des fichiers .zip à l’aide de la console

Pour créer une nouvelle fonction, vous devez d’abord créer la fonction dans la console, puis charger votre archive .zip. Pour mettre à jour une fonction existante, ouvrez la page de votre fonction, puis suivez la même procédure pour ajouter votre fichier .zip mis à jour.

Si votre fichier .zip fait moins de 50 Mo, vous pouvez créer ou mettre à jour une fonction en chargeant le fichier directement à partir de votre ordinateur local. Pour les fichiers .zip de plus de 50 Mo, vous devez d’abord charger votre package dans un compartiment Amazon S3. Pour savoir comment charger un fichier dans un compartiment Amazon S3 à l'aide du AWS Management Console, consultez Getting started with Amazon S3. Pour télécharger des fichiers à l'aide de AWS CLI, voir Déplacer des objets dans le guide de AWS CLI l'utilisateur.

Mise à jour des fonctions du fichier .zip à l’aide de l’éditeur de code de la console

Pour certaines fonctions avec des packages de déploiement .zip, vous pouvez utiliser l’éditeur de code intégré de la console Lambda pour mettre à jour le code de votre fonction directement. Pour utiliser cette fonctionnalité, votre fonction doit répondre aux critères suivants :

Le code des fonctions avec les packages de déploiement d’images de conteneurs ne peut pas être édité directement dans la console.

Création et mise à jour de fonctions avec des fichiers .zip à l'aide du AWS CLI

Vous pouvez utiliser l’AWS CLI pour créer une nouvelle fonction ou pour mettre à jour une fonction existante à l’aide d’un fichier .zip. Utilisez la fonction de création et update-function-codeles commandes pour déployer votre package .zip. Si votre fichier .zip est inférieur à 50 Mo, vous pouvez charger le package .zip à partir d’un emplacement de fichier sur votre machine de génération locale. Pour les fichiers plus volumineux, vous devez charger votre package .zip à partir d’un compartiment Amazon S3. Pour savoir comment charger un fichier dans un compartiment Amazon S3 à l'aide du AWS CLI, consultez la section Déplacer des objets dans le guide de AWS CLI l'utilisateur.

Pour créer une nouvelle fonction à l'aide d'un fichier .zip avec le AWS CLI, vous devez spécifier les éléments suivants :

Vous devez également indiquer l’emplacement de votre fichier .zip. Si votre fichier .zip se trouve dans un dossier sur votre machine de génération locale, utilisez l’option --zip-file pour spécifier le chemin d’accès du fichier, comme le montre l’exemple de commande suivant.

aws lambda create-function --function-name myFunction \
--runtime nodejs22.x --handler index.handler \
--role arn:aws:iam::111122223333:role/service-role/my-lambda-role \
--zip-file fileb://myFunction.zip

Pour spécifier l’emplacement du fichier .zip dans un compartiment Amazon S3, utilisez l’option --code comme le montre l’exemple de commande suivant. Vous devez uniquement utiliser le paramètre S3ObjectVersion pour les objets soumis à la gestion des versions.

aws lambda create-function --function-name myFunction \
--runtime nodejs22.x --handler index.handler \
--role arn:aws:iam::111122223333:role/service-role/my-lambda-role \
--code S3Bucket=amzn-s3-demo-bucket,S3Key=myFileName.zip,S3ObjectVersion=myObjectVersion

Pour mettre à jour une fonction existante à l’aide de l’interface de ligne de commande, vous devez spécifier le nom de votre fonction à l’aide du paramètre --function-name. Vous devez également spécifier l’emplacement du fichier .zip que vous souhaitez utiliser pour mettre à jour votre code de fonction. Si votre fichier .zip se trouve dans un dossier sur votre machine de génération locale, utilisez l’option --zip-file pour spécifier le chemin d’accès du fichier, comme le montre l’exemple de commande suivant.

aws lambda update-function-code --function-name myFunction \
--zip-file fileb://myFunction.zip

Pour spécifier l’emplacement du fichier .zip dans un compartiment Amazon S3, utilisez les options --s3-bucket et --s3-key comme le montre l’exemple de commande suivant. Vous devez uniquement utiliser le paramètre --s3-object-version pour les objets soumis à la gestion des versions.

aws lambda update-function-code --function-name myFunction \
--s3-bucket amzn-s3-demo-bucket --s3-key myFileName.zip --s3-object-version myObject Version

Création et mise à jour de fonctions avec des fichiers .zip à l’aide de l’API Lambda

Pour créer et mettre à jour des fonctions à l’aide d’une archive de fichiers .zip, utilisez les opérations d’API suivantes :

Création et mise à jour de fonctions avec des fichiers .zip à l'aide de AWS SAM

The AWS Serverless Application Model (AWS SAM) est une boîte à outils qui permet de rationaliser le processus de création et d'exécution d'applications sans serveur sur AWS. Vous définissez les ressources de votre application dans un modèle YAML ou JSON et vous utilisez l'interface de ligne de AWS SAM commande (AWS SAM CLI) pour créer, empaqueter et déployer vos applications. Lorsque vous créez une fonction Lambda à partir d'un AWS SAM modèle, elle crée AWS SAM automatiquement un package de déploiement ou une image de conteneur .zip avec le code de votre fonction et les dépendances que vous spécifiez. Pour en savoir plus sur l'utilisation des fonctions Lambda AWS SAM pour créer et déployer des fonctions Lambda, consultez la section Getting started with AWS SAM dans le Guide du AWS Serverless Application Model développeur.

Vous pouvez également l'utiliser AWS SAM pour créer une fonction Lambda à l'aide d'une archive de fichiers .zip existante. Pour créer une fonction Lambda à l'aide de AWS SAM, vous pouvez enregistrer votre fichier .zip dans un compartiment Amazon S3 ou dans un dossier local sur votre machine de génération. Pour savoir comment charger un fichier dans un compartiment Amazon S3 à l'aide du AWS CLI, consultez la section Déplacer des objets dans le guide de AWS CLI l'utilisateur.

Dans votre AWS SAM modèle, la AWS::Serverless::Function ressource spécifie votre fonction Lambda. Dans cette ressource, définissez les propriétés suivantes pour créer une fonction à l’aide d’une archive de fichiers .zip :

Ainsi AWS SAM, si votre fichier .zip est supérieur à 50 Mo, vous n'avez pas besoin de le télécharger au préalable dans un compartiment Amazon S3. AWS SAM peut télécharger des packages .zip jusqu'à la taille maximale autorisée de 250 Mo (décompressés) à partir d'un emplacement sur votre machine de compilation locale.

Pour en savoir plus sur le déploiement de fonctions à l'aide d'un fichier .zip dans AWS SAM, consultez AWS::Serverless::Functionle manuel du AWS SAM développeur.

Création et mise à jour de fonctions avec des fichiers .zip à l'aide de AWS CloudFormation

Vous pouvez l'utiliser AWS CloudFormation pour créer une fonction Lambda à l'aide d'une archive de fichiers .zip. Pour créer une fonction Lambda à partir d’un fichier .zip, vous devez d’abord charger votre fichier dans un compartiment Amazon S3. Pour savoir comment charger un fichier dans un compartiment Amazon S3 à l'aide du AWS CLI, consultez la section Déplacer des objets dans le guide de AWS CLI l'utilisateur.

Dans votre AWS CloudFormation modèle, la AWS::Lambda::Function ressource spécifie votre fonction Lambda. Dans cette ressource, définissez les propriétés suivantes pour créer une fonction à l’aide d’une archive de fichiers .zip :

Le fichier .zip AWS CloudFormation généré ne peut pas dépasser 4 Mo. Pour en savoir plus sur le déploiement de fonctions à l'aide d'un fichier .zip dans AWS CloudFormation, consultez AWS::Lambda::Functionle Guide de l'AWS CloudFormation utilisateur.