| Wybierz ścieżkę migracji: | Migracja do pakietów funkcji w npm Migracja do samodzielnie utworzonego pakietu funkcji |
Jeśli wydawca nie utworzył oficjalnego zestawu zastępczego rozpowszechnianego w npm, ten przewodnik zawiera instrukcje, jak rozwidlić jego rozszerzenie i skonfigurować je jako lokalny zestaw funkcji.
Sprawdzanie znanych ograniczeń migracji
Zanim rozpoczniesz migrację instancji rozszerzenia, sprawdź, czy Twoja konfiguracja korzysta z którejś z tych funkcji, które wymagają obejścia lub nie są jeszcze obsługiwane w zestawach funkcji:
- Niestandardowe repozytoria Dockera i klucze KMS wymagają ręcznego obejścia Cloud Functions for Firebase nie obsługuje parametrów systemu zastępczego do konfigurowania niestandardowego repozytorium Dockera ani klucza szyfrowania zarządzanego przez klienta (klucza KMS). Jeśli rozszerzenie konfiguruje którykolwiek z tych parametrów, zapoznaj się z obejściem problemu w sekcji z najczęstszymi pytaniami.
Zanim zaczniesz
Musisz skonfigurować interfejs wiersza poleceń Firebase i zainicjować projekt Firebase. Jeśli używasz interfejsu wiersza poleceń, upewnij się, że korzystasz z firebase-tools wersji >= 15.32.0, która zawiera nowe polecenia migracji i zestawu funkcji.
Wymagane uprawnienia i role konta
W zależności od tego, co musi zostać utworzone i skonfigurowane przez Firebase CLI podczas migracji, konto, którego używasz do uwierzytelniania w Firebase i Google Cloud, musi mieć te role:
roles/firebaseextensions.editorroles/cloudbuild.builds.editorroles/artifactregistry.writerroles/run.developerroles/iam.serviceAccountUserroles/iam.serviceAccountCreatorroles/cloudfunctions.admin(jeśli musiszsetIamPermissionsto zrobić w przypadku publicznych punktów końcowych)roles/secretmanager.admin(jeśli używasz obiektów tajnych)roles/serviceusage.serviceUsageAdmin(jeśli musisz włączyć nowe interfejsy API)
Zalecamy używanie konta, na którym zainstalowano już rozszerzenia i wdrożono funkcje, ponieważ większość tych uprawnień będzie już przyznana. Jeśli przenoszone konto potrzebuje więcej ról, postępuj zgodnie z Google Cloudinstrukcjami dotyczącymi uprawnień, aby je dodać.
Uaktualnianie instancji rozszerzenia do najnowszej wersji
Aby zminimalizować różnicę między instancją rozszerzenia a zestawem zastępczym, musisz zaktualizować rozszerzenie do najnowszej wersji. Jeśli rozszerzenie nie zostanie uaktualnione, między instancją rozszerzenia a zestawem zastępczym mogą wystąpić istotne zmiany powodujące problemy. Wyeksportowana konfiguracja może nie pasować do oczekiwań zestawu z powodu zmian parametrów w różnych wersjach.
Aby zaktualizować rozszerzenie, skorzystaj z jednej z tych opcji w zależności od tego, gdzie zostało ono zainstalowane:
- W Firebasekonsoli
- Z interfejsu wiersza poleceń Firebase za pomocą tego polecenia:
firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>
Jeśli pominiesz ten krok, interfejs wiersza poleceń wyświetli prośbę o uaktualnienie podczas eksportowania konfiguracji, jeśli rozszerzenie nie jest w najnowszej wersji.
Skopiuj rozszerzenie do lokalnego zestawu funkcji
Zanim zaczniesz przekształcać rozszerzenie w lokalny zestaw funkcji, upewnij się, że kod źródłowy rozszerzenia znajduje się w projekcie Firebase. Aby to zrobić, sklonuj repozytorium rozszerzenia z GitHuba, utwórz katalog w Firebase katalogu głównym projektu i skopiuj do niego folder functions/ rozszerzenia oraz plik extension.yaml:
mkdir -p path/to/kit
cp -r /path/to/extension-source/functions/* path/to/kit/
cp /path/to/extension-source/extension.yaml path/to/kit/.
Wykonaj kroki 1–8 z przewodnika po migracji dla wydawców, aby przenieść kod źródłowy rozszerzenia do funkcji 2 generacji. Następnie wykonaj te czynności:
Wprowadzenie obsługi regionu wyeksportowanej funkcji i parametrów zaawansowanych w lokalnym zestawie narzędzi
W lokalnym zestawie funkcji interfejs Firebase nie generuje pliku index.ts
do skonfigurowania pakietu i ustawienia w nim migracji parametrów systemowych.
Aby używać regionu funkcji i parametrów zaawansowanych skonfigurowanych dla rozszerzenia, skonfiguruj plik index.ts tak, aby odczytywał format wyeksportowany przez firebase
ext:export --mode functions do pliku zmiennej środowiskowej.
W pliku najwyższego poziomu index.ts, który eksportuje funkcje, zdefiniuj parametr dla FUNCTION_DEFAULT_REGION i wywołaj setGlobalOptions z zmiennymi środowiskowymi w formacie EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>, podobnie jak w szablonie index-kit-migration.ts używanym przez interfejs CLI:
import { setGlobalOptions } from "firebase-functions";
import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options";
import { defineString } from "firebase-functions/params";
export const regionParam = defineString("FUNCTION_DEFAULT_REGION", {
input: { text: { nonEmpty: true } },
description: "Global default region where functions should be deployed. Can be overridden per-function.",
});
setGlobalOptions({
region: regionParam,
memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined,
timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS
? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS)
: undefined,
vpcConnectorEgressSettings:
process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS &&
process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED"
? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting)
: undefined,
vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined,
maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES
? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES)
: undefined,
minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES
? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES)
: undefined,
ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined,
// Parses a comma-separated string of key:value pairs into a key-value object
// (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }).
labels: process.env.EXT_MIGRATED_SYSTEM_LABELS
? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce<Record<string, string> | undefined>(
(acc, curr) => {
const [key, value] = curr.split(":");
const trimmedKey = key?.trim();
const trimmedValue = value?.trim();
if (!trimmedKey || !trimmedValue) {
return acc;
}
acc = acc ?? {};
acc[trimmedKey] = trimmedValue;
return acc;
},
undefined,
)
: undefined,
});
// Re-export all functions so the Firebase CLI can deploy them
export * from "./your-functions";
Przetestuj zestaw przed migracją
Masz teraz lokalny zestaw funkcji, który po wdrożeniu działa identycznie jak nowa instalacja rozszerzenia. Następnym krokiem jest sprawdzenie i naprawienie wszelkich problemów, które mogły się pojawić po drodze, zanim przeniesiesz na nią instancje rozszerzenia produkcyjnego.
Najpierw dodaj fork jako lokalny pakiet SDK, skonfiguruj go i wdroż go w projekcie testowym. Zestawy funkcji lokalnych muszą znajdować się w projekcie Firebase, więc jeśli sklonowane repozytorium rozszerzenia znajduje się poza projektem Firebase, przenieś je do katalogu projektu. Następnie uruchom to polecenie instalacji pakietu, aby zainstalować go jako pakiet lokalny:
firebase functions:kits:install --directory <path-to-your-fork> --project <test-project-id>
To polecenie przeprowadzi Cię przez wybór identyfikatora zestawu, identyfikatora instancji i konfiguracji pierwszej instancji testowej. Następnie modyfikuje plik firebase.json, aby zarejestrować lokalny zestaw narzędzi wskazujący rozwidlony katalog, z konfiguracjami poszczególnych instancji przechowywanymi w pliku .env w lokalizacji function-kits/<kit-id>/config-<instance-id>.
Wdróż lokalny zestaw w projekcie testowym z odpowiednimi zasobami, aby przetestować jego działanie. Jeśli masz już projekt testowy skonfigurowany na potrzeby testowania rozszerzenia, uruchom to polecenie:
firebase deploy --only functions:<kit-instance-id> --project <test-project-id>
Przykład: przesyłanie strumieniowe z Cloud Firestore do BigQuery (firestore-bigquery-export)
Sprawdź pełne szyfrowanie synchronizacji Cloud Firestore z BigQuery:
- Na stronie Cloud Firestore w Firebase konsoli utwórz kolekcję, którą ustawisz jako
COLLECTION_PATH(users), jeśli jeszcze nie istnieje. - Utwórz dokument o nazwie
bigquery-mirror-testzawierający dowolne pola z dowolnymi wartościami. Na stronie BigQuery w konsoli Google Cloud wyślij zapytanie do tabeli raw changelog. Powinien zawierać jeden wiersz rejestrujący utworzenie dokumentu:
SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`Wyślij zapytanie o najnowszą wersję, która powinna zwrócić najnowsze zdarzenie zmiany w jedynym obecnym dokumencie (
bigquery-mirror-test):SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`Usuń dokument
bigquery-mirror-testw Cloud Firestore. Znika z widoku najnowszych zmian, a do tabeli z surowym dziennikiem zmian dodawane jest zdarzenieDELETE.Pełną historię pojedynczego dokumentu możesz sprawdzić za pomocą tego polecenia:
SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog` WHERE document_name = "bigquery-mirror-test" ORDER BY timestamp ASC
Różnice w porównaniu z testowaniem rozszerzenia:
- Reguła jest wdrażana jako
kit-<kit-instance-id>-fsexportbigquery, a nieext-<instanceId>-fsexportbigquery. Poszukaj tej nazwy w panelu Cloud Functions i dziennikach. - Kod jest uruchamiany w Firebase Local Emulator Suite jako funkcje standardowe. Wartości parametrów, które mają być używane w emulatorze, możesz ustawić za pomocą
.env.local. Możesz też przeprowadzić testy jednostkowe kodu za pomocą pakietufirebase-functions-testSDK, jak opisano w sekcji Testy jednostkowe Cloud Functions. - Inicjowanie nie jest już oparte na środowisku wykonawczym rozszerzeń. Jeśli po wdrożeniu brakuje tabeli dziennika zmian, ponownie uruchom ręcznie zadanie konfiguracji:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>Zadanie jest idempotentne, więc ponowne jego uruchomienie spowoduje uzgodnienie zbioru danych, tabeli i widoków. - Wartości parametrów pochodzą z
.env, a nie z formularza instalacji, więc ponowne uruchomieniafirebase deploysą nieinteraktywne po zakończeniu.env.
(Opcjonalnie) Usuwanie danych po testach
Jeśli po zakończeniu testowania chcesz usunąć tę instancję testową, odinstaluj ją:
firebase functions:kits:uninstall --instance <kit-instance-id> --project <test-project-id>
Spowoduje to usunięcie wszystkich zasobów w chmurze utworzonych podczas wdrażania zestawu i usunięcie konfiguracji jego instancji. Jeśli masz tylko 1 zestaw, spowoduje to również usunięcie wpisu o zestawie z firebase.json. Nie powoduje usunięcia lokalnego katalogu z kodem źródłowym. Podczas instalowania zestawu na potrzeby migracji produkcyjnej możesz ponownie wybrać identyfikator zestawu.
Migracja z rozszerzeń do lokalnego zestawu
Po przetestowaniu lokalnego pakietu możesz przenieść wdrożoną instancję rozszerzenia.
1. Instalowanie instancji zestawu funkcji zastępowania
Zainstaluj lokalny zestaw funkcji, przekazując --no-configure, aby pominąć ręczną konfigurację. Dzięki temu w następnym kroku możesz wyeksportować istniejącą konfigurację rozszerzenia bezpośrednio do tej instancji zestawu:
firebase functions:kits:install --no-configure --directory <path-to-your-fork> --project <project-id>
2. Skonfiguruj instancję pakietu funkcji identycznie jak rozszerzenie.
Musisz dostosować tę instancję zestawu za pomocą konfiguracji identycznej z zastępowanym rozszerzeniem. Możesz wyeksportować konfigurację instancji rozszerzenia do pliku .env, który przechowuje dane konfiguracji parametrów, zmiennych środowiskowych i odwołań do kluczy tajnych dla wszystkich Cloud Functions, w tym zestawów. Aby wyeksportować go bezpośrednio do pliku konfiguracji zestawu, uruchom:
firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>
Po wykonaniu tego kroku informacje o konfiguracji tej instancji zostaną zapisane w pliku .env w katalogu konfiguracji instancji, np.:function-kits/<kit-name>/config-<instance-id>/.env.<project-id>
3. Wdrażanie i weryfikowanie wymiany zestawu
Po zainstalowaniu zestawu i udostępnieniu go jako zestawu funkcji możesz wdrożyć zamiennik zestawu. Zestawy funkcji działają jak standardowe funkcje, przy czym każda instancja zestawu pełni funkcję osobnej bazy kodu do organizowania funkcji. Możesz wdrożyć wszystkie funkcje lub tylko konkretną instancję zestawu. Podczas migracji pojedynczej instancji rozszerzenia wdróż tylko tę instancję pakietu.
Jeśli zestaw korzysta z nowych parametrów, których nie było w instancji rozszerzenia, z której przeprowadzono migrację, interfejs wiersza poleceń Firebase poprosi o ich podanie na początku procesu wdrażania. W tym przykładzie nie jest to oczekiwane w przypadku aktualnego rozszerzenia firestore-bigquery-export, ale wiele zestawów SDK wyświetla prośbę o podanie nowego parametru dla każdego źródła wyzwalającego zdarzenie używanego przez zestaw SDK. W ramach tej migracji zaktualizowane zestawy korzystają z funkcji 2 generacji, podczas gdy rozszerzenia wcześniej używały funkcji 1 generacji. W przypadku funkcji 2 generacji znajdują się one w pobliżu źródeł zdarzeń i są dodawane jako dodatkowy parametr. W przyszłych aktualizacjach, jeśli zostaną dodane nowe parametry, interfejs CLI wyświetli prośbę o ich podanie podczas następnego wdrażania.
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!
Aby sprawdzić, czy firebase deploy zestawu nie zawierał błędów, przejrzyj dzienniki wdrażania i sprawdź, czy zostały wywołane jakieś punkty zaczepienia cyklu życia. Popularne rozszerzenia, takie jak Stream Cloud Firestore to BigQuery, korzystają z haków cyklu życia. Oto przykład wywołania haka cyklu życia:
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/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project
Te wiadomości w dzienniku potwierdzają:
- Wykryto i wykonano funkcję cyklu życia.
- Zadanie zostało umieszczone w kolejce zadań powiązanej z punktem zaczepienia cyklu życia.
- Podano link do Cloud Logging, aby można było sprawdzić, czy zadanie zostało wykonane bez błędów.
Kliknij link do dzienników w konsoli Google Cloud, aby sprawdzić, czy w dziennikach nie ma błędów i czy zdarzenie kolejki zadań zostało przetworzone. Jeśli zdarzenie cyklu życia nie zostało wykonane prawidłowo, możesz je ponownie wywołać, uruchamiając to polecenie:
firebase functions:lifecycle:run <hook-name> <codebase>
Jeśli wdrażasz instancję pakietu funkcji po raz pierwszy, uruchom to polecenie:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
Jeśli w dowolnym momencie w trakcie weryfikacji zdecydujesz, że chcesz przerwać lub cofnąć tę migrację, możesz odinstalować zestaw, postępując zgodnie z instrukcjami w sekcji Odinstalowywanie rozszerzenia.
4. Odinstalowywanie rozszerzenia
Gdy sprawdzisz wdrożony zestaw funkcji, możesz odinstalować rozszerzenie, aby nie powielać jego działania – raz w przypadku zestawu i raz w przypadku rozszerzenia. Możesz odinstalować wszystkie rozszerzenia z Firebase CLI
niezależnie od tego, jak zostały zainstalowane, jeśli przekażesz flagę --immediate:
firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate
Przykład:
firebase ext:uninstall firestore-bigquery-export --project my-project --immediate
Dane wyjściowe:
i extensions: uninstalling firestore-bigquery-export...
i extensions: deleting extension instance resources in project my-project...
✔ extensions: successfully uninstalled firestore-bigquery-export
Zaawansowane migracje
Możesz mieć rozszerzenia w wielu projektach Firebase, którymi chcesz zarządzać za pomocą jednej bazy kodu. Jeśli na przykład wdrażasz tę samą infrastrukturę w środowiskach testing i production, z których każde ma instancję documents Cloud Firestore eksportowaną do BigQuery, możesz mieć zainstalowane 2 instancje rozszerzenia firestore-bigquery-export:
export-documents-testingexport-documents-production
Jeśli podczas pracy z interfejsem wiersza poleceń Firebase przeniesiesz te 2 instancje rozszerzeń do 2 instancji zestawu funkcji w jednej bazie kodu i wdrożysz je za pomocą poleceń firebase deploy --project testing i firebase deploy --project production, każde wdrożenie utworzy 2 instancje w środowiskach testing i production.
Zamiast tego zastąp 2 instancje rozszerzenia 1 instancją zestawu funkcjifirestore-bigquery-export wdrożoną w wielu projektach, z których każdy ma własną konfigurację. Katalog konfiguracji instancji powinien wyglądać tak:
config-export-documents/.env.testing.env.production
Każde wdrożenie w usługach testing i production tworzy 1 instancję zestawu z odpowiednią konfiguracją. Obecne polecenia interfejsu CLI tworzą tę konfigurację, o ile w każdym wywołaniu polecenia --project lub ext:migrate albo functions:kits:install podasz flagę --project.
Przykład:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔ Wrote function-kits/firestore-bigquery-export/source/package.json
✔ Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔ Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔ Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i functions: Running npm install
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
--kit-instance export-documents --project testing
# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
--kit-instance export-documents --project production
Masz teraz jedną instancję zestawu skonfigurowaną do wdrażania w projektach testing i production z odpowiednimi konfiguracjami. Jeśli utworzysz instancję w projekcie testing i uruchomisz polecenie functions:kits:install dla tego samego pakietu w projekcie production, pojawi się prośba o ponowne użycie instancji skonfigurowanej dla projektu testing lub zainstalowanie drugiej instancji.