Migrer des extensions Firebase vers Cloud Functions

Ce guide vous explique comment migrer vos extensions de l'environnement Firebase Extensions obsolète vers une fonction que vos utilisateurs installent et déploient dans leur propre codebase Cloud Functions pour Firebase (2e génération).

Il s'agit du chemin de migration recommandé. Firebase gérera une liste d'extensions avec des équivalents npm officiels. Ce guide vous explique comment créer le vôtre.

Tout au long de ce guide, l'extension Diffuser Cloud Firestore vers BigQuery (firestore-bigquery-export) est utilisée comme exemple. Chaque section se termine par un exemple concret qui montre à quoi ressemblait l'extension avant la migration et à quoi elle ressemble après, en tant que package @firebase-function-kits/firestore-bigquery-export.

Inscrivez-vous pour obtenir plus d'informations et d'aide sur la migration des extensions

Si vous avez des questions sur la migration depuis Firebase Extensions, vous pouvez nous contacter à l'adresse firebase-extensions-migrator-support-external@google.com. Nous enverrons également un e-mail à ce groupe lorsque nous mettrons à jour le guide avec plus d'informations sur l'empaquetage, les tests et la distribution de vos fonctions de 2e génération.

Pour rejoindre ce groupe, envoyez un message à firebase-extensions-migrator-support-external+subscribe@google.com. Vous recevrez un e-mail de demande d'adhésion. Vous devez répondre à cet e-mail, et non cliquer sur le bouton "Rejoindre ce groupe".

Avant de commencer

Pour effectuer cette migration comme décrit, vous utiliserez les fonctionnalités suivantes de Cloud Functions :

  • Configuration paramétrée. Chaque paramètre que vous déclarez dans extension.yaml devient un paramètre défini dans le code de votre package.

  • Rôles IAM déclaratifs et API requises Chaque rôle que vous déclarez dans extension.yaml devient un appel requiresRole(...), et chaque API devient un appel requiresAPI(...) dans le code de votre package. Au moment du déploiement, la CLI Firebase attribue les rôles déclarés à un compte de service d'exécution géré et active les API déclarées en votre nom.

  • Événements de cycle de vie pour les codebases Cloud Functions. Les codebases Cloud Functions sont désormais compatibles avec les événements de cycle de vie analogues à Firebase Extensions. Déclarez la configuration au moment de l'installation et de la mise à jour avec les hooks de cycle de vie afterFirstDeploy(...) et afterRedeploy(...). Ils remplacent les lifecycleEvents que vous déclarez dans extension.yaml.

Migrer la source Firebase Extensions vers une fonction de 2e génération

(Facultatif) Migration automatisée avec la compétence d'agent Firebase

Vous pouvez automatiser les étapes 1 à 8 (inventaire des ressources, déclenchement des mises à niveau, conversions de paramètres et de secrets, IAM déclaratif, hooks de cycle de vie et génération du fichier README du package) à l'aide de la compétence d'agent IA extension-to-functions-codebase officielle.

Installer la compétence

Si vous ou votre assistant de codage IA (Gemini dans Firebase, Cursor, Claude Code, GitHub Copilot) n'avez pas encore installé la compétence, exécutez la commande suivante à l'aide de la CLI des compétences :

npx skills add firebase/agent-skills --skill extension-to-functions-codebase

Une fois la compétence installée dans votre projet, votre assistant de codage IA suit automatiquement ses règles de migration et ses étapes de transformation. Vous pouvez utiliser le prompt suivant :

"Veuillez migrer cette extension Firebase vers un package de kit de fonctions de 2e génération publiable en suivant les instructions de la compétence extension-to-functions-codebase."

1. Inventorier l'extension

Commencez par dresser un inventaire de votre extension : une liste complète de tout ce que l'extension déclare, fournit et documente, afin que chaque comportement ait une destination définie dans la fonction de 2e génération et que rien ne soit perdu lors de la migration.

Examinez chacun des éléments suivants et notez ce que vous trouvez :

  • extension.yaml, qui déclare vos paramètres, fonctions, événements, rôles IAM, API requises, secrets et hooks de cycle de vie.

  • functions/, qui contient le code de votre fonction, les dépendances, la configuration de compilation, les déclencheurs et les fonctions de file d'attente de tâches.

  • README.md, PREINSTALL.md et POSTINSTALL.md, qui contiennent les étapes de configuration, les avertissements et les notes de facturation.

  • scripts/, qui contient tous les utilitaires d'importation, de remplissage, IAM, de réparation ou de migration, ainsi que tous les autres outils que vous fournissez avec l'extension.

Ensuite, pour chaque élément de extension.yaml, déterminez où il doit être placé dans le package npm :

  • Convertissez la configuration utilisateur en paramètres Cloud Functions (étape 4).

  • Convertissez les secrets en secrets Cloud Functions (étape 4).

  • Convertissez les rôles IAM en déclarations requiresRole(...) (étape 6).

  • Convertissez les API Google requises en déclarations requiresAPI(...), le cas échéant (étape 6).

  • Convertissez les hooks d'installation et de mise à jour en déclarations afterFirstDeploy(...) et afterRedeploy(...) (étape 7).

  • Convertissez les ID d'instance de EXT_INSTANCE_ID en FIREBASE_KIT_INSTANCE_ID (étape 4).

