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 à partir de npm sans migrer une extension existante, comment mettre à jour les paramètres et les options globales du kit, comment mettre à niveau les versions des packages npm lorsque les éditeurs publient des mises à jour et comment effectuer un rollback d'une migration si nécessaire.

Utiliser un kit de fonctions à partir d'un package npm sans migration

Si vous ne migrez pas depuis 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 générales par défaut

Pour configurer les options globales de votre instance de kit, modifiez le fichier index.ts situé à l'adresse 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 documentés dans 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 futurs mises à jour ajoutent de nouveaux paramètres, vous serez invité à les saisir 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 Cloud Tasks.

Si vous avez 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>

Cela supprime toutes les instances et leurs configurations, et supprime la source du kit du disque.

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

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

Si vous ne disposez que d'une seule instance du kit, l'ensemble du kit sera désinstallé.

Mettre à jour la configuration d'un 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 depuis 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'adresse 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 serez 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.ajp-testing
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)

Gérer 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 résoudre 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 les failles de sécurité.

La commande functions:kits:install crée un code de base 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 comporte des mises à jour

Accédez au répertoire source de votre kit à l'adresse 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 votre répertoire de kit à ce workflow.

Mettre à jour un kit

Pour mettre à jour le kit et ses dépendances vers la dernière version non incompatible (à l'exclusion des mises à jour de version majeure qui peuvent contenir des modifications incompatibles), 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 (qui peut introduire des modifications incompatibles), 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 effectuer des étapes supplémentaires avant ou après le déploiement pour éviter les changements cassants.

Déployer des instances mises à jour

L'exécution de npm update ne met à jour que votre code source local. Pour mettre à jour les 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'ensemble 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 la configuration d'une extension existante. Si vous ne pouvez pas migrer 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 d'instance de vos extensions :

    Vous pouvez utiliser la commande 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

    » firebaselocal ext:list
i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  extensions: list of extensions installed in ajp-testing:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ 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 possède également 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'adresse 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 pourront être réutilisées ultérieurement lors d'une migration.

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

    Les fichiers .env exportés à partir de vos extensions ont été placés directement dans votre projet Firebase, mais 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 n'importe quel autre emplacement de stockage approprié jusqu'à ce que vous en ayez besoin à l'avenir ou choisir de les supprimer.