Spécifier les dépendances dans Node.js
Une fonction est autorisée à utiliser d'autres modules Node.js ainsi que des données locales. Dans Node.js, les dépendances sont gérées avec npm et exprimées dans un fichier de métadonnées appelé package.json
. Les environnements d'exécution Node.js des fonctions Cloud Run sont compatibles avec l'installation via npm, yarn ou pnpm.
Pour spécifier une dépendance pour votre fonction, ajoutez-la au fichier package.json
.
Dans cet exemple, une dépendance est répertoriée dans le fichier package.json
:
{ "dependencies": { "escape-html": "^1.0.3" } }
La dépendance est alors importée dans la fonction :
Le Functions Framework est une dépendance requise pour toutes les fonctions. Bien que les fonctions Cloud Run l'installent en votre nom lors de la création de la fonction, nous vous recommandons de l'inclure en tant que dépendance explicite pour plus de clarté.
Si votre fonction repose sur des dépendances privées, nous vous recommandons de mettre en miroir functions-framework
dans votre registre privé. Incluez la valeur functions-framework
mise en miroir en tant que dépendance à votre fonction pour éviter d'installer le package depuis l'Internet public.
Utiliser npm
pour installer des modules Node.js localement
La méthode la plus simple pour installer un module Node.js localement consiste à utiliser la commande npm install
dans le dossier contenant votre fonction Cloud Run. Par exemple, la commande suivante ajoute le module uuid
:
npm install uuid
Cette commande a un double effet :
- Elle définit la dernière version du module comme dépendance dans votre fichier
package.json
. C'est très important : les fonctions Cloud Run installent uniquement les modules qui sont déclarés dans votre fichierpackage.json
. - Elle télécharge le module dans votre répertoire
node_modules
. Cela vous permet d'utiliser le module lors du développement local.
Si vous n'avez pas installé npm sur votre ordinateur, procurez-vous npm.
Configurer des dépendances de déploiement
Vous pouvez installer des dépendances en production pour NPM, Yarn ou Pnpm :
NPM
Lorsque vous déployez votre fonction, les fonctions Cloud Run installent les dépendances déclarées dans le fichier package.json
à l'aide de la commande npm install
:
npm install --production
Yarn
Dans l'environnement d'exécution Node.js 8 ou version ultérieure, si un fichier yarn.lock
existe, les fonctions Cloud Run utilisent la commande yarn install
:
yarn install --production
Pnpm
Dans l'environnement d'exécution Node.js 8 ou version ultérieure, si un fichier pnpm-lock.yaml
existe, les fonctions Cloud Run utilisent la commande pnpm install
:
pnpm install
Exécuter les étapes de compilation personnalisée lors du déploiement
Une fois le déploiement terminé, vous pouvez effectuer une étape de compilation personnalisée pendant le processus de compilation de la fonction en ajoutant un script gcp-build
dans votre fichier package.json
.
Lorsque ce script est exécuté, les dépendances des champs dependencies
et devDependencies
du fichier package.json
sont disponibles. Après avoir exécuté l'étape de compilation personnalisée, les fonctions Cloud Run suppriment et génèrent à nouveau le dossier node_modules
en n'installant que les dépendances de l'environnement de production déclarées dans le champ dependencies
du fichier package.json
.
Si le fichier package.json
ne contient pas de script gcp-build
, les fonctions Cloud Run installent simplement les dépendances de l'environnement de production.
Utiliser des packages système
L'environnement d'exécution Node.js inclut également un certain nombre de packages système. Si votre fonction utilise une dépendance nécessitant un package non répertorié, vous pouvez demander un package.
Inclure des modules Node.js locaux
Vous pouvez également inclure des modules Node.js locaux comme faisant partie de votre fonction. Pour ce faire, déclarez votre module dans le fichier package.json
à l'aide du préfixe file:
. Dans l'exemple suivant, mymodule
fait référence au nom de votre module et mymoduledir
correspond au répertoire contenant le module :
{ "dependencies": { "mymodule": "file:mymoduledir" } }
Le code de ce module local doit être stocké ailleurs que dans le dossier node_modules
du répertoire racine de votre fonction.
Charger des modules Node.js
Utilisez la fonction require()
Node.js pour charger les modules Node.js que vous avez installés. Vous pouvez également utiliser la fonction require()
pour importer les fichiers locaux que vous déployez avec votre fonction.
Utiliser des modules privés
Vous pouvez utiliser un module npm privé en fournissant des paramètres d'authentification avec le registre dans un fichier .npmrc
du répertoire de la fonction. Si vous utilisez comme gestionnaire de packages Yarn v2 ou une version ultérieure, ce fichier est nommé .yarnrc.yml
.
Modules privés d'Artifact Registry
Un dépôt de packages Node.js Artifact Registry peut héberger des modules privés pour votre fonction. Lorsque vous déployez une fonction Cloud Run, le processus de compilation génère automatiquement des identifiants Artifact Registry pour le compte de service Cloud Build.
Il vous suffit de répertorier le dépôt Artifact Registry dans votre fichier .npmrc
sans générer d'identifiants supplémentaires. Exemple :
@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true
Cette approche fonctionne également pour le gestionnaire de packages Yarn v1.
Si vous utilisez Yarn v2 ou une version ultérieure, il vous suffit de répertorier le dépôt Artifact Registry dans votre fichier .yarnrc.yml
sans identifiants supplémentaires.
Exemple :
npmScopes:
SCOPE:
npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
npmAlwaysAuth: true
Modules privés d'autres dépôts
La documentation npm explique comment créer des jetons d'accès personnalisés en lecture seule. Nous déconseillons l'utilisation du fichier .npmrc
créé dans le répertoire d'accueil, car il contient un jeton de lecture/écriture. Les autorisations d'écriture ne sont pas requises pendant le déploiement et peuvent présenter un risque pour la sécurité.
N'incluez pas le fichier .npmrc
si vous n'utilisez pas de dépôts privés, car cela peut augmenter le temps de déploiement de vos fonctions.
Format de fichier
Si vous utilisez un fichier .npmrc
pour définir un jeton d'authentification personnalisé, il doit inclure la ligne ci-dessous.
//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN
Remplacez :
- REGISTRY_DOMAIN : le nom de domaine de votre registre npm privé. Si votre dépôt est hébergé avec
npmjs.org
, définissez ce champ surregistry.npmjs.org
. AUTH_TOKEN : jeton d'autorisation de votre registre npm. Il peut s'agir de la valeur de texte littéral du jeton, ou de la chaîne de texte
${NPM_TOKEN}
, quenpm
va remplacer par la valeur réelle du jeton, fournie par l'environnement.Vous pouvez définir la variable d'environnement
$NPM_TOKEN
avec l'argument--set-build-env-vars
sur votre commandegcloud functions deploy
. Pour en savoir plus sur le jeton d'authentification NPM, consultez le tutoriel NPM sur les modules privés.
Créer votre fonction avec des dépendances fournies par le fournisseur
Les dépendances fournies sont celles dont la source est incluse directement dans votre package de code source et reconstruite avec votre propre code. Vous créez des dépendances Node.js fournies par le fournisseur et vous ne les installez pas lors du déploiement à l'aide de la variable d'environnement de compilation GOOGLE_VENDOR_NPM_DEPENDENCIES.
Prérequis pour les dépendances fournies par le fournisseur
Assurez-vous de disposer d'une fonction opérationnelle avec toutes les dépendances que vous souhaitez spécifier dans le fournisseur définies dans votre fichier
package.json
.Installez ces dépendances localement en exécutant la commande suivante :
npm install
Supprimez
node_modules
du fichier .gcloudignore dans votre répertoire de travail.Déployez la fonction en vous assurant que votre version locale de Node.js est identique à celle que vous spécifiez lors du déploiement.
Déployez votre fonction et les dépendances fournies par le fournisseur à l'aide de la commande suivante :
gcloud functions deploy FUNCTION_NAME \ --runtime RUNTIME_NAME \ --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
Remplacez :
- FUNCTION_NAME : nom de la fonction Cloud Run que vous déployez.
- RUNTIME_NAME : nom de l'environnement d'exécution Node.js dans lequel exécuter votre fonction déployée. Il doit s'agir de la même version de Node.js que celle utilisée dans votre environnement de développement local.
Le package du framework Functions est une dépendance requise pour les fonctions. Pour des compilations plus rapides, nous vous recommandons d'utiliser le vendoring. Si ce n'est pas le cas, il est téléchargé et installé lors de la création de votre fonction.
Si vous spécifiez un moteur npm dans le fichier package.json, la version de npm spécifiée est téléchargée au moment de la compilation. Pour supprimer ce comportement, supprimez-le de votre fichier package.json.