Exemple : Diffuser Cloud Firestore vers BigQuery

La lecture de firestore-bigquery-export/extension.yaml et de functions/ produit cet inventaire :

Dans extension.yaml Nombre/Valeur Où vont-elles ?
params 25 (COLLECTION_PATH, DATASET_ID, TABLE_ID, DATASET_LOCATION, VIEW_TYPE, …) Cloud Functions paramètres (étape 4)
apis bigquery.googleapis.com requiresAPI(...) (Étape 6)
roles bigquery.dataEditor, datastore.user, bigquery.user requiresRole(...) (Étape 6)
resources 1 déclencheur d'événement (fsexportbigquery) + fonctions de file d'attente de tâches (initBigQuerySync, setupBigQuerySync) Fonctions du package exporté (étape 3)
lifecycleEvents onInstall → initBigQuerySync ; onUpdate/onConfigure → setupBigQuerySync afterFirstDeploy / afterRedeploy (Étape 7)
ID d'instance Non utilisé (aucune lecture EXT_INSTANCE_ID) Rien à migrer
scripts/ import/ (remplissage), gen-schema-view/ Conservés en tant que scripts (hors du champ d'application ici)

Analyse L'extension ne déclare aucun paramètre type: secret. Il n'y a donc rien à migrer pour les secrets à l'étape 4. Le déclencheur d'événement est déjà de 2e génération. Seules les fonctions de file d'attente de tâches sont encore de 1re génération (pertinent à l'étape 3).

2. Mettre à jour package.json

Mettez à jour le fichier package.json de votre extension. Si vous migrez une extension, il peut s'agir de la racine package.json. Si vous migrez de nombreuses extensions dans un même dépôt, attribuez à chacune son propre package.

Versions minimales du SDK : déclarez firebase-functions >= 7.4.0 et firebase-admin >= 14.2.0 comme dépendances. Déclarez également votre version de firebase-functions en tant que dépendance de pairs, afin que le projet Cloud Functions de vos utilisateurs dispose de la même version du SDK que celle avec laquelle votre bibliothèque a été écrite.

{
  "name": "<package-name>",
  "version": "1.0.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": "22"
  },
  "peerDependencies": {
    "firebase-functions": "^7.4.0"
  },
  "dependencies": {
    "firebase-functions": "^7.4.0",
    "firebase-admin": "^14.2.0"
  }
}

Exemple : Diffuser Cloud Firestore vers BigQuery

Avant Le fichier functions/package.json de l'extension est privé, nomme l'ID de l'extension et déclare firebase-functions comme dépendance directe :

{
  "name": "firestore-bigquery-export",
  "main": "lib/index.js",
  "private": true,
  "dependencies": {
    "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
    "firebase-admin": "^14.2.0",
    "firebase-functions": "^6.3.2"
  }
}

Après Un package publiable : nom limité, mappage exports et firebase-functions déplacé vers peerDependencies :

{
  "name": "@firebase-function-kits/firestore-bigquery-export",
  "version": "0.1.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": "22"
  },
  "peerDependencies": {
    "firebase-functions": "^7.4.0"
  },
  "dependencies": {
    "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
    "firebase-admin": "^14.2.0",
    "firebase-functions": "^7.4.0"
  }
}

3. Mettre à niveau des fonctions de la 1re génération vers la 2e génération

Si votre extension exporte toujours des fonctions de 1re génération, convertissez chaque déclencheur en son équivalent de 2e génération. Importez à partir des modules firebase-functions/... et transmettez les paramètres d'exécution dans les options du déclencheur.

Consultez le guide de mise à niveau vers Cloud Functions (2e génération). Vous pouvez notamment minimiser les efforts de réécriture en utilisant la déstructuration d'événements corrigée de 2e génération et éviter de réécrire la logique de votre fonction, car le SDK de 2e génération expose les paramètres v1 en tant que champs dans l'objet d'événement, ce qui vous permet d'utiliser des paramètres déstructurés/nommés et de conserver votre logique métier inchangée.

Avant 1re génération :

import * as functions from "firebase-functions/v1";

export const sync = functions.firestore
  .document("{collectionId}/{documentId}")
  .onWrite(async (change, context) => {
    await handleWrite(change.before, change.after, context.params);
  });

Après 2e génération :

import { onDocumentWritten } from "firebase-functions/firestore";

export const syncV2 = onDocumentWritten(
  { document: "{collectionId}/{documentId}" },
  async ({ change, context }) =>
    await handleWrite(change.before, change.after, context.params)
);

Consultez la comparaison des versions de Cloud Functions pour obtenir la liste complète des différences entre les fonctions de 1re génération et de 2e génération.

