Bonnes pratiques après la migration

Après avoir migré de Firebase Extensions vers un kit de fonctions, vous gérez vos instances de kit en tant que Cloud Functions de 2e génération standards dans votre projet Firebase. Ce guide explique comment installer de nouveaux kits de fonctions directement depuis npm sans migrer une extension existante, mettre à jour les paramètres du kit et les options globales, mettre à niveau les versions des packages npm à mesure que les éditeurs publient des mises à jour, et annuler une migration si nécessaire.

Utiliser un kit de fonctions d'un package npm sans migrer

Si vous n'effectuez pas de migration à partir d'une extension, l'utilisation d'un kit de fonctions se compose de deux parties :

Installer le kit

Vous pouvez installer un kit de fonctions à l'aide de la commande CLI suivante :

firebase functions:kits:install --package <npm-package-name>

Exemple :

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i  function-kits/firestore-bigquery-export/source/package.json is unchanged
i  function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i  function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i  functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i  functions: Building TypeScript source...
✔  Wrote configuration info to firebase.json

i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1

✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project

✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing

# Omitting many more parameters for brevity

✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

i  functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i  functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠  functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.

Modifier les options globales par défaut

Pour configurer les options globales de votre instance de kit, modifiez le fichier index.ts situé dans function-kits/<your-kit-id>/source/src/index.ts.

Si vous souhaitez que les valeurs par défaut soient partagées entre toutes les instances du kit, définissez-les directement dans index.ts. Sinon, créez des paramètres définis par instance, en suivant les exemples et les instructions de index.ts.

Déployer le kit

Pour déployer votre kit de fonctions, exécutez la commande suivante :

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

Exemple :

firebase deploy --only functions:firestore-bigquery-export --project my-project

Résultat :

=== Deploying to 'my-project'...

i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.

✔  Deploy complete!

L'installation et le déploiement du kit effectuent les actions suivantes :

  • Crée function-kits/firestore-bigquery-export/source, qui contient la source du kit, y compris un fichier index.ts de base qui importe et exporte le package du kit tout en configurant un paramètre qui vous permet de choisir un emplacement différent pour chaque instance du kit.
  • Crée function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> et le remplit avec les données de configuration saisies pour la fonction. Si de futures mises à jour ajoutent de nouveaux paramètres, vous serez invité à les configurer lors du prochain déploiement.
  • Crée les ressources Google Cloud requises pour exécuter ce kit, y compris un compte de service avec des rôles IAM spécifiques, des fonctions, des déclencheurs Eventarc et des files d'attente de tâches Cloud Tasks.

Si vous disposez de plusieurs instances du kit dans le même projet, vous pouvez répéter ces commandes pour créer et déployer de nouvelles instances du même kit. Vous pouvez également déployer une seule instance de kit sur plusieurs projets Firebase avec des configurations différentes (par exemple, un projet de préproduction et un projet de production). Pour en savoir plus sur les configurations avancées, consultez Migrations avancées.

Désinstaller un kit

Pour supprimer le kit et toutes ses instances, exécutez la commande suivante :

firebase functions:kits:uninstall --kit <kit-id>

Cette opération supprime toutes les instances et leurs configurations, ainsi que la source du kit du disque.

Pour ne supprimer qu'une seule instance du kit, exécutez la commande suivante :

firebase functions:kits:uninstall --instance <kit-instance-id>

Si vous n'avez qu'une seule instance du kit, cela désinstalle l'intégralité du kit.

Mettre à jour une configuration de kit

Lors de l'installation ou de votre premier déploiement, vous êtes invité à configurer tous les paramètres de votre kit (sauf si vous avez migré une configuration à partir d'une extension). Ces paramètres sont stockés dans le fichier .env du répertoire de configuration de votre instance de kit. Par exemple, si vous disposez d'une instance de kit nommée firestore-bigquery-export dans le projet my-project, le fichier .env se trouve à l'emplacement function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.

Il se présente comme suit :

DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1

Si vous connaissez la valeur de configuration que vous souhaitez modifier, vous pouvez la modifier directement dans le fichier .env. Si vous préférez utiliser l'invite interactive qui s'exécute lors de l'installation et du déploiement, supprimez les paramètres que vous souhaitez modifier du fichier .env et redéployez l'instance du kit. Vous êtes invité à saisir ces paramètres lors du déploiement.

Par exemple, si vous supprimez la ligne COLLECTION_PATH=posts et que vous déployez, vous êtes invité à la saisir lors du déploiement :

i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:

Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)

Entretenir et mettre à niveau un kit de fonctions

Les éditeurs peuvent mettre à jour leurs packages npm au fil du temps pour corriger des bugs, ajouter des fonctionnalités, mettre à jour des dépendances ou corriger des failles de sécurité. Nous vous recommandons de vous tenir informé de ces versions et d'installer les mises à jour, en particulier celles qui corrigent des failles de sécurité.

