Passer des fonctions Node.js de 1re génération à celles de 2e génération

Les applications qui utilisent des fonctions de 1re génération doivent envisager de migrer vers la 2e génération en suivant les instructions de ce guide. Les fonctions de 2e génération utilisent Cloud Run pour offrir de meilleures performances, une meilleure configuration, une meilleure surveillance, et plus encore.

Les exemples de ce document supposent que vous utilisez JavaScript avec des modules CommonJS (importations de style require), mais les mêmes principes s'appliquent à JavaScript avec ESM (importations de style import … from) et à TypeScript.

Le processus de migration

Les fonctions de 1re et 2e génération peuvent coexister dans le même fichier. Cela vous permet de migrer votre codebase progressivement, lorsque vous êtes prêt. Nous vous recommandons de migrer une fonction à la fois, en effectuant des tests et des vérifications avant de continuer.

Vérifier les versions de Firebase CLI et de firebase-function

Assurez-vous d'utiliser au moins la version Firebase de CLI 12.00 et la version firebase-functions de 4.3.0. Toute version plus récente sera compatible avec la 2e génération ainsi qu'avec la 1re génération.

Mettre à jour les importations

Les fonctions de 2e génération importent à partir du sous-package v2 du SDK firebase-functions. Ce chemin d'importation différent est tout ce dont la Firebase CLI a besoin pour déterminer s'il faut déployer le code de votre fonction en tant que fonction de 1re ou de 2e génération.

Le sous-package v2 est modulaire. Nous vous recommandons de n'importer que le module spécifique dont vous avez besoin.

Avant : 1re génération

const functions = require("firebase-functions/v1");

Après : 2e génération

// explicitly import each trigger
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

Mettre à jour les définitions de déclencheurs

Étant donné que le SDK de 2e génération privilégie les importations modulaires, mettez à jour les définitions de déclencheurs pour refléter les modifications d'importations de l'étape précédente.

Les arguments transmis aux rappels de certains déclencheurs ont changé. Dans cet exemple, notez que les arguments du rappel onDocumentCreated ont été regroupés dans un seul objet event. De plus, certains déclencheurs disposent de nouvelles fonctionnalités de configuration pratiques, comme l'option cors du déclencheur onRequest.

Avant : 1re génération

const functions = require("firebase-functions/v1");

exports.date = functions.https.onRequest((req, res) => {
  // ...
});

exports.uppercase = functions.firestore
  .document("my-collection/{docId}")
  .onCreate((change, context) => {
    // ...
  });

Après : 2e génération

const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

exports.date = onRequest({cors: true}, (req, res) => {
  // ...
});

exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  /* ... */
});

Minimiser les efforts de réécriture avec la déstructuration JavaScript

Si vos fonctions comportent des corps complexes qui dépendent fortement du contexte de 1re génération ou de paramètres spécifiques au fournisseur (comme message ou snapshot), vous pouvez utiliser les assistants de compatibilité de 1re génération intégrés au SDK de 2e génération.

Le SDK de 2e génération corrige automatiquement l'objet d'événement avec des getters qui correspondent aux signatures de 1re génération. Cela vous permet d'utiliser la déstructuration JavaScript pour extraire ces propriétés directement dans la signature du gestionnaire, ce qui minimise la nécessité de réécrire la logique de votre fonction.

Documentation de référence sur le mappage des fournisseurs

Fournisseur Arguments de 1re génération Déstructuration d'événements corrigés de 2e génération
Pub/Sub (message, context) ({ message, context }) => { ... }
Firestore (snapshot, context) ({ snapshot, context }) => { ... }
Stockage (object, context) ({ object, context }) => { ... }
Realtime Database (snapshot, context) ({ snapshot, context }) => { ... }
Remote Config (version, context) ({ version, context }) => { ... }
Planificateur (context) ({ context }) => { ... }
File d'attente de tâches (data, context) ({ data, context }) => { ... }

Avant (1re génération) :

export const myPubSubV1 = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  const data = message.json;
  const eventId = context.eventId;
  // ... rest of the logic
});

Nouvelle alternative (2e génération avec déstructuration) :

import { onMessagePublished } from "firebase-functions/v2/pubsub";