Une différence significative entre les fonctions de 1re et de 2e génération est que les fonctions de 2e génération doivent être colocalisées avec leurs ressources de déclencheur. Lorsque les utilisateurs migrent d'une extension utilisant des fonctions de 1re génération vers un kit utilisant des fonctions de 2e génération, ils peuvent avoir besoin de modifier l'emplacement des fonctions pour répondre à cette exigence.

Les emplacements Cloud Functions sélectionnés par vos utilisateurs risquent de ne plus fonctionner pendant la migration, car l'emplacement existant est conservé. Si les fonctions déclenchées par un événement de votre extension reposaient sur l'emplacement des fonctions fourni par l'utilisateur, nous vous suggérons d'ajouter un nouveau paramètre à votre extension pour collecter l'emplacement du déclencheur d'événement et le mapper au nouvel emplacement de la fonction.

Exemple : Diffuser Cloud Firestore vers BigQuery

defineString("DATABASE_REGION", {
  label: "Firestore Instance Location",
  description:
    "Where is the Firestore database located? You can check your current database location at https://console.cloud.google.com/firestore/databases. The functions in this kit deploy to the Cloud Run region closest to this location.",
  input: select({
    "Multi-region (Europe - Belgium and Netherlands)": "eur3",
    "Multi-region (United States)": "nam5",
    "Multi-region (Iowa, North Virginia, and Oklahoma)": "nam7",
    "Iowa (us-central1)": "us-central1",
    // More locations...
  })
});

// Firestore multi-region locations are not Cloud Run regions; deploying a
// function to one hard-fails, so they map to a region inside the multi-region.
const MULTI_REGION_TO_FUNCTION_REGION: Record<string, string> = {
  nam5: "us-central1",
  nam7: "us-central1",
  eur3: "europe-west1",
};

/**
 * Maps a Firestore database location to the Cloud Run region the functions
 * should deploy to. The lookup is case-insensitive and ignores surrounding
 * whitespace, as the CLI's own region handling is. Regional locations pass
 * through lowercased; an unset or blank location returns `undefined`, meaning
 * the functions declare no region.
 */
export function firestoreLocationToFunctionRegion(
  location: string | undefined
): string | undefined {
  const normalized = location?.trim().toLowerCase();
  if (!normalized) {
    return undefined;
  }
  return MULTI_REGION_TO_FUNCTION_REGION[normalized] ?? normalized;
}

const functionRegion = firestoreLocationToFunctionRegion(
  process.env.DATABASE_REGION
);

export const fsexportbigquery = onDocumentWritten(
  {
    region: functionRegion,
    // Other configuration
  },
  (event) => handleDocumentWrite(event, getHandlerContext())
);

Lors du premier déploiement du kit, les utilisateurs seront invités à saisir leur DATABASE_REGION, et les fonctions seront déployées dans l'functionRegion correspondant ci-dessus, ce qui résoudra les problèmes d'emplacement pour leurs fonctions déclenchées par un événement de 2e génération.

4. Convertir les paramètres et les secrets de l'extension

Paramètres

Chaque paramètre que vous déclarez dans extension.yaml devient un paramètre Cloud Functions.

Convertissez les lectures d'environnement directes :

const collectionPath = process.env.COLLECTION_PATH;

en Cloud Functions paramètres :

import { defineString } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";

const collectionPath = defineString("COLLECTION_PATH");

// Pass the param directly when used as a placeholder (e.g. trigger path)
export const sync = onDocumentWritten(
  { document: collectionPath },
  async (event) => {
    // Call .value() to read the string inside a handler
    const path = collectionPath.value();
    await handleWrite(path, event);
  }
);

Utilisez collectionPath.value() pour lire la chaîne dans un gestionnaire. Utilisez collectionPath directement là où un espace réservé est attendu, par exemple un chemin de déclencheur de fonction.

La CLI Firebase découvre vos paramètres et lit leurs valeurs à partir de .env, .env.<projectId> ou invite vos utilisateurs à les saisir lors du déploiement. Conservez les mêmes noms de paramètres afin que les valeurs d'une installation existante soient reportées.

Il est important de ne pas modifier les noms des paramètres déclarés dans votre code. La migration des extensions conserve automatiquement les valeurs de paramètres existantes des utilisateurs finaux, mais uniquement lorsque les noms ne sont pas modifiés.

Exemple : Diffuser Cloud Firestore vers BigQuery

Avant Un paramètre déclaré dans extension.yaml, lu comme une variable d'environnement brute dans config.ts :

# extension.yaml
- param: COLLECTION_PATH
  label: Collection path
  type: string
  required: true
// functions/src/config.ts
collectionPath: process.env.COLLECTION_PATH,

Après Un fichier defineString : la CLI le détecte et lit .env :

// src/config.ts
import { defineString } from "firebase-functions/params";

collectionPath: defineString("COLLECTION_PATH", {
  label: "Collection path",
  // We now support "nonEmpty: true" to ensure a value other than the empty string
  // is entered, analogous to "required: true" in extension.yaml
  input: { text: { nonEmpty: true } }
}),

