Best practice post-migrazione

Dopo aver eseguito la migrazione da Firebase Extensions a un kit di funzioni, gestisci le istanze del kit come Cloud Functions di 2ª gen. standard nel tuo progetto Firebase. Questa guida spiega come installare nuovi kit di funzioni direttamente da npm senza eseguire la migrazione di un'estensione esistente, aggiornare i parametri del kit e le opzioni globali, eseguire l'upgrade delle versioni dei pacchetti npm man mano che i publisher rilasciano aggiornamenti ed eseguire il rollback di una migrazione, se necessario.

Utilizzo di un kit di funzioni da un pacchetto npm senza migrazione

Se non esegui la migrazione da un'estensione, l'utilizzo di un kit di funzioni prevede due parti:

Installazione del kit

Puoi installare un kit di funzioni utilizzando il seguente comando dell'interfaccia a riga di comando:

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

Esempio elaborato:

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.

Modifica delle opzioni globali predefinite

Per configurare le opzioni globali per l'istanza del kit, modifica il file index.ts che si trova in function-kits/<your-kit-id>/source/src/index.ts.

Se vuoi che i valori predefiniti vengano condivisi tra tutte le istanze del kit, impostali direttamente in index.ts. In caso contrario, crea parametri impostati per istanza, seguendo gli esempi e le istruzioni documentati in index.ts.

Deployment del kit

Per eseguire il deployment del kit di funzioni, esegui:

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

Esempio elaborato:

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

Output:

=== 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'installazione e il deployment del kit eseguono le seguenti azioni:

  • Crea function-kits/firestore-bigquery-export/source, che contiene l'origine del kit, incluso un file index.ts di base che importa ed esporta il pacchetto del kit, configurando al contempo un parametro che ti consente di scegliere una posizione diversa per ogni istanza del kit.
  • Crea function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> e lo compila con i dati di configurazione inseriti per la funzione. Se gli aggiornamenti futuri aggiungono nuovi parametri, ti verrà chiesto di configurarli al deployment successivo.
  • Crea le risorse Google Cloud necessarie per eseguire questo kit, tra cui un service account con ruoli IAM specifici, funzioni, trigger Eventarc e code di attività Cloud Tasks.

Se hai più istanze del kit nello stesso progetto, puoi ripetere questi comandi per creare ed eseguire il deployment di nuove istanze dello stesso kit. Puoi anche eseguire il deployment di una singola istanza del kit in più progetti Firebase con configurazioni diverse (ad esempio, un progetto di gestione temporanea e un progetto di produzione). Per scoprire di più sulle configurazioni avanzate, consulta Migrazioni avanzate.

Disinstallazione di un kit

Per rimuovere il kit e tutte le sue istanze, esegui:

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

In questo modo, vengono eliminate tutte le istanze e le relative configurazioni e l'origine del kit viene rimossa dal disco.

Per rimuovere una singola istanza del kit, esegui:

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

Se hai una sola istanza del kit, l'intero kit verrà disinstallato.

Aggiornamento di una configurazione del kit

Durante l'installazione o il primo deployment, ti verrà chiesto di configurare tutti i parametri del kit (a meno che tu non abbia eseguito la migrazione di una configurazione da un'estensione). Questi parametri sono archiviati nel file .env nella directory di configurazione dell'istanza del kit. Ad esempio, se hai un'istanza del kit denominata firestore-bigquery-export nel progetto my-project, il file .env si trova in function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.

Avrà un aspetto simile al seguente:

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

Se conosci il valore di configurazione che vuoi modificare, puoi modificarlo direttamente nel file .env. Se preferisci utilizzare il prompt interattivo che viene eseguito durante l'installazione e il deployment, rimuovi i parametri che vuoi modificare dal file .env e rifai il deployment dell'istanza del kit. Ti verrà chiesto di inserire questi parametri durante il deployment.

Ad esempio, se elimini la riga COLLECTION_PATH=posts ed esegui il deployment, ti verrà richiesto durante il deployment:

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)

Manutenzione e upgrade di un kit di funzioni

I publisher possono aggiornare i propri pacchetti npm nel tempo per correggere bug, aggiungere funzionalità, aggiornare le dipendenze o risolvere vulnerabilità di sicurezza. Ti consigliamo di rimanere al corrente di queste release e di installare gli aggiornamenti, in particolare quelli che risolvono le vulnerabilità della sicurezza.

