Po przejściu z Firebase Extensions na zestaw funkcji możesz zarządzać instancjami zestawu jako standardowymi funkcjami Cloud Functions 2 generacji w projekcie Firebase. Z tego przewodnika dowiesz się, jak instalować nowe zestawy funkcji bezpośrednio z npm bez przenoszenia istniejącego rozszerzenia, aktualizować parametry zestawu i opcje globalne, uaktualniać wersje pakietów npm, gdy wydawcy publikują aktualizacje, oraz w razie potrzeby wycofywać migrację.
Używanie zestawu funkcji z pakietu npm bez migracji
Jeśli nie przeprowadzasz migracji z rozszerzenia, korzystanie z zestawu funkcji składa się z 2 części:
Instalowanie zestawu
Zestaw funkcji możesz zainstalować za pomocą tego polecenia w interfejsie wiersza poleceń:
firebase functions:kits:install --package <npm-package-name>
Przykład:
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.
Zmiana domyślnych opcji globalnych
Aby skonfigurować opcje globalne dla instancji zestawu, zmodyfikuj plik index.ts znajdujący się w function-kits/<your-kit-id>/source/src/index.ts.
Jeśli chcesz, aby wartości domyślne były udostępniane we wszystkich instancjach zestawu, ustaw je bezpośrednio w index.ts. W przeciwnym razie utwórz parametry, które są ustawiane dla każdej instancji, zgodnie z przykładami i instrukcjami opisanymi w index.ts.
Wdrażanie zestawu
Aby wdrożyć zestaw funkcji, uruchom:
firebase deploy --only functions:<kit-instance-id>
Przykład:
firebase deploy --only functions:firestore-bigquery-export --project my-project
Dane wyjściowe:
=== 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!
Zainstalowanie i wdrożenie zestawu powoduje wykonanie tych działań:
- Tworzy plik
function-kits/firestore-bigquery-export/source, który zawiera źródło zestawu, w tym podstawowy plikindex.ts, który importuje i eksportuje pakiet zestawu, konfigurując parametr umożliwiający wybranie innej lokalizacji dla każdej instancji zestawu. - Tworzy plik
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>i wypełnia go danymi konfiguracji wprowadzonymi dla funkcji. Jeśli przyszłe aktualizacje dodadzą nowe parametry, przy następnym wdrożeniu pojawi się prośba o ich podanie. - Tworzy zasoby Google Cloud wymagane do uruchomienia tego zestawu, w tym konto usługi z określonymi rolami uprawnień, funkcjami, aktywatorami Eventarc i kolejkami Cloud Tasks.
Jeśli masz wiele instancji zestawu w tym samym projekcie, możesz powtórzyć te polecenia, aby utworzyć i wdrożyć nowe instancje tego samego zestawu. Możesz też wdrożyć pojedynczą instancję zestawu w wielu projektach Firebase z różnymi konfiguracjami (np. projekt przejściowy i projekt produkcyjny). Więcej informacji o konfiguracjach zaawansowanych znajdziesz w artykule Migracje zaawansowane.
Odinstalowywanie zestawu
Aby usunąć zestaw i wszystkie jego instancje, uruchom:
firebase functions:kits:uninstall --kit <kit-id>
Spowoduje to usunięcie wszystkich instancji i ich konfiguracji oraz usunięcie źródła zestawu z dysku.
Aby usunąć tylko 1 instancję zestawu, uruchom:
firebase functions:kits:uninstall --instance <kit-instance-id>
Jeśli masz tylko 1 instancję zestawu, spowoduje to odinstalowanie całego zestawu.
Aktualizowanie konfiguracji zestawu
Podczas instalacji lub pierwszego wdrożenia pojawi się prośba o skonfigurowanie wszystkich parametrów zestawu (chyba że konfiguracja została przeniesiona z rozszerzenia).
Te parametry są przechowywane w pliku .env w katalogu konfiguracji instancji zestawu. Jeśli na przykład masz instancję zestawu o nazwie firestore-bigquery-export w projekcie my-project, plik .env znajduje się w function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.
Wygląda on mniej więcej tak:
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
Jeśli znasz wartość konfiguracji, którą chcesz zmienić, możesz ją edytować bezpośrednio w pliku .env. Jeśli wolisz używać interaktywnego promptu, który jest uruchamiany podczas instalacji i wdrażania, usuń parametry, które chcesz zmienić, z pliku .env i ponownie wdróż instancję zestawu. Podczas wdrażania pojawi się prośba o podanie tych parametrów.
Jeśli na przykład usuniesz wiersz COLLECTION_PATH=posts i wdrożysz, podczas wdrażania pojawi się prośba o podanie tej wartości:
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)
Konserwacja i ulepszanie zestawu funkcji
Wydawcy mogą z czasem aktualizować pakiety npm, aby naprawiać błędy, dodawać funkcje, aktualizować zależności lub eliminować luki w zabezpieczeniach. Zalecamy śledzenie wiadomości o tych wersjach i instalowanie aktualizacji, zwłaszcza tych, które dotyczą luk w zabezpieczeniach.
Polecenie functions:kits:install tworzy bazę kodu, która instaluje zestaw jako pakiet npm i eksportuje wszystkie jego funkcje dla każdej instancji zestawu.
Aby uaktualnić zestaw, zaktualizuj wersję pakietu, a następnie ponownie wdróż każdą instancję zestawu, aby zastosować zmiany.
Sprawdzanie, czy zestaw ma aktualizacje
Przejdź do katalogu source zestawu pod adresem function-kits/<your-kit-id>/source. W katalogu source uruchom to polecenie, aby uzyskać raport o wszystkich nieaktualnych pakietach npm, w tym o pakiecie funkcji i pakiecie SDK Cloud Functions:
npm outdated
Jeśli używasz już narzędzia do identyfikowania zależności, które wymagają aktualizacji, takiego jak Dependabot w GitHubie, zalecamy zintegrowanie katalogu zestawu z tym procesem.
Aktualizowanie zestawu
Aby zaktualizować zestaw i jego zależności do najnowszej wersji, która nie powoduje niezgodności (z wyłączeniem aktualizacji wersji głównych, które mogą zawierać zmiany powodujące niezgodność), uruchom:
npm update --save
Jeśli chcesz zaktualizować tylko pakiet zestawu funkcji, a nie inne pakiety, przekaż nazwę pakietu do npm update:
npm update <package-name> --save
Aby uaktualnić pakiet do najnowszej wersji głównej (co może spowodować zmiany powodujące błędy), uruchom:
npm update --save <npm-package-name>@latest
Zapoznaj się z dokumentacją pakietu i informacjami o wersji, aby dowiedzieć się, co się zmieniło i czy musisz wykonać jakieś dodatkowe czynności przed wdrożeniem lub po nim, aby zapobiec zmianom powodującym niezgodność.
Wdrażanie zaktualizowanych instancji
Uruchomienie polecenia npm update powoduje tylko aktualizację lokalnego kodu źródłowego. Aby zaktualizować funkcje działające w chmurze, wdróż je ponownie. Możesz ponownie wdrożyć wszystkie funkcje w projekcie, w tym wszystkie zestawy funkcji, uruchamiając:
firebase deploy --only functions
Cofanie migracji
Aby cofnąć migrację, najpierw ponownie zainstaluj rozszerzenie. Aby znaleźć wartości konfiguracji potrzebne podczas instalacji, możesz użyć pliku .env zestawu.
Po wdrożeniu rozszerzenia odinstaluj instancję zestawu (spowoduje to odinstalowanie całego zestawu, jeśli jest to ostatnia pozostała instancja):
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
Zapisywanie konfiguracji rozszerzeń na potrzeby przyszłej migracji
Po 31 marca 2027 r. nie będzie można pobrać istniejącej konfiguracji rozszerzenia. Jeśli nie możesz przeprowadzić migracji przed 31 marca 2027 r., zdecydowanie zalecamy zapisanie rozszerzenia na wypadek, gdyby migracja miała nastąpić po tej dacie.
Uzyskaj listę identyfikatorów instancji rozszerzeń:
Aby uzyskać listę wszystkich instancji rozszerzeń w projekcie w Firebase, możesz użyć polecenia
ext:listw interfejsie wiersza poleceń:firebase ext:list --project <project-id>Przykład:
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-troubleshootingPolecenie
ext:listma też format wyjściowy JSON. Jeśli masz zainstalowane narzędzie jq, możesz go użyć, aby uzyskać listę wszystkich identyfikatorów instancji w projekcie:firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'Przykład:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'Dane wyjściowe:
firestore-bigquery-export-zbrp firestore-bigquery-exportWyeksportuj konfigurację każdej instancji:
W przypadku każdej instancji możesz zapisać jej konfigurację na dysku, wykonując to polecenie eksportu:
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>Przykład:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-exportDane wyjściowe:
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.testingNa dysku znajdziesz eksport tej instancji rozszerzenia w lokalizacji takiej jak
<instance-id>/.env.<project-id>. W tym przykładzie znajduje się on wfirestore-bigquery-export/.env.my-project.Możesz powtórzyć ten proces raz na instancję. Spowoduje to utworzenie zestawu plików
.envze wszystkimi konfiguracjami instancji rozszerzenia, które można później ponownie wykorzystać w ramach migracji.Przenieś wyeksportowane pliki
.envdo lepszej lokalizacji:Wyeksportowane pliki
.envz rozszerzeń zostały umieszczone bezpośrednio w projekcie w Firebase, ale nie są potrzebne na co dzień, jeśli nie przeprowadzono migracji do zestawów funkcji. Możesz przenieść je z projektu do dowolnej innej odpowiedniej lokalizacji, dopóki nie będą Ci potrzebne, lub je usunąć.