Le nom du paramètre reste inchangé, de sorte qu'un .env existant continue de fonctionner.

ID d'instance

Les extensions lisent leur ID d'instance à partir de EXT_INSTANCE_ID, injecté par l'environnement d'exécution des extensions. Les kits de fonctions lisent leur ID d'instance à partir de FIREBASE_KIT_INSTANCE_ID, que la CLI Firebase définit pour chaque instance de kit sur la clé de l'instance dans le mappage instances de firebase.json. La CLI la fournit lors de la découverte au moment du déploiement, dans l'émulateur et aux fonctions déployées.

L'ID d'instance n'est pas un paramètre. Ne le déclarez donc pas avec defineString. En fait, FIREBASE_... est un préfixe réservé dans les fichiers .env. Les utilisateurs ne pourront donc pas le définir ni le remplacer. Les valeurs injectées par la CLI ne sont pas visibles par le système de paramètres. Lisez-la directement à partir de l'environnement :

// Before
const instanceId = process.env.EXT_INSTANCE_ID;

// After
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;

La variable ne sera définie que lorsque votre package sera déployé en tant que kit. Si votre code est également déployé en tant que codebase autonome (voir l'étape 9), traitez-le comme facultatif ou échouez rapidement avec un message clair lorsqu'il est manquant. Si votre extension exposait l'ID d'instance en tant que paramètre visible par l'utilisateur, vous devez supprimer ce paramètre, car la CLI Firebase possède désormais la valeur.

Exemple concret : Supprimer les données utilisateur

(L'extension Stream Cloud Firestore to BigQuery ne lit pas son ID d'instance. Il n'y a donc rien à migrer ici. L'extension Delete User Data l'utilise pour nommer ses sujets Pub/Sub.)

Avant Lisez-la en tant que variable d'environnement brute dans config.ts avec le préfixe ext- utilisé par Extensions pour ses ressources :

// functions/src/config.ts
discoveryTopic: `ext-${process.env.EXT_INSTANCE_ID}-discovery`,
deletionTopic: `ext-${process.env.EXT_INSTANCE_ID}-deletion`,

Après Une simple lecture process.env de FIREBASE_KIT_INSTANCE_ID utilisée pour deux paramètres ordinaires afin que les utilisateurs puissent remplacer les noms de thèmes :

// src/config.ts
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;

// Non-empty defaults so Pub/Sub trigger bindings resolve during deploy
// discovery without freezing an empty topic name into the manifest.
discoveryTopicName: defineString("DISCOVERY_TOPIC_NAME", {
  default: `kit-${instanceId}-discovery`,
}),
deletionTopicName: defineString("DELETION_TOPIC_NAME", {
  default: `kit-${instanceId}-deletion`,
}),

Les valeurs par défaut ne doivent pas être vides, car les liaisons de déclencheur sont résolues au moment de la découverte. Une valeur par défaut vide serait écrite dans le fichier manifeste de déploiement en tant que nom de sujet. Le kit est également protégé contre l'exécution en dehors du contexte d'un kit. Si la variable est manquante, la valeur par défaut au niveau du module est évaluée à kit-undefined-discovery. Le chargeur de configuration échoue alors avec une erreur explicative :

// ...
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
if (!instanceId) {
  throw new Error(
    "FIREBASE_KIT_INSTANCE_ID is not set. It is provided automatically to " +
      "kit instances by firebase-tools >= 15.32.0; deploy or emulate this " +
      "kit with a supported CLI version."
  );
}
// ...

Cette vérification s'exécute lorsqu'un gestionnaire résout sa configuration pour la première fois. Ainsi, une variable manquante génère une erreur d'exécution claire plutôt que des fonctions liées de manière silencieuse aux sujets kit-undefined-*. Pour rejeter le déploiement lui-même, effectuez la vérification au niveau du module afin qu'elle s'exécute pendant la découverte. Étant donné que la CLI dérive l'ID d'instance de firebase.json, il n'y a pas de INSTANCE_ID configurable, ni d'élément à synchroniser sur plusieurs instances.

Secrets

Dans extension.yaml, vous déclarez des secrets avec type: secret. L'environnement d'exécution des extensions les stocke et les lie, afin que le code de votre extension puisse lire directement process.env.PARAM_NAME. Dans un codebase Cloud Functions classique, vous déclarez et liez chaque secret explicitement :

import { defineSecret } from "firebase-functions/params";
import { onRequest } from "firebase-functions/https";

const apiKey = defineSecret("API_KEY");
export const fn = onRequest({ secrets: [apiKey] }, handler);

Une fois votre extension migrée vers un package/kit npm, les références de secrets sont gérées dans le fichier .env de l'utilisateur final. Il est important de ne pas modifier les noms des secrets déclarés dans votre code. Lors de la migration, les secrets des utilisateurs finaux sont migrés en conséquence.

Exemple : Déclencher un e-mail à partir de Cloud Firestore

Avant MAIL_COLLECTION et SMTP_PASSWORD sont lues en tant que variables d'environnement brutes dans config.ts :

# extension.yaml
- param: MAIL_COLLECTION
  label: Email documents collection
  type: string
  default: mail
  required: true

- param: SMTP_PASSWORD
  label: SMTP password
  type: secret
// functions/src/config.ts
mailCollection: process.env.MAIL_COLLECTION,
smtpPassword: process.env.SMTP_PASSWORD,

Après Un defineString et un defineSecret ; la CLI découvre les deux et lit à partir de .env :

import { defineString, defineSecret } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";

const mailCollection = defineString("MAIL_COLLECTION", {
  label: "Email documents collection",
  default: "mail"
});

const smtpPassword = defineSecret("SMTP_PASSWORD", { label: "SMTP password" });

export const processQueue = onDocumentWritten(
  { document: `${mailCollection}/{documentId}`, secrets: [smtpPassword] },
  async (event) => {
    const collection = mailCollection.value();
    const password = smtpPassword.value();
    // ...
  }
);

5. Migrer les appels internes de file d'attente de tâches

Certaines extensions mettent en file d'attente des tâches dans leurs propres files d'attente de tâches à partir de leur code de fonction, à l'aide de Firebase Admin SDK. Cela diffère de la réception d'une tâche distribuée (abordée dans les sections Mettre à niveau les fonctions et Convertir les hooks de cycle de vie). Ici, votre code est le producteur qui appelle queue.enqueue(...).

Les versions précédentes de Admin SDK nécessitaient que les extensions transmettent leur propre ID d'instance d'extension en tant que deuxième paramètre pour cibler une fonction de file d'attente de tâches dans la même extension. À partir de la version 14.2.0 de firebase-admin, cela n'est ni obligatoire, ni recommandé. L'API Task Queue cible désormais par défaut les files d'attente de tâches dans le même contexte (par exemple, une extension ou un kit). Vous pouvez supprimer ce paramètre de votre code en toute sécurité, à la fois en tant qu'extension et en tant que fonctions autonomes. Nous vous encourageons d'ailleurs à le faire. La suppression de ce paramètre garantit la portabilité et la compatibilité ascendante.

Tout le reste de l'appel de mise en file d'attente (le chemin d'accès à la ressource locations/<region>/functions/<name>, la charge utile de la tâche et votre logique de nouvelle tentative) reste inchangé.

Pour en savoir plus sur la mise en file d'attente des fonctions avec Cloud Tasks, consultez Mettre en file d'attente des fonctions avec Cloud Tasks.

Avant Extension de 1re génération :

import { getFunctions } from "firebase-admin/functions";

const queue = getFunctions().taskQueue(
  `locations/${config.location}/functions/syncBigQuery`,
  process.env.EXT_INSTANCE_ID, // extension instance ID, injected by the runtime
);
await queue.enqueue(taskData);

Après Extension de 2e génération :

import { getFunctions } from "firebase-admin/functions";

const queue = getFunctions().taskQueue(
  `locations/${process.env.FUNCTION_REGION}/functions/syncBigQuery`
);
await queue.enqueue(taskData);

Si votre appel de mise en file d'attente cible un codebase préfixé, le nom de la fonction découverte est également préfixé (par exemple, orders-syncBigQuery). Consultez Examiner et installer l'instance du kit de fonctions de remplacement et Tester en tant que kit de fonctions.

6. Déclarer les API et les rôles IAM requis

Déplacez les exigences IAM et API de votre extension de extension.yaml vers le code :

import { requiresAPI, requiresRole } from "firebase-functions";

requiresAPI("bigquery.googleapis.com", "Needed to write changelog rows");
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/bigquery.user");

Avec la sécurité déclarative, la CLI Firebase crée ou met à jour un compte de service d'exécution géré pour la codebase, et lui accorde l'ensemble de tous les rôles déclarés. Indiquez à vos utilisateurs que toutes les fonctions de la codebase s'exécutent avec ces rôles, sauf si l'API finale est compatible avec un modèle plus restreint.

Exemple : Diffuser Cloud Firestore vers BigQuery

Avant Déclaré dans extension.yaml ; l'environnement d'exécution des extensions a activé l'API et accordé les rôles à un compte géré :

apis:
  - apiName: bigquery.googleapis.com
roles:
  - role: bigquery.dataEditor
  - role: datastore.user
  - role: bigquery.user

Après Déclaré dans le code avec requiresAPI et requiresRole :

import { requiresAPI, requiresRole } from "firebase-functions";

requiresAPI(
  "bigquery.googleapis.com",
  "Needed to write changelog rows and views"
);
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/datastore.user");
requiresRole("roles/bigquery.user");

Si votre extension publie des événements Eventarc, vous devez également définir les rôles et les API requis pour publier des événements. Cette opération était auparavant gérée par les extensions sans qu'aucune modification ne soit requise dans votre extensions.yaml. Vous pouvez le faire de manière conditionnelle dans votre code afin que le kit ne demande ces autorisations que lorsqu'un canal Eventarc personnalisé est utilisé.

if (!!process.env.EVENTARC_CHANNEL) {
  requiresRole("roles/eventarc.publisher");
  requiresAPI(
    "eventarcpublishing.googleapis.com",
    "Publishes the extension's custom events to its Eventarc channel."
  );
}

7. Convertir les hooks de cycle de vie

Si votre extension appelle getExtensions().runtime() (par exemple, setProcessingState ou setFatalError), supprimez ces appels, car ils génèrent une erreur s'ils sont appelés à partir d'une fonction de 2e génération normalement déployée. L'état du cycle de vie est désormais géré par afterFirstDeploy et afterRedeploy, où ce suivi d'état n'est pas utilisé.

Firebase Extensions peut exécuter la configuration lorsqu'un utilisateur installe, met à jour ou reconfigure une extension. Dans votre package npm, déclarez des actions de cycle de vie équivalentes dans le code.

Pour une configuration ponctuelle :

import { afterFirstDeploy } from "firebase-functions/lifecycle";
import { onTaskDispatched } from "firebase-functions/tasks";

export const runInitialSetup = onTaskDispatched(async (request) => {
  await initializeResources(request.data);
});

afterFirstDeploy({
  task: {
    function: "runInitialSetup",
    body: {}
  }
});

Pour les mises à jour de configuration ou de code :

import { afterRedeploy } from "firebase-functions/lifecycle";

afterRedeploy({
  task: {
    function: "runInitialSetup",
    body: { reconcile: true }
  }
});

Rendez vos actions de cycle de vie idempotentes. Vos utilisateurs devront peut-être les réexécuter manuellement en cas d'échec de l'envoi ou de l'exécution :

firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME
firebase functions:lifecycle:run afterRedeploy CODEBASE_NAME

Exemple : Diffuser Cloud Firestore vers BigQuery

Avant lifecycleEvents en extension.yaml, en raison de l'environnement d'exécution des extensions :

lifecycleEvents:
  onInstall:
    function: initBigQuerySync
    processingMessage: Configuring BigQuery Sync.
  onUpdate:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync
  onConfigure:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync

Après Déclaré dans le code ; la tâche provisionne BigQuery lors du premier déploiement :

import { afterFirstDeploy, afterRedeploy } from "firebase-functions/lifecycle";

afterFirstDeploy({ task: { function: "initBigQuerySync" } });
afterRedeploy({ task: { function: "setupBigQuerySync" } });

Le provisionnement est idempotent. Par conséquent, une nouvelle exécution rapproche l'ensemble de données, la table et les vues. Les utilisateurs peuvent relancer manuellement l'exécution avec firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME.

8. Configuration des documents pour vos utilisateurs

Rédigez un fichier README qui explique au moins :

  • Valeurs .env requises par le package.
  • Les secrets requis par le package et la manière de migrer les valeurs de secrets existantes.
  • Rôles IAM que le package déclare avec requiresRole(...).
  • Les API Google que le package active ou requiert.
  • Les hooks de cycle de vie déclarés par le package et comment les réexécuter manuellement.
  • Remarques sur la facturation.
  • Ce qui a changé par rapport à l'extension d'origine.
  • Comment le package obtient son ID d'instance (FIREBASE_KIT_INSTANCE_ID défini par la CLI) et que toutes les fonctions de l'instance sont déployées avec un préfixe kit-<instanceId>-.

Exemple : Diffuser Cloud Firestore vers BigQuery

Le package README fournit un tableau concret des modifications :

Problème En tant qu'extension En tant que @firebase-function-kits/firestore-bigquery-export
Configuration Paramètres d'extension Cloud Functions paramètres via .env
IAM Accordée par des extensions requiresRole(...), appliqué au déploiement
Provisionnement Tâche de cycle de vie par Extensions afterFirstDeploy tâche sur afterRedeploy
Noms des fonctions ext-<instanceId>-fsexportbigquery fsexportbigquery (avec préfixe facultatif)
ID d'instance EXT_INSTANCE_ID injecté par des extensions FIREBASE_KIT_INSTANCE_ID, défini par la CLI à partir de firebase.json

9. Tester votre fonction de 2e génération

Vous devriez maintenant disposer d'une fonction de 2e génération qui, une fois déployée, se comporte de la même manière qu'une nouvelle installation de votre extension. L'étape suivante consiste à vérifier et à corriger les problèmes introduits accidentellement en cours de route.

Pour appeler setGlobalOptions afin de définir des options globales telles qu'une région ou un processeur par défaut, vous ne devez le faire que lorsque vous déployez votre kit en tant que fonction de 2e génération autonome. Lorsque votre kit est installé en tant que package npm, vos utilisateurs appellent setGlobalOptions dans leur code d'encapsulation pour configurer ces paramètres. Ils reçoivent des avertissements si cela se produit deux fois. Vous pouvez protéger cet appel en vérifiant la variable d'environnement FIREBASE_KIT_INSTANCE_ID :

import { setGlobalOptions } from "firebase-functions";

if (!process.env.FIREBASE_KIT_INSTANCE_ID) {
  setGlobalOptions({
    region: "us-east1",
    maxInstances: 10,
  });
}

Assurez-vous d'utiliser firebase-tools >= 15.32.0, puis déployez votre fonction de 2e génération convertie dans un projet de test avec les ressources appropriées pour tester son comportement. Si vous avez déjà configuré un projet de test pour tester votre extension, exécutez la commande suivante :

firebase deploy --only functions

Remplissez l'assistant qui vous invite à saisir les valeurs des paramètres de la même manière que vous auriez rempli le formulaire d'installation dans la console Firebase pour l'extension.

Exemple : Diffuser Cloud Firestore vers BigQuery

Nous vérifions la synchronisation de bout en bout de Cloud Firestore à BigQuery :

  1. Sur la page Cloud Firestore de la console Firebase, créez la collection que vous avez définie comme COLLECTION_PATH (users) si elle n'existe pas déjà.
  2. Créez un document nommé bigquery-mirror-test contenant des champs avec des valeurs.
  3. Sur la page BigQuery de la console Google Cloud, interrogez la table de journal des modifications brute. Il doit contenir une seule ligne enregistrant la création du document :

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`
    
  4. Interrogez la dernière vue, qui doit renvoyer le dernier événement de modification pour le seul document présent (bigquery-mirror-test) :

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`
    
  5. Supprimez le document bigquery-mirror-test dans Cloud Firestore. Elle disparaît de la dernière vue, et un événement DELETE est ajouté à la table du journal des modifications brut.

    Vous pouvez inspecter l'historique complet d'un seul document avec :

    SELECT *
       FROM `PROJECT_ID.analytics.users_raw_changelog`
       WHERE document_name = "bigquery-mirror-test"
       ORDER BY timestamp ASC
    

Différences par rapport au test de l'extension :

  • Le déclencheur est déployé en tant que fsexportbigquery (sans préfixe lors du déploiement en tant que fonction de 2e génération standard et non en tant que kit), et non en tant que ext-<instanceId>-fsexportbigquery. Recherchez ce nom dans le tableau de bord et les journaux Cloud Functions.
  • Votre code s'exécute désormais dans le Firebase Local Emulator Suite en tant que fonctions normales. Vous pouvez définir la valeur des paramètres à utiliser dans l'émulateur avec .env.local. Vous pouvez également effectuer des tests unitaires de votre code à l'aide du SDK firebase-functions-test, comme décrit dans Tests unitaires de Cloud Functions.
  • Le provisionnement n'est plus géré par l'environnement d'exécution des extensions. Si la table du journal des modifications est manquante après le déploiement, réexécutez manuellement la tâche de configuration : firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME. La tâche est idempotente. Par conséquent, sa réexécution rapproche l'ensemble de données, la table et les vues.
  • Les valeurs des paramètres proviennent de .env plutôt que du formulaire d'installation. Par conséquent, les réexécutions de firebase deploy ne sont pas interactives une fois que .env est terminé.

10. Publier votre kit de fonctions sur npm

Une fois que vous avez validé la conversion de l'extension en fonction de 2e génération, vous pouvez publier une version candidate sur npm pour des tests de bout en bout en suivant l'un des guides suivants :

Une fois votre kit publié sur npm, il peut être installé avec firebase functions:kits:install et listé comme remplacement officiel de votre extension.

Nous vous recommandons vivement de publier d'abord une version candidate. Les kits sont installés par nom de package et par version. Une version préliminaire vous permet donc de tester le flux d'installation réel par rapport au registre sans exposer un package inachevé aux utilisateurs qui l'installent avec le tag latest par défaut.

Avant de publier :

  1. Choisissez un nom de package. Les noms limités et non limités fonctionnent (voir les guides ci-dessus). Notez que les packages limités sont privés par défaut. Transmettez donc --access public.
  2. Construire et vérifier quels vaisseaux. main et types pointent vers votre sortie compilée (lib/ dans notre exemple), ce répertoire doit donc être inclus dans le fichier tar publié. Utilisez .npmignore ou une liste d'autorisation files, puis inspectez le résultat avec npm pack --dry-run. Un script prepublishOnly qui exécute votre compilation empêche la publication d'une sortie obsolète.

package.json ajouts qui sécurisent la publication par défaut :

{
  "files": ["lib", "README.md", "CHANGELOG.md"],
  "publishConfig": { "access": "public", "tag": "next" },
  "scripts": {
    "build": "tsc -b",
    "prepublishOnly": "npm run build && npm test"
  }
}

Le champ "publishConfig": { "tag": "next" } garantit qu'un npm publish simple n'écrase jamais latest.

Créer une version candidate :

Par exemple, pour incrémenter la version localement de 0.0.2-rc.3 à 0.0.2-rc.4 (cela valide et ajoute des tags dans Git si package.json se trouve à la racine du dépôt) :

npm version prerelease --preid rc

Pour publier la version candidate et enregistrer @your-org/your-kit@0.0.2-rc.4 sur npm sous le tag next :

npm publish

L'affichage de la nouvelle version sur le site Web npm peut prendre quelques minutes. npm view lit directement le registre :

npm view @your-org/your-kit versions dist-tags

Une fois les étapes 11 et 12 de ce guide terminées, vous pouvez promouvoir le package vers une version stable :

npm version 0.0.2
npm publish --tag latest
npm dist-tag add @your-org/your-kit@0.0.2 next

Remarque sur npm-shrinkwrap.json : Nous vous recommandons vivement d'inclure un fichier npm-shrinkwrap.json dans votre package. La CLI avertit les utilisateurs lors de l'installation si vous ne le faites pas. Cela garantit que les utilisateurs utilisent les dépendances exactes que vous avez testées et contribue à vous protéger contre les attaques de la chaîne d'approvisionnement. Toutefois, un shrinkwrap est appliqué textuellement dans les projets de vos utilisateurs, y compris lors de la compilation Cloud Functions (npm ci), où les entrées réservées au développement peuvent échouer avec EBADPLATFORM. Vous devrez peut-être supprimer les entrées "dev": true et devDependencies de la copie shrinkwrap publiée.

Exemple : Diffuser Cloud Firestore vers BigQuery

package.json du kit au moment de sa quatrième version candidate :

{
  "name": "@firebase-function-kits/firestore-bigquery-export",
  "version": "0.0.2-rc.4",
  "repository": {
    "type": "git",
    "url": "https://github.com/firebase/extensions.git",
    "directory": "kits/firestore-bigquery-export"
  },
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "engines": { "node": "22" },
  "scripts": { "build": "tsc -b" }
}

Notez que dans ce cas, le kit se trouve dans un monorepo. Il est donc important d'inclure repository.directory pour que le lien du registre npm pointe vers le bon dossier. Son CHANGELOG.md contient des notes pour la version en attente.

11. Tester en tant que kit de fonctions

Une fois votre kit publié, nous vous recommandons de le tester à l'aide de npm.

Assurez-vous d'utiliser la version >= 15.32.0 de firebase-tools et installez le kit :

firebase functions:kits:install --package <your-package-name>@<your-prerelease-version>

Cette commande télécharge votre package depuis npm, le configure dans un nouveau répertoire source pour votre kit et vous guide dans la configuration de la première instance, de la même manière que pour l'installation d'extensions. Une fois que vous avez installé et configuré votre package localement, exécutez un déploiement pour créer les ressources dans votre projet Google Cloud :

firebase deploy --only functions:<your-kit-instance-id>

Après l'installation, la CLI Firebase affiche une commande de déploiement similaire avec l'ID d'instance exact que vous avez choisi lors de l'installation.

Validez à nouveau votre kit en suivant les instructions de l'étape 9. Testez votre fonction de 2e génération. Maintenant que vous effectuez le déploiement à l'aide de kits, vos fonctions sont préfixées et nommées kit-<instance-id>-<method-name>. Cela permet aux kits d'avoir plusieurs instances, en déployant la même fonction plusieurs fois dans un projet, chacune avec un nom unique.

12. Tester le remplacement de la migration

Vous pouvez configurer une instance d'extension opérationnelle, puis utiliser le guide de migration pour les utilisateurs (à l'aide de firebase ext:migrate --package ou des commandes de la CLI des kits de fonctions) pour terminer de tester votre kit de fonctions en tant que remplacement de migration.

13. Informer les utilisateurs et Google de l'extension officielle de remplacement

Une fois que votre kit de fonctions de remplacement est prêt et disponible sous la forme d'un package npm vers lequel les utilisateurs doivent migrer, informez-les, ainsi que Google, de ce remplacement officiel. Mettez à jour le fichier README.md dans le dépôt GitHub qui héberge votre extension avec les informations suivantes :

<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="<your-extesion-id>" package="<your-npm-package-name>" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `<your-extension>` is deprecated. Migrate to the [<your-npm-package-name>](<link-to-your-npm-package>) package.

Google analyse les fichiers README des extensions connues pour rechercher des commentaires tels que <!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" --> et les utilise pour renseigner notre registre officiel des remplacements stockés dans le dépôt firebase-tools sous la forme replacements.json. Vous pouvez également consulter replacements.json pour voir quels README.md seront analysés pour votre extension. La liste officielle des remplacements est mise à jour toutes les semaines.

Exemple : Diffuser Cloud Firestore vers BigQuery

L'extension firestore-bigquery-export README.md contient :

<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `firebase/firestore-bigquery-export` is deprecated. Please migrate to the [`@firebase-function-kits/firestore-bigquery-export`](https://www.npmjs.com/package/@firebase-function-kits/firestore-bigquery-export) package.