Gérer les dépendances

Sélectionner la langue : Node.js Python

Une fonction Cloud Functions peut utiliser des modules externes et des dépendances locales. La façon dont vous spécifiez et gérez les dépendances dépend de votre langage d'exécution.

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 de Cloud Functions 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 :

JavaScript

const onRequest = require("firebase-functions/https");
const escapeHtml = require("escape-html");

// Return a greeting with the input HTML-escaped.
exports.hello = onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);
});

TypeScript

import { onRequest } from "firebase-functions/https";
import * as escapeHtml from "escape-html";

// Return a greeting with the input HTML-escaped.
export let hello = onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);
});

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.

Étapes supplémentaires pour TypeScript

TypeScript est plus utile lorsque vous utilisez des bibliothèques contenant des informations de type. Cela permet à TypeScript de détecter les erreurs de syntaxe et aux éditeurs de vous fournir de meilleures suggestions de saisie semi-automatique. Certaines bibliothèques, telles que firebase-admin et firebase-functions, sont fournies avec des définitions TypeScript incluses.

De nombreuses bibliothèques ne fournissent pas leur propre définition TypeScript. Le projet DefinitelyTyped fournit des définitions gérées par la communauté pour les bibliothèques de nœuds les plus populaires. DefinitelyTyped publie ces définitions sous le même nom de package NPM, mais au sein de l'organisation "@types". Par exemple, vous pouvez installer les informations de type pour la bibliothèque uuid avec la commande suivante :

npm install @types/uuid

À mesure que vous vous familiarisez avec TypeScript, vous pouvez combiner les deux installations :

npm install uuid @types/uuid

Les dépendances de type doivent être du même type que la dépendance de la bibliothèque. Par exemple, vous ne devez pas enregistrer uuid en tant que dépendance normale et @types/uuid en tant que dépendance de développement ou dépendance homologue.

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.

Si vous écrivez des fonctions en TypeScript, utilisez l import instruction de la même manière pour charger les modules Node.js que vous avez installés.

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 Google Cloud Functions, 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 sur registry.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}, que npm 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 commande gcloud functions deploy. Pour en savoir plus sur le jeton d'authentification NPM, consultez le tutoriel NPM sur les modules privés.

Python

Il existe deux manières de spécifier des dépendances pour Cloud Functions rédigées en Python : en utilisant le fichier pip du gestionnaire de paquets requirements.txt ou en empaquetant les dépendances locales avec votre fonction.

La spécification des dépendances avec le fichier standard Pipfile/Pipfile.lock n'est actuellement pas prise en charge. Votre projet ne doit pas contenir ces fichiers.

Spécifier des dépendances avec pip

Dans Python, les dépendances sont gérées avec piprequirements.txt et exprimées dans un fichier de métadonnées appelé . Ce fichier doit se trouver dans le même répertoire que le fichier main.py qui contient le code de votre fonction.

Lorsque vous déployez ou redéployez votre fonction, Cloud Functions utilise pip pour télécharger et installer la dernière version de vos dépendances, comme déclaré dans le fichier requirements.txt. Le fichier requirements.txt contient une ligne par package. Chaque ligne contient le nom du package et, éventuellement, la version demandée. Pour en savoir plus, consultez la documentation de référence sur requirements.txt.

Pour éviter que votre compilation ne soit affectée par les modifications de version de dépendance, envisagez d'épingler vos packages de dépendances sur une version spécifique.

Voici un exemple de fichier requirements.txt :

functions-framework
requests==2.20.0
numpy

Empaqueter les dépendances locales

Vous pouvez également empaqueter et déployer les dépendances avec votre fonction. Cette approche est utile si votre dépendance n'est pas disponible via le gestionnaire de packages pip ou si l'accès Internet de votre environnement Cloud Functions est limité.

Par exemple, vous pouvez utiliser une structure de répertoires comme suit :

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

Vous pouvez ensuite importer le code comme d'habitude à partir de localpackage en utilisant l'instruction import suivante.

# Code in main.py
from localpackage import script

Notez qu'avec cette approche, les fichiers setup.py ne sont pas exécutés. Les packages contenant ces fichiers peuvent toujours être regroupés, mais ils peuvent ne pas s'exécuter correctement sur Cloud Functions.