export const myPubSubV2 = onMessagePublished("my-topic", ({ message, context }) => {
  // No need to change the function body!
  const data = message.json;      // Uses v1 Message wrapper
  const eventId = context.eventId; // Uses v1 EventContext map
  // ... rest of the logic
});

Utiliser une configuration paramétrée

Les fonctions de 2e génération abandonnent la prise en charge de functions.config au profit d'une interface plus sécurisée pour définir des paramètres de configuration de manière déclarative dans votre codebase. Avec le nouveau module params, la CLI bloque le déploiement, sauf si tous les paramètres ont une valeur valide, ce qui garantit qu'une fonction n'est pas déployée avec une configuration manquante.

Avant : 1re génération

const functions = require("firebase-functions/v1");

exports.getQuote = functions.https.onRequest(async (req, res) => {
  const quote = await fetchMotivationalQuote(functions.config().apiKey);
  // ...
});

Après : 2e génération

const {onRequest} = require("firebase-functions/v2/https");
const {defineSecret} = require("firebase-functions/params");

// Define the secret parameter
const apiKey = defineSecret("API_KEY");

exports.getQuote = onRequest(
  // make the secret available to this function
  { secrets: [apiKey] },
  async (req, res) => {
    // retrieve the value of the secret
    const quote = await fetchMotivationalQuote(apiKey.value());
    // ...
  }
);

Si vous disposez d'une configuration d'environnement existante avec functions.config, migrez cette configuration dans le cadre de votre mise à niveau vers la 2e génération.

L'API functions.config est obsolète et sera mise hors service en mars 2027. Après cette date, les déploiements avec functions.config échoueront.

Pour éviter les échecs de déploiement, migrez votre configuration vers Cloud Secret Manager à l'aide de Firebase CLI. Cette méthode est fortement recommandée, car elle constitue le moyen le plus efficace et le plus sécurisé de migrer votre configuration.

  1. Exporter la configuration avec Firebase CLI

    Utilisez la commande config export pour exporter votre configuration d'environnement existante vers un nouveau secret dans Cloud Secret Manager :

    $ firebase functions:config:export
i  This command retrieves your Runtime Config values (accessed via functions.config())
   and exports them as a Secret Manager secret.

i  Fetching your existing functions.config() from your project...  ✔
   Fetched your existing functions.config().

i  Configuration to be exported:
⚠  This may contain sensitive data. Do not share this output.

{
   ...
}

✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG

