Nachdem Sie von Firebase Extensions zu einem Funktions-Kit migriert sind, verwalten Sie Ihre Kit-Instanzen als standardmäßige Cloud Functions der 2. Generation in Ihrem Firebase-Projekt. In diesem Leitfaden wird beschrieben, wie Sie neue Funktions-Kits direkt über npm installieren, ohne eine vorhandene Erweiterung zu migrieren, wie Sie Kit-Parameter und globale Optionen aktualisieren, wie Sie npm-Paketversionen aktualisieren, wenn Publisher Updates veröffentlichen, und wie Sie eine Migration bei Bedarf rückgängig machen.
Funktions-Kit aus einem npm-Paket ohne Migration verwenden
Wenn Sie nicht von einer Erweiterung migrieren, besteht die Verwendung eines Funktions-Kits aus zwei Teilen:
Kit installieren
Sie können ein Funktions-Kit mit dem folgenden CLI-Befehl installieren:
firebase functions:kits:install --package <npm-package-name>
Beispiel:
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.
Globale Standardoptionen ändern
Wenn Sie die globalen Optionen für Ihre Kit-Instanz konfigurieren möchten, ändern Sie die Datei index.ts unter function-kits/<your-kit-id>/source/src/index.ts.
Wenn die Standardeinstellungen für alle Instanzen des Kits gelten sollen, legen Sie sie direkt in index.ts fest. Erstellen Sie andernfalls Parameter, die pro Instanz festgelegt werden, und folgen Sie dabei den Beispielen und Anleitungen in index.ts.
Kit bereitstellen
Führen Sie folgenden Befehl aus, um das Funktions-Kit bereitzustellen:
firebase deploy --only functions:<kit-instance-id>
Beispiel:
firebase deploy --only functions:firestore-bigquery-export --project my-project
Ausgabe:
=== 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!
Bei der Installation und Bereitstellung des Kits werden die folgenden Aktionen ausgeführt:
- Erstellt
function-kits/firestore-bigquery-export/source, das die Kit-Quelle enthält, einschließlich einer einfachenindex.ts-Datei, die das Kit-Paket importiert und exportiert, während ein Parameter eingerichtet wird, mit dem Sie für jede Instanz des Kits einen anderen Speicherort auswählen können. - Erstellt
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>und füllt es mit den für die Funktion eingegebenen Konfigurationsdaten. Wenn bei zukünftigen Updates neue Parameter hinzugefügt werden, werden Sie bei der nächsten Bereitstellung dazu aufgefordert. - Erstellt die erforderlichen Google Cloud-Ressourcen zum Ausführen dieses Kits, einschließlich eines Dienstkontos mit bestimmten IAM-Rollen, Funktionen, Eventarc-Triggern und Cloud Tasks-Aufgabenwarteschlangen.
Wenn Sie mehrere Instanzen des Kits im selben Projekt haben, können Sie diese Befehle wiederholen, um neue Instanzen desselben Kits zu erstellen und bereitzustellen. Sie können auch eine einzelne Kit-Instanz in mehreren Firebase-Projekten mit unterschiedlichen Konfigurationen bereitstellen (z. B. in einem Staging-Projekt und einem Produktionsprojekt). Weitere Informationen zu erweiterten Konfigurationen finden Sie unter Erweiterte Migrationen.
Kit deinstallieren
Führen Sie den folgenden Befehl aus, um das Kit und alle zugehörigen Instanzen zu entfernen:
firebase functions:kits:uninstall --kit <kit-id>
Dadurch werden alle Instanzen und ihre Konfigurationen gelöscht und die Kit-Quelle wird vom Laufwerk entfernt.
Wenn Sie nur eine einzelne Instanz des Kits entfernen möchten, führen Sie folgenden Befehl aus:
firebase functions:kits:uninstall --instance <kit-instance-id>
Wenn Sie nur eine Instanz des Kits haben, wird das gesamte Kit deinstalliert.
Kit-Konfiguration aktualisieren
Während der Installation oder der ersten Bereitstellung werden Sie aufgefordert, alle Parameter für Ihr Kit zu konfigurieren (es sei denn, Sie haben eine Konfiguration aus einer Erweiterung migriert).
Diese Parameter werden in der Datei .env im Konfigurationsverzeichnis Ihrer Kit-Instanz gespeichert. Wenn Sie beispielsweise eine Kit-Instanz mit dem Namen firestore-bigquery-export im Projekt my-project haben, befindet sich die Datei .env unter function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.
Das sieht so aus:
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
Wenn Sie den Konfigurationswert kennen, den Sie ändern möchten, können Sie ihn direkt in der Datei .env bearbeiten. Wenn Sie die interaktive Eingabeaufforderung verwenden möchten, die während der Installation und Bereitstellung ausgeführt wird, entfernen Sie die Parameter, die Sie ändern möchten, aus der Datei .env und stellen Sie die Kit-Instanz noch einmal bereit. Sie werden während der Bereitstellung aufgefordert, diese Parameter einzugeben.
Wenn Sie beispielsweise die Zeile COLLECTION_PATH=posts löschen und die Bereitstellung durchführen, werden Sie während der Bereitstellung dazu aufgefordert:
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)
Funktions-Kit warten und aktualisieren
Publisher können ihre npm-Pakete im Laufe der Zeit aktualisieren, um Fehler zu beheben, Funktionen hinzuzufügen, Abhängigkeiten zu aktualisieren oder Sicherheitslücken zu schließen. Wir empfehlen, sich über diese Releases auf dem neuesten Stand zu halten und Updates zu installieren, insbesondere solche, die Sicherheitslücken beheben.
Mit dem Befehl functions:kits:install wird eine Codebasis erstellt, die ein Kit als npm-Paket installiert und alle Funktionen für jede Instanz des Kits exportiert.
Wenn Sie ein Kit aktualisieren möchten, aktualisieren Sie die Paketversion und stellen Sie dann jede Instanz des Kits noch einmal bereit, um die Änderungen zu übernehmen.
Prüfen, ob ein Kit aktualisiert wurde
Wechseln Sie in das Verzeichnis source Ihres Kits unter function-kits/<your-kit-id>/source. Führen Sie im Verzeichnis source den folgenden Befehl aus, um einen Bericht zu allen veralteten npm-Paketen zu erhalten, einschließlich Ihres Funktions-Kits und des Cloud Functions SDK:
npm outdated
Wenn Sie bereits ein Tool zum Identifizieren von Abhängigkeiten verwenden, die aktualisiert werden müssen, z. B. Dependabot für GitHub, empfehlen wir, Ihr Kit-Verzeichnis in diesen Workflow einzubinden.
Kit aktualisieren
Führen Sie folgenden Befehl aus, um das Kit und seine Abhängigkeiten auf die neueste nicht funktionsgefährdende Version zu aktualisieren (ausgenommen Hauptversionsupdates, die funktionsgefährdende Änderungen enthalten können):
npm update --save
Wenn Sie nur das Funktions-Kit-Paket und keine anderen Pakete aktualisieren möchten, übergeben Sie den Paketnamen an npm update:
npm update <package-name> --save
Führen Sie folgenden Befehl aus, um ein Paket auf die neueste Hauptversion zu aktualisieren (was zu funktionsgefährdenden Änderungen führen kann):
npm update --save <npm-package-name>@latest
Lesen Sie die Paketdokumentation und die Versionshinweise, um zu sehen, was sich geändert hat und ob Sie vor oder nach der Bereitstellung zusätzliche Schritte ausführen müssen, um funktionsgefährdende Änderungen zu vermeiden.
Aktualisierte Instanzen bereitstellen
Wenn Sie npm update ausführen, wird nur Ihr lokaler Quellcode aktualisiert. Wenn Sie Ihre laufenden Funktionen in der Cloud aktualisieren möchten, müssen Sie sie noch einmal bereitstellen. Sie können alle Funktionen in Ihrem Projekt, einschließlich aller Funktions-Kits, noch einmal bereitstellen, indem Sie Folgendes ausführen:
firebase deploy --only functions
Migration rückgängig machen
Wenn Sie eine Migration rückgängig machen möchten, müssen Sie die Erweiterung zuerst neu installieren. In der Datei .env des Kits finden Sie die Konfigurationswerte, die für die Installation erforderlich sind.
Deinstallieren Sie nach der Bereitstellung der Erweiterung die Kit-Instanz. Dadurch wird das gesamte Kit deinstalliert, wenn es die letzte verbleibende Instanz ist:
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
Erweiterungskonfigurationen für eine zukünftige Migration speichern
Nach dem 31. März 2027 können Sie keine vorhandene Erweiterungskonfiguration mehr abrufen. Wenn Sie die Migration nicht vor dem 31. März 2027 durchführen können, empfehlen wir Ihnen dringend, Ihre Erweiterung zu speichern, falls Sie sich nach diesem Datum für die Migration entscheiden.
Rufen Sie eine Liste der IDs Ihrer Erweiterungsinstanzen ab:
Mit dem
ext:list-CLI-Befehl können Sie eine Liste aller Erweiterungsinstanzen in Ihrem Firebase-Projekt abrufen:firebase ext:list --project <project-id>Beispiel:
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-troubleshootingDer Befehl
ext:listhat auch ein JSON-Ausgabeformat. Wenn Sie das Dienstprogramm jq installiert haben, können Sie damit eine Liste aller Instanz-IDs für ein Projekt abrufen:firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'Beispiel:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'Ausgabe:
firestore-bigquery-export-zbrp firestore-bigquery-exportExportieren Sie die Konfiguration für jede Instanz:
Sie können die Konfiguration jeder Instanz auf dem Laufwerk speichern, indem Sie den folgenden Exportbefehl ausführen:
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>Beispiel:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-exportAusgabe:
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.testingAuf dem Laufwerk finden Sie einen Export dieser Erweiterungsinstanz an einem Speicherort wie
<instance-id>/.env.<project-id>. In diesem Beispiel befindet sie sich unterfirestore-bigquery-export/.env.my-project.Sie können diesen Vorgang einmal pro Instanz wiederholen. Dadurch wird eine Reihe von
.env-Dateien mit allen Konfigurationen Ihrer Erweiterungsinstanzen erstellt, die später im Rahmen einer Migration wiederverwendet werden können.Verschieben Sie die exportierten
.env-Dateien an einen besseren Speicherort:Die exportierten
.env-Dateien aus Ihren Erweiterungen wurden direkt in Ihr Firebase-Projekt eingefügt, werden aber im Alltag nicht benötigt, wenn Sie nicht zu Function Kits migriert sind. Sie können sie aus Ihrem Projekt an einen anderen geeigneten Speicherort verschieben, bis Sie sie in Zukunft benötigen, oder sie löschen.