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 gli editori rilasciano gli aggiornamenti ed eseguire il rollback di una migrazione, se necessario.
Utilizzo di un kit di funzioni da un pacchetto npm senza eseguire la migrazione
Se non esegui la migrazione da un'estensione, l'utilizzo di un kit di funzioni è composto da due parti:
Installazione del kit
Puoi installare un kit di funzioni utilizzando il seguente comando CLI:
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.
Modificare le 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 in 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 fileindex.tsdi base che importa ed esporta il pacchetto del kit durante la configurazione di un parametro che 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 i futuri aggiornamenti aggiungono nuovi parametri, ti verrà chiesto al deployment successivo. - Crea le risorse Google Cloud richieste per eseguire questo kit, tra cui un service account con ruoli IAM specifici, funzioni, trigger Eventarc e code Cloud Tasks.
Se hai più istanze del kit nello stesso progetto, puoi ripetere questi comandi per creare e implementare 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 staging e un progetto di produzione). Per saperne di più sulle configurazioni avanzate, consulta Migrazioni avanzate.
Disinstallare un kit
Per rimuovere il kit e tutte le sue istanze, esegui:
firebase functions:kits:uninstall --kit <kit-id>
Vengono eliminate tutte le istanze e le relative configurazioni e la fonte del kit viene rimossa dal disco.
Per rimuovere una sola istanza del kit, esegui:
firebase functions:kits:uninstall --instance <kit-instance-id>
Se hai una sola istanza del kit, viene disinstallato l'intero kit.
Aggiornamento di una configurazione del kit
Durante l'installazione o il primo deployment, ti viene 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 farlo 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 viene chiesto di inserire questi
parametri durante l'implementazione.
Ad esempio, se elimini la riga COLLECTION_PATH=posts ed esegui il deployment, ti viene
richiesta durante il deployment:
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)
Manutenzione e upgrade di un kit di funzioni
Gli autori possono aggiornare i propri pacchetti npm nel tempo per correggere bug, aggiungere funzionalità, aggiornare le dipendenze o risolvere le vulnerabilità di sicurezza. Ti consigliamo di rimanere aggiornato su queste versioni e di installare gli aggiornamenti, in particolare quelli che risolvono le vulnerabilità di sicurezza.
Il comando functions:kits:install crea una base di codice 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. Dalla directory source, esegui il
seguente comando 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 incompatibile (esclusi gli aggiornamenti delle versioni principali che potrebbero contenere modifiche incompatibili), 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 causano interruzioni), esegui:
npm update --save <npm-package-name>@latest
Esamina la documentazione del pacchetto e le note di rilascio per vedere cosa è cambiato e se devi eseguire passaggi aggiuntivi prima o dopo il deployment per evitare modifiche che provocano errori.
Deployment delle istanze aggiornate
L'esecuzione di npm update aggiorna solo il codice sorgente locale. Per aggiornare le funzioni
in esecuzione nel cloud, esegui nuovamente il deployment. Puoi eseguire nuovamente il deployment di tutte le funzioni nel tuo progetto, inclusi tutti i kit di funzioni, eseguendo:
firebase deploy --only functions
Annullare 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 (in questo modo viene disinstallato 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.
Ottieni un elenco degli ID istanza delle tue estensioni:
Puoi utilizzare il comando CLI
ext:listper 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» 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-troubleshootingIl comando
ext:listha anche un formato di output JSON e, se hai installato l'utilità jq, puoi utilizzarla per ottenere un elenco di tutti gli ID istanza per 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-exportEsporta 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-exportOutput:
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.testingSul disco troverai un'esportazione di questa istanza dell'estensione in una posizione come
<instance-id>/.env.<project-id>. In questo esempio, si trova infirestore-bigquery-export/.env.my-project.Puoi ripetere questa procedura una volta per istanza e viene creato un insieme di file
.envcon tutte le configurazioni delle istanze di estensione che possono essere riutilizzate in un secondo momento nell'ambito di una migrazione.Sposta i file
.envesportati in una posizione migliore:I file
.envesportati dalle 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 finché non ti serviranno in futuro o scegliere di eliminarli.