✔  Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```

  2. Mettre à jour le code de la fonction pour lier les secrets

    Pour utiliser la configuration stockée dans le nouveau secret de Cloud Secret Manager, utilisez l'API defineJsonSecret dans la source de votre fonction. Assurez-vous également que les secrets sont liés à toutes les fonctions qui en ont besoin.

    Avant

    const functions = require("firebase-functions/v1");

exports.myFunction = functions.https.onRequest((req, res) => {
  const apiKey = functions.config().someapi.key;
  // ...
});

    Après

    const { onRequest } = require("firebase-functions/v2/https");
const { defineJsonSecret } = require("firebase-functions/params");

const config = defineJsonSecret("RUNTIME_CONFIG");

exports.myFunction = onRequest(
  // Bind secret to your function
  { secrets: [config] },
  (req, res) => {
    // Access secret values via .value()
    const apiKey = config.value().someapi.key;
    // ...
});

  3. Déployer des fonctions

    Déployez vos fonctions mises à jour pour appliquer les modifications et lier les autorisations secrètes.

    firebase deploy --only functions:<your-function-name>

Définir des options d'exécution

La configuration des options d'exécution a changé entre la 1re et la 2e génération. La 2e génération ajoute également une nouvelle fonctionnalité permettant de définir des options pour toutes les fonctions.

Avant : 1re génération

const functions = require("firebase-functions/v1");

exports.date = functions
  .runWith({
    // Keep 5 instances warm for this latency-critical function
    minInstances: 5,
  })
  // locate function closest to users
  .region("asia-northeast1")
  .https.onRequest((req, res) => {
    // ...
  });

exports.uppercase = functions
  // locate function closest to users and database
  .region("asia-northeast1")
  .firestore.document("my-collection/{docId}")
  .onCreate((change, context) => {
    // ...
  });

Après : 2e génération

const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions/v2");

// locate all functions closest to users
setGlobalOptions({ region: "asia-northeast1" });

exports.date = onRequest({
    // Keep 5 instances warm for this latency-critical function
    minInstances: 5,
  }, (req, res) => {
  // ...
});

exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  /* ... */
});

Mettre à jour le compte de service par défaut (facultatif)

Alors que les fonctions de 1re génération utilisent le compte de service App Engine par défaut pour autoriser l'accès aux API Firebase, les fonctions de 2e génération utilisent le compte de service Compute Engine par défaut. Cette différence peut entraîner des problèmes d'autorisations pour les fonctions migrées vers la 2e génération dans les cas où vous avez accordé des autorisations spéciales au compte de service de 1re génération. Si vous n'avez modifié aucune autorisation de compte de service, vous pouvez ignorer cette étape.

La solution recommandée consiste à attribuer explicitement le compte de service App Engine par défaut de 1re génération existant aux fonctions que vous souhaitez migrer vers la 2e génération, en remplaçant la valeur par défaut de la 2e génération. Pour ce faire, assurez-vous que chaque fonction migrée définit la valeur correcte pour serviceAccountEmail :

const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions");

// Use the App Engine default service account for all functions
setGlobalOptions({serviceAccountEmail: '<my-project-number>@<wbr>appspot.gserviceaccount.com'});

// Now I use the App Engine default service account.
exports.date = onRequest({cors: true}, (req, res) => {
  // ...
});

// I do too!
exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  // ...
});

Vous pouvez également modifier les détails du compte de service pour qu'ils correspondent à toutes les autorisations nécessaires sur le compte de service App Engine par défaut (pour la 1re génération) et sur le compte de service Compute Engine par défaut (pour la 2e génération).

Utiliser la simultanéité

Un avantage significatif des fonctions de 2e génération est la capacité d'une seule instance de fonction à traiter plusieurs requêtes à la fois. Cela peut réduire considérablement le nombre de démarrages à froid rencontrés par les utilisateurs finaux. Par défaut, la simultanéité est définie sur 80, mais vous pouvez la définir sur n'importe quelle valeur comprise entre 1 et 1 000 :

const {onRequest} = require("firebase-functions/v2/https");

exports.date = onRequest({
    // set concurrency value
    concurrency: 500
  },
  (req, res) => {
    // ...
});

Le réglage de la simultanéité peut améliorer les performances et réduire le coût des fonctions. Pour en savoir plus sur la simultanéité, consultez Autoriser les requêtes simultanées.

Auditer l'utilisation des variables globales

Les fonctions de 1re génération écrites sans tenir compte de la simultanéité peuvent utiliser des variables globales qui sont définies et lues à chaque requête. Lorsque la simultanéité est activée et qu'une seule instance commence à traiter plusieurs requêtes à la fois, cela peut introduire des bugs dans votre fonction, car les requêtes simultanées commencent à définir et à lire des variables globales simultanément.

Lors de la mise à niveau, vous pouvez définir le processeur de votre fonction sur gcf_gen1 et définir concurrency sur 1 pour restaurer le comportement de la 1re génération :

const {onRequest} = require("firebase-functions/v2/https");

exports.date = onRequest({
    // TEMPORARY FIX: remove concurrency
    cpu: "gcf_gen1",
    concurrency: 1
  },
  (req, res) => {
    // ...
});

Toutefois, cette solution n'est pas recommandée à long terme, car elle annule les avantages en termes de performances des fonctions de 2e génération. Auditez plutôt l'utilisation des variables globales dans vos fonctions et supprimez ces paramètres temporaires lorsque vous êtes prêt.

Migrer le trafic vers les nouvelles fonctions de 2e génération

Comme lorsque vous modifiez la région ou le type de déclencheur d'une fonction, vous devez attribuer un nouveau nom à la fonction de 2e génération et migrer lentement le trafic vers celle-ci.

Il n'est pas possible de mettre à niveau une fonction de la 1re à la 2e génération avec le même nom et d'exécuter firebase deploy. Cela entraînera l'erreur suivante :

Upgrading from GCFv1 to GCFv2 is not yet supported. Please delete your old function or wait for this feature to be ready.

La stratégie de migration dépend du type de déclencheur utilisé par votre fonction.

Pour les déclencheurs appelables, de file d'attente de tâches et HTTP

Ces déclencheurs sont des appels directs. Étant donné que la fonction de 2e génération aura un nouveau nom (et une nouvelle URL pour les déclencheurs HTTP), vous pouvez migrer le trafic en mettant à jour les clients.

  1. Renommez la fonction dans votre code (par exemple, remplacez myCallable par myCallableV2).
  2. Déployez la fonction. Les fonctions de 1re et 2e génération sont désormais en cours d'exécution.
  3. Mettez à jour le code ou l'appelant de votre client pour qu'il pointe vers le nouveau nom ou la nouvelle URL de la fonction de 2e génération.
  4. Une fois que tout le trafic a été transféré vers la nouvelle fonction, supprimez la fonction de 1re génération à l'aide de la commande firebase functions:delete de Firebase CLI.

Pour les déclencheurs en arrière-plan (Pub/Sub, Cloud Firestore, Cloud Storage, etc.)

Les déclencheurs en arrière-plan répondent aux événements de votre projet. Pour éviter de manquer des événements pendant la transition, vous devez exécuter temporairement les fonctions de 1re et 2e génération côte à côte.

Pendant la période de transition, les deux fonctions se déclencheront sur le même événement. Cela signifie que votre logique métier s'exécutera deux fois par événement. Assurez-vous que votre fonction est idempotente avant de continuer.

Étape 1 : Ajouter la fonction de 2e génération à côté de la fonction de 1re génération

Conservez votre fonction de 1re génération existante dans votre code et ajoutez la fonction de 2e génération qui écoute la même source d'événements.

Conseil : Utiliser un passthrough pour la validation Pour éviter de dupliquer votre logique métier dans votre codebase pendant la transition, ou pour vérifier que la fonction de 2e génération reçoit correctement les événements avant de lui faire entièrement confiance, faites de la fonction de 2e génération un passthrough qui appelle la fonction de 1re génération à l'aide de la méthode run.

import * as functions from "firebase-functions/v1";
import { onMessagePublished } from "firebase-functions/v2/pubsub";

// --- Existing 1st gen function ---
export const myPubSub = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  console.log("V1 handler running for event:", context.eventId);
  // ... existing v1 function logic ...
});

// --- New v2 passthrough function ---
export const myPubSubV2 = onMessagePublished("my-topic", async ({ message, context }) => {
   console.log("v2 handler triggering V1 for event:", context.eventId);
   // Call the v1 function's handler
   await myPubSub.run(message, context);
});

Étape 2 : Déployer les deux fonctions

Exécutez firebase deploy. Les deux fonctions sont désormais actives et écoutent les mêmes événements.

Étape 3 : Vérifier que la fonction de 2e génération reçoit du trafic

Surveillez les journaux des deux fonctions. Assurez-vous que la fonction de 2e génération est appelée pour tous les événements et que les appels réussissent.

Étape 4 : Déplacer la logique complète vers la fonction de 2e génération

Une fois que vous êtes sûr, déplacez la logique métier réelle de la fonction de 1re génération vers le corps de la fonction de 2e génération. Si vous avez utilisé la méthode passthrough, supprimez le appel à myPubSub.run().

import * as functions from "firebase-functions/v1";
import { onMessagePublished } from "firebase-functions/v2/pubsub";

// --- Existing v1 function (to be removed next) ---
export const myPubSub = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  console.log("v1 handler running for event:", context.eventId);
  // ... existing v1 function logic ...
});

// --- New v2 function with full logic ---
export const myPubSubV2 = onMessagePublished("my-topic", ({ message, context }) => {
   console.log("v2 handler running for event:", context.eventId);
   // ... existing v1 function logic WAS MOVED HERE ...
});

Déployez cette modification.

Étape 5 : Annuler le déploiement de la fonction de 1re génération

Supprimez la définition de la fonction de 1re génération de votre code et redéployez-la. La CLI vous invite à supprimer la fonction de 1re génération de Google Cloud.

import { onMessagePublished } from "firebase-functions/v2/pubsub";

// --- V1 function definition REMOVED ---

// --- New v2 function with full logic ---
export const myPubSubV2 = onMessagePublished("my-topic", ({ message, context }) => {
   console.log("v2 handler running for event:", context.eventId);
   // ... existing v1 function logic ...
});