Il comando functions:kits:install crea un codebase che installa un kit come pacchetto npm ed esporta tutte le sue funzioni per ogni istanza del kit. Per eseguire l'upgrade di un kit, aggiorna la versione del pacchetto e poi esegui nuovamente il deployment di ogni istanza del kit per applicare le modifiche.

Determinare se un kit ha aggiornamenti

Vai alla directory source del tuo kit all'indirizzo function-kits/<your-kit-id>/source. Da questa directory source, esegui il comando seguente per ottenere un report su tutti i pacchetti npm obsoleti, inclusi il kit di funzioni e l'SDK Cloud Functions:

npm outdated

Se utilizzi già uno strumento per identificare le dipendenze che devono essere aggiornate, ad esempio Dependabot per GitHub, ti consigliamo di integrare la directory del kit in questo flusso di lavoro.

Aggiornamento di un kit

Per aggiornare il kit e le relative dipendenze all'ultima versione non invasiva (esclusi gli aggiornamenti delle versioni principali che potrebbero contenere modifiche che provocano un errore), esegui:

npm update --save

Se vuoi aggiornare solo il pacchetto del kit di funzioni e nessun altro pacchetto, passa il nome del pacchetto a npm update:

npm update <package-name> --save

Per eseguire l'upgrade di un pacchetto all'ultima versione principale (che può introdurre modifiche che provocano un errore), esegui:

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

Consulta la documentazione del pacchetto e le note di rilascio per vedere cosa è cambiato e se devi eseguire ulteriori passaggi prima o dopo il deployment per evitare modifiche che provocano un errore.

Deployment delle istanze aggiornate

L'esecuzione di npm update aggiorna solo il codice sorgente locale. Per aggiornare le funzioni in esecuzione nel cloud, devi eseguirne nuovamente il deployment. Puoi rifare il deployment di tutte le funzioni del tuo progetto, inclusi tutti i kit di funzioni, eseguendo:

firebase deploy --only functions

Annullamento di una migrazione

Per annullare una migrazione, reinstalla prima l'estensione. Puoi utilizzare il file .env del kit per trovare i valori di configurazione necessari durante l'installazione.

Dopo aver eseguito il deployment dell'estensione, disinstalla l'istanza del kit (questa operazione disinstalla l'intero kit se è l'ultima istanza rimanente):

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

Salvataggio delle configurazioni delle estensioni per una migrazione futura

Dopo il 31 marzo 2027, non potrai recuperare una configurazione di estensione esistente. Se non riesci a eseguire la migrazione prima del 31 marzo 2027, ti consigliamo vivamente di salvare l'estensione nel caso in cui decidi di eseguire la migrazione dopo questa data.

  1. Ottieni un elenco degli ID istanza delle tue estensioni:

    Puoi utilizzare il comando dell'interfaccia a riga di comando ext:list per ottenere un elenco di tutte le istanze di estensione nel tuo progetto Firebase:

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

    Esempio elaborato:

    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

    Il comando ext:list ha anche un formato di output JSON e, se hai installato l'utilità jq, puoi utilizzarla per ottenere un elenco di tutti gli ID istanza di un progetto:

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

    Esempio elaborato:

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

    Output:

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

  2. Esporta la configurazione per ogni istanza:

    Per ogni istanza, puoi salvare la configurazione sul disco eseguendo il seguente comando di esportazione:

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

    Esempio elaborato:

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

    Output:

    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

    Sul disco, troverai un'esportazione di questa istanza dell'estensione in una posizione simile a <instance-id>/.env.<project-id>. In questo esempio, si trova in firestore-bigquery-export/.env.my-project.

    Puoi ripetere questa procedura una volta per istanza e creare un insieme di file .env con tutte le configurazioni delle istanze di estensione che possono essere riutilizzate in un secondo momento nell'ambito di una migrazione.

  3. Sposta i file .env esportati in una posizione migliore:

    I file .env esportati dalle tue estensioni sono stati inseriti direttamente nel tuo progetto Firebase, ma non sono necessari quotidianamente se non hai eseguito la migrazione ai kit di funzioni. Puoi spostarli dal progetto a qualsiasi altra posizione di archiviazione appropriata fino a quando non ne avrai bisogno in futuro o scegliere di eliminarli.