Nachdem Sie von Firebase Extensions zu einem Funktions-Kit migriert haben, verwalten Sie Ihre Kit-Instanzen als Standard-Cloud Functions der 2. Generation in Ihrem Firebase-Projekt. In dieser Anleitung wird beschrieben, wie Sie neue Funktionskits direkt von npm installieren, ohne eine vorhandene Erweiterung zu migrieren, Kit-Parameter und globale Optionen aktualisieren, npm-Paketversionen aktualisieren, wenn Publisher Updates veröffentlichen, und 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 Funktionskits aus zwei Teilen:
Kit installieren
Sie können ein Funktionskit 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. 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!
Beim Installieren und Bereitstellen 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 und gleichzeitig einen Parameter einrichtet, 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 Konfigurationsdaten, die für die Funktion eingegeben wurden. 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-Warteschlangen.
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- und einem Produktionsprojekt. Weitere Informationen zu erweiterten Setups finden Sie unter Erweiterte Migrationen.
Kit deinstallieren
Führen Sie Folgendes 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 von der Festplatte 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
Bei der Installation oder der ersten Bereitstellung werden Sie aufgefordert, alle Parameter für Ihr Kit zu konfigurieren, sofern Sie keine Konfiguration aus einer Erweiterung migriert haben.
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 lieber den interaktiven Prompt verwenden möchten, der 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 Funktion bereitstellen, 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.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)
Funktions-Kit warten und aktualisieren
Verlage und Webpublisher 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 Laufenden zu halten und Updates zu installieren, insbesondere solche, die Sicherheitslücken schließen.
Mit dem Befehl functions:kits:install wird eine Codebasis erstellt, mit der ein Kit als npm-Paket installiert und alle seine Funktionen für jede Instanz Ihres Kits exportiert werden.
Wenn Sie ein Kit aktualisieren möchten, aktualisieren Sie die Paketversion und stellen Sie dann jede Instanz Ihres Kits noch einmal bereit, um die Änderungen zu übernehmen.
Prüfen, ob für ein Kit Updates verfügbar sind
Wechseln Sie im Kit unter function-kits/<your-kit-id>/source in das Verzeichnis source. Führen Sie im Verzeichnis source den folgenden Befehl aus, um einen Bericht zu allen veralteten npm-Paketen zu erhalten, einschließlich Ihres Funktionskits und des Cloud Functions SDK:
npm outdated
Wenn Sie bereits ein Tool verwenden, um Abhängigkeiten zu identifizieren, die aktualisiert werden müssen, z. B. Dependabot für GitHub, empfehlen wir, Ihr Kit-Verzeichnis in diesen Workflow zu integrieren.
Kit aktualisieren
So aktualisieren Sie das Kit und seine Abhängigkeiten auf die neueste nicht funktionsgefährdende Version (mit Ausnahme von Hauptversionsupdates, die funktionsgefährdende Änderungen enthalten können):
npm update --save
Wenn Sie nur das Funktionskit-Paket und keine anderen Pakete aktualisieren möchten, übergeben Sie den Paketnamen an npm update:
npm update <package-name> --save
So aktualisieren Sie ein Paket auf die neueste Hauptversion (die möglicherweise Breaking Changes enthält):
npm update --save <npm-package-name>@latest
Sehen Sie sich die Paketdokumentation und die Versionshinweise an, um zu erfahren, 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, stellen Sie sie noch einmal bereit. Sie können alle Funktionen in Ihrem Projekt, einschließlich aller Funktionskits, neu 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 während der Installation benötigt werden.
Nachdem die Erweiterung bereitgestellt wurde, deinstallieren Sie 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 entscheiden, die Migration nach diesem Datum durchzuführen.
So rufen Sie eine Liste Ihrer Erweiterungsinstanz-IDs 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» 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-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:
Für jede Instanz können Sie die Konfiguration 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 Ihrem Firebase-Projekt platziert, werden aber im täglichen Betrieb nicht benötigt, wenn Sie nicht zu Funktionskits 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.