Po przejściu z Firebase Extensions na zestaw funkcji możesz zarządzać instancjami zestawu jako standardowymi funkcjami 2 generacji Cloud Functions 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 cofać migrację.
Używanie pakietu funkcji z pakietu npm bez przenoszenia
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 interfejsu 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.
Zmienianie domyślnych opcji globalnych
Aby skonfigurować opcje globalne instancji zestawu, zmień plik index.ts znajdujący się w lokalizacji 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ć pakiet funkcji, uruchom to polecenie:
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!
Instalacja i wdrożenie zestawu wykonuje te działania:
- Tworzy
function-kits/firestore-bigquery-export/source, który zawiera źródło pakietu SDK, w tym podstawowy plikindex.ts, który importuje i eksportuje pakiet SDK, a także konfiguruje parametr umożliwiający wybór innej lokalizacji dla każdej instancji pakietu SDK. - Tworzy
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>i wypełnia go danymi konfiguracyjnymi wprowadzonymi dla funkcji. Jeśli w przyszłych aktualizacjach zostaną dodane nowe parametry, przy następnym wdrożeniu pojawi się odpowiedni komunikat. - Tworzy wymagane zasoby Google Cloud do uruchomienia tego zestawu, w tym konto usługi z określonymi rolami uprawnień, funkcje, wyzwalacze Eventarc i kolejki Cloud Tasks.
Jeśli w tym samym projekcie masz kilka instancji zestawu, możesz powtórzyć te polecenia, aby utworzyć i wdrożyć nowe instancje tego samego zestawu. Możesz też wdrożyć jedną instancję zestawu w kilku projektach Firebase z różnymi konfiguracjami (np. w projekcie testowym i produkcyjnym). Więcej informacji o zaawansowanych konfiguracjach znajdziesz w artykule Zaawansowane migracje.
Odinstalowywanie zestawu
Aby usunąć zestaw i wszystkie jego instancje, wpisz:
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 jedną 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 np. masz instancję zestawu o nazwie
firestore-bigquery-export w projekcie my-project, plik .env znajduje się w lokalizacji
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.
Wygląda to 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 prompta, który jest uruchamiany podczas instalacji i wdrażania, usuń z pliku .env parametry, które chcesz zmienić, 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 kod, podczas wdrażania pojawi się prośba o jego podanie:
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)
Utrzymywanie i uaktualnianie zestawu funkcji
Wydawcy mogą z czasem aktualizować pakiety npm, aby naprawiać błędy, dodawać funkcje, aktualizować zależności lub usuwać luki w zabezpieczeniach. Zalecamy śledzenie tych wersji i instalowanie aktualizacji, zwłaszcza tych, które eliminują luki 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 wdróż ponownie 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 tym katalogu source uruchom to polecenie, aby uzyskać raport o wszystkich nieaktualnych pakietach npm, w tym o zestawie funkcji i pakiecie SDK Cloud Functions:
npm outdated
Jeśli używasz już narzędzia do identyfikowania zależności, które wymagają aktualizacji, np. Dependabot w GitHubie, zalecamy zintegrowanie katalogu zestawu z tym procesem.
Aktualizowanie zestawu
Aby zaktualizować pakiet i jego zależności do najnowszej wersji, która nie powoduje problemów (z wyjątkiem aktualizacji do wersji głównej, które mogą zawierać zmiany powodujące problemy), uruchom to polecenie:
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 (która może wprowadzać zmiany powodujące niezgodność), uruchom to polecenie:
npm update --save <npm-package-name>@latest
Zapoznaj się z dokumentacją pakietu i informacjami o wersji, aby sprawdzić, co się zmieniło i czy przed wdrożeniem lub po nim musisz wykonać dodatkowe czynności, aby zapobiec zmianom powodującym niezgodność.
Wdrażanie zaktualizowanych instancji
Uruchomienie polecenia npm update aktualizuje tylko lokalny kod źródłowy. Aby zaktualizować działające funkcje w chmurze, wdróż je ponownie. Możesz ponownie wdrożyć wszystkie funkcje w projekcie, w tym wszystkie zestawy funkcji, uruchamiając to polecenie:
firebase deploy --only functions
Cofanie migracji
Aby cofnąć migrację, najpierw ponownie zainstaluj rozszerzenie. W .envpliku zestawu znajdziesz wartości konfiguracji potrzebne podczas instalacji.
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ś zdecydował(-a) się na migrację po tej dacie.
Uzyskaj listę identyfikatorów instancji rozszerzeń:
Aby uzyskać listę wszystkich instancji rozszerzeń w projekcie w Firebase, możesz użyć polecenia interfejsu wiersza poleceń
ext:list:firebase ext:list --project <project-id>Przykład:
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-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 wyeksportowaną instancję tego rozszerzenia w lokalizacji takiej jak
<instance-id>/.env.<project-id>. W tym przykładzie znajduje się on w lokalizacjifirestore-bigquery-export/.env.my-project.Możesz powtórzyć ten proces raz na instancję. W wyniku tego powstanie zestaw
.envplików ze wszystkimi konfiguracjami instancji rozszerzenia, które można później wykorzystać w ramach migracji.Przenieś wyeksportowane pliki
.envw lepsze miejsce: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, w której będą przechowywane do czasu, gdy będą potrzebne w przyszłości, lub możesz je usunąć.