La commande functions:kits:install crée un codebase qui installe un kit en tant que package npm et exporte toutes ses fonctions pour chaque instance de votre kit. Pour mettre à niveau un kit, mettez à jour la version du package, puis redéployez chaque instance de votre kit pour appliquer les modifications.

Déterminer si un kit dispose de mises à jour

Accédez au répertoire source de votre kit à l'emplacement function-kits/<your-kit-id>/source. À partir de ce répertoire source, exécutez la commande suivante pour obtenir un rapport sur tous les packages npm obsolètes, y compris votre kit de fonctions et le SDK Cloud Functions :

npm outdated

Si vous utilisez déjà un outil pour identifier les dépendances à mettre à jour, comme Dependabot pour GitHub, nous vous recommandons d'intégrer le répertoire de votre kit à ce workflow.

Mettre à jour un kit

Pour mettre à jour le kit et ses dépendances vers la dernière version non destructive (à l'exclusion des mises à jour de version majeure pouvant contenir des modifications destructives), exécutez la commande suivante :

npm update --save

Si vous ne souhaitez mettre à jour que le package du kit de fonctions et aucun autre package, transmettez le nom du package à npm update :

npm update <package-name> --save

Pour mettre à niveau un package vers la dernière version majeure (ce qui peut introduire des modifications destructives), exécutez la commande suivante :

npm update --save <npm-package-name>@latest

Consultez la documentation du package et les notes de version pour voir ce qui a changé et si vous devez prendre des mesures supplémentaires avant ou après le déploiement pour éviter les modifications destructives.

Déploiement des instances mises à jour…

L'exécution de npm update ne met à jour que votre code source local. Pour mettre à jour vos fonctions en cours d'exécution dans le cloud, redéployez-les. Vous pouvez redéployer toutes les fonctions de votre projet, y compris tous les kits de fonctions, en exécutant la commande suivante :

firebase deploy --only functions

Annuler une migration

Pour annuler une migration, réinstallez d'abord l'extension. Vous pouvez utiliser le fichier .env du kit pour trouver les valeurs de configuration nécessaires lors de l'installation.

Une fois l'extension déployée, désinstallez l'instance du kit (cela désinstalle l'intégralité du kit s'il s'agit de la dernière instance restante) :

firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>

Enregistrer les configurations d'extension pour une migration ultérieure

Après le 31 mars 2027, vous ne pourrez plus récupérer une configuration d'extension existante. Si vous ne parvenez pas à effectuer la migration avant le 31 mars 2027, nous vous recommandons vivement d'enregistrer votre extension au cas où vous décideriez de migrer après cette date.

  1. Obtenez la liste des ID de vos instances d'extension :

    Vous pouvez utiliser la commande de la CLI ext:list pour obtenir la liste de toutes les instances d'extension de votre projet Firebase :

    firebase ext:list --project <project-id>

    Exemple :

    firebase ext:list --project my-project

    » firebase ext:list
i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  extensions: list of extensions installed in my-project:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3   │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export      │ ACTIVE │ 0.3.2   │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

    La commande ext:list dispose également d'un format de sortie JSON. Si l'utilitaire jq est installé, vous pouvez l'utiliser pour obtenir la liste de tous les ID d'instance d'un projet :

    firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'

    Exemple :

    firebase ext:list --json --project my-project | jq -r '.result[].instanceId'

    Résultat :

    firestore-bigquery-export-zbrp
firestore-bigquery-export

  2. Exportez la configuration de chaque instance :

    Pour chaque instance, vous pouvez enregistrer sa configuration sur le disque en exécutant la commande d'exportation suivante :

    firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>

    Exemple :

    firebase ext:export --mode functions --project my-project --instance firestore-bigquery-export

    Résultat :

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  functions: Saving exported extensions config as a Function Kits .env file
i  functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control.
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testing

    Sur le disque, vous trouverez une exportation de cette instance d'extension à un emplacement tel que <instance-id>/.env.<project-id>. Dans cet exemple, il se trouve à l'emplacement firestore-bigquery-export/.env.my-project.

    Vous pouvez répéter ce processus une fois par instance. Il crée un ensemble de fichiers .env contenant toutes les configurations de vos instances d'extension, qui peuvent être réutilisées ultérieurement dans le cadre d'une migration.

  3. Déplacez les fichiers .env exportés vers un meilleur emplacement :

    Les fichiers .env exportés depuis vos extensions ont été placés directement dans votre projet Firebase, mais ils ne sont pas nécessaires au quotidien si vous n'avez pas migré vers les kits de fonctions. Vous pouvez les déplacer de votre projet vers un autre emplacement de stockage approprié jusqu'à ce que vous en ayez besoin, ou choisir de les supprimer.