Environnement d'exécution Node.js

Votre fonction Cloud Run s'exécute dans un environnement composé d'une version de système d'exploitation, de packages complémentaires, d'une compatibilité avec les langages et de la bibliothèque du framework des fonctions compatible avec votre fonction. Cet environnement est identifié par la version de langage et est appelé l'environnement d'exécution.

Pour en savoir plus sur les environnements d'exécution en général et découvrir la version d'Ubuntu utilisée par chaque environnement d'exécution Node.js, consultez la page Environnement d'exécution des fonctions Cloud Run.

Pour commencer à créer et à déployer des fonctions Cloud Functions avec Node.js, consultez le guide de démarrage rapide.

Pour créer et tester vos fonctions sur votre système local, consultez la page Exécuter des fonctions avec le framework des fonctions.

Sélectionner l'environnement d'exécution

Les fonctions Cloud Run sont compatibles avec plusieurs versions de Node.js, répertoriées sur la page Compatibilité des environnements d'exécution. Vous pouvez sélectionner l'environnement d'exécution Node.js de votre choix pour votre fonction lors du déploiement.

Environnement d'exécution

L'environnement d'exécution comprend l'exécution, le système d'exploitation, les packages et une bibliothèque appelant votre fonction.

Node.js 18 et versions ultérieures utilisent un environnement d'exécution basé sur Ubuntu 22.04. Les versions antérieures à Node.js 18 sont basées sur Ubuntu 18.04. Pour plus d'informations, consultez la section Environnement d'exécution des fonctions Cloud Run.

La bibliothèque qui appelle votre fonction est le framework des fonctions Node.js.

Structure du code source

Pour que les fonctions Cloud Run trouvent la définition de votre fonction, chaque environnement d'exécution a certaines exigences en matière de structuration pour votre code source. Pour en savoir plus, consultez la page Écrire des fonctions Cloud Run.

Spécifier des dépendances

Vous pouvez spécifier des dépendances pour vos fonctions en les répertoriant dans un fichier package.json. Pour en savoir plus, consultez la page Spécifier des dépendances dans Node.js.

Script de compilation NPM

Par défaut, l'environnement d'exécution Node.js exécute npm run build si un script build est détecté dans le projet package.json. Si vous avez besoin d'exercer un contrôle supplémentaire sur vos étapes de compilation avant de démarrer votre application, vous pouvez fournir une étape de compilation personnalisée en ajoutant un script gcp-build à votre fichier package.json.

Vous pouvez empêcher votre compilation d'exécuter le script npm run build de l'une des manières suivantes :

  • En ajoutant un script gcp-build avec une valeur vide dans votre fichier package.json : "gcp-build":"".

  • En définissant la variable d'environnement de compilation GOOGLE_NODE_RUN_SCRIPTS sur la chaîne vide pour empêcher tous les scripts de s'exécuter.

Exécution asynchrone de la fonction

Lorsque vous travaillez avec des tâches asynchrones qui impliquent des rappels ou des objets Promise, vous devez explicitement informer l'environnement d'exécution que votre fonction a terminé l'exécution de ces tâches. Vous pouvez effectuer cette opération de différentes manières, comme indiqué dans les exemples suivants. L'essentiel est que votre code attende que la tâche asynchrone ou Promise se termine avant de renvoyer, faute de quoi le composant asynchrone de votre fonction risque d'être interrompu avant qu'il ne se termine.

Fonctions basées sur les événements

Renvoi implicite

  exports.implicitlyReturning = async (event, context) => {
    return await asyncFunctionThatReturnsAPromise();
  };

Renvoi explicite

  exports.explicitlyReturning = function (event, context) {
    return asyncFunctionThatReturnsAPromise();
  };

Fonctions HTTP

Node.js

// OK: await-ing a Promise before sending an HTTP response
await Promise.resolve();

// WRONG: HTTP functions should send an
// HTTP response instead of returning.
return Promise.resolve();

// HTTP functions should signal termination by returning an HTTP response.
// This should not be done until all background tasks are complete.
res.send(200);
res.end();

// WRONG: this may not execute since an
// HTTP response has already been sent.
return Promise.resolve();

Utiliser un middleware pour gérer les requêtes HTTP

Afin de simplifier le traitement des requêtes HTTP, les fonctions Cloud Run HTTP Node.js fournissent des objets request et response compatibles avec ExpressJS. Les fonctions Cloud Run lisent automatiquement le corps de la requête, vous recevrez donc toujours le corps d'une requête indépendamment du type de contenu. Ainsi, les requêtes HTTP doivent être considérées comme ayant été entièrement lues au moment de l'exécution de votre code. L'imbrication avec des applications ExpressJS est possible à condition de prendre cela en compte. En effet, certains composants middleware ne s'attendant pas à ce que le corps d'une requête soit préalablement lu risquent de ne pas se comporter comme prévu.

Utiliser des modules ES

Les modules ECMAScript (modules ES ou ESM) sont une fonctionnalité standard TC39 non signalée dans Node version 14 et ultérieure, qui permet de charger des modules JavaScript. Contrairement à CommonJS, ESM fournit une API asynchrone pour le chargement de modules. Il fournit également une amélioration appréciée de la syntaxe via les instructions import et export, qui peuvent être utilisées dans une fonction Cloud Run au lieu d'instructions require.

Pour utiliser ESM dans une fonction Cloud Run, vous devez déclarer "type": "module" dans votre fichier package.json.

{
  ...
  "type": "module",
  ...
}

Vous pouvez alors utiliser les instructions import et export.