Aplikacje, które obecnie korzystają z funkcji 1 generacji, powinny rozważyć migrację do 2 generacji, korzystając z instrukcji w tym przewodniku. Funkcje 2 generacji korzystają z Cloud Run, aby zapewnić lepszą wydajność, lepszą konfigurację, lepszy monitoring itp.
Przykłady na tej stronie zakładają, że używasz JavaScriptu z modułami CommonJS (importy w stylu require), ale te same zasady dotyczą JavaScriptu z ESM (importy w stylu import … from) i TypeScript.
Proces migracji
Funkcje 1 i 2 generacji mogą współistnieć w tym samym pliku. Dzięki temu możesz łatwo przeprowadzić migrację, wykonując poszczególne kroki w miarę potrzeb. Zalecamy przenoszenie jednej funkcji naraz, a przed dalszymi działaniami przetestowanie i weryfikację.
Sprawdź wersje wiersza poleceń Firebase i firebase-function
Upewnij się, że używasz co najmniej wersji 12.00 wiersza poleceń Firebase i wersji firebase-functions 4.3.0. Wszelkie nowsze wersje będą obsługiwać urządzenia 2 generacji, a także 1 generacji.
Aktualizowanie importów
Funkcje 2 generacji importowane z podpakietu v2 w pakiecie SDK firebase-functions.
Ta odmienna ścieżka importowania wystarczy, aby interfejs wiersza poleceń Firebase mógł określić, czy wdrożyć kod funkcji jako funkcję 1 czy 2 generacji.
Podpakiet v2 jest modułowy i zalecamy importowanie tylko potrzebnych modułów.
Przed: 1 generacja
const functions = require("firebase-functions/v1");
Po: 2 generacja
// explicitly import each trigger
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
Aktualizowanie definicji reguł
Ponieważ pakiet SDK 2 generacji preferuje importowanie modułów, zaktualizuj definicje reguł, aby odzwierciedlały zmienione importy z poprzedniego kroku.
Argumenty przekazywane do funkcji wywołujących w przypadku niektórych reguł uległy zmianie. W tym przykładzie argumenty funkcji zwracanej onDocumentCreated zostały scalone w jeden obiekt event. Dodatkowo niektóre reguły mają nowe, wygodne funkcje konfiguracji, np. opcję cors reguły onRequest.
Przed: 1 generacja
const functions = require("firebase-functions/v1");
exports.date = functions.https.onRequest((req, res) => {
// ...
});
exports.uppercase = functions.firestore
.document("my-collection/{docId}")
.onCreate((change, context) => {
// ...
});
Po: 2 generacja
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
exports.date = onRequest({cors: true}, (req, res) => {
// ...
});
exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
/* ... */
});
Korzystanie z konfiguracji parametrycznej
Funkcje 2 generacji nie obsługują już functions.config, ponieważ oferują bezpieczniejszy interfejs do deklaratywnego definiowania parametrów konfiguracji w kodzie. W nowym module params interfejs wiersza poleceń blokuje wdrożenie, chyba że wszystkie parametry mają prawidłową wartość. Dzięki temu funkcja nie zostanie wdrożona z brakującym elementem konfiguracji.
Przejście na podpakiet params
Jeśli używasz konfiguracji środowiska z użyciem functions.config, możesz przenieść dotychczasową konfigurację do konfiguracji z parametrami.
Przed: 1 generacja
const functions = require("firebase-functions/v1");
exports.date = functions.https.onRequest((req, res) => {
const date = new Date();
const formattedDate =
date.toLocaleDateString(functions.config().dateformat);
// ...
});
Po: 2 generacja
const {onRequest} = require("firebase-functions/v2/https");
const {defineString} = require("firebase-functions/params");
const dateFormat = defineString("DATE_FORMAT");
exports.date = onRequest((req, res) => {
const date = new Date();
const formattedDate = date.toLocaleDateString(dateFormat.value());
// ...
});
Ustawianie wartości parametrów
Podczas pierwszego wdrożenia narzędzie wiersza poleceń Firebase poprosi o wszystkie wartości parametrów i zapisze je w pliku dotenv. Aby wyeksportować wartości z pliku functions.config, uruchom firebase functions:config:export.
Aby zwiększyć bezpieczeństwo, możesz też określić typy i reguły walidacji parametrów.
Przypadek szczególny: klucze interfejsu API
Moduł params integruje się z usługą Cloud Secret Manager, która zapewnia szczegółową kontrolę dostępu do wartości poufnych, takich jak klucze interfejsu API. Więcej informacji znajdziesz w sekcji parametry tajne.
Przed: 1 generacja
const functions = require("firebase-functions/v1");
exports.getQuote = functions.https.onRequest(async (req, res) => {
const quote = await fetchMotivationalQuote(functions.config().apiKey);
// ...
});
Po: 2 generacja
const {onRequest} = require("firebase-functions/v2/https");
const {defineSecret} = require("firebase-functions/params");
// Define the secret parameter
const apiKey = defineSecret("API_KEY");
exports.getQuote = onRequest(
// make the secret available to this function
{ secrets: [apiKey] },
async (req, res) => {
// retrieve the value of the secret
const quote = await fetchMotivationalQuote(apiKey.value());
// ...
}
);
Ustawianie opcji środowiska wykonawczego
Konfiguracja opcji czasu wykonywania zmieniła się między 1 a 2 generacją. 2 generacja wprowadza też nową możliwość ustawiania opcji dla wszystkich funkcji.
Przed: 1 generacja
const functions = require("firebase-functions/v1");
exports.date = functions
.runWith({
// Keep 5 instances warm for this latency-critical function
minInstances: 5,
})
// locate function closest to users
.region("asia-northeast1")
.https.onRequest((req, res) => {
// ...
});
exports.uppercase = functions
// locate function closest to users and database
.region("asia-northeast1")
.firestore.document("my-collection/{docId}")
.onCreate((change, context) => {
// ...
});
Po: 2 generacja
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions/v2");
// locate all functions closest to users
setGlobalOptions({ region: "asia-northeast1" });
exports.date = onRequest({
// Keep 5 instances warm for this latency-critical function
minInstances: 5,
}, (req, res) => {
// ...
});
exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
/* ... */
});
Korzystanie z równoczesnego wykonywania
Jedną z istotne zalet funkcji 2 generacji jest możliwość obsługi przez pojedynczą instancję funkcji większej liczby żądań jednocześnie. Może to znacznie zmniejszyć liczbę uruchomień „na zimno” przez użytkowników. Domyślnie równoczesność jest ustawiona na 80, ale możesz ustawić dowolną wartość od 1 do 1000:
const {onRequest} = require("firebase-functions/v2/https");
exports.date = onRequest({
// set concurrency value
concurrency: 500
},
(req, res) => {
// ...
});
Dostosowywanie współbieżności może poprawić wydajność i zmniejszyć koszty funkcji. Dowiedz się więcej o jednoczesności w artykule Zezwalanie na jednoczesne żądania.
Sprawdzanie wykorzystania zmiennych globalnych
Funkcje 1 generacji napisane bez uwzględnienia współbieżności mogą używać zmiennych globalnych, które są ustawiane i odczytywane w ramach każdego żądania. Jeśli równoczesność jest włączona i pojedyncza instancja zaczyna obsługiwać wiele żądań jednocześnie, może to spowodować błędy w funkcji, ponieważ równoczesne żądania zaczynają jednocześnie ustawiać i czytać zmienne globalne.
Podczas uaktualniania możesz ustawić procesor funkcji na gcf_gen1, a concurrency na 1, aby przywrócić działanie funkcji w pierwszej generacji:
const {onRequest} = require("firebase-functions/v2/https");
exports.date = onRequest({
// TEMPORARY FIX: remove concurrency
cpu: "gcf_gen1",
concurrency: 1
},
(req, res) => {
// ...
});
Nie jest to jednak zalecane jako długoterminowe rozwiązanie, ponieważ powoduje utratę zalet funkcji 2 generacji. Zamiast tego sprawdź użycie zmiennych globalnych w funkcjach i usuń te tymczasowe ustawienia, gdy już to zrobisz.
przenieść ruch do nowych funkcji 2 generacji.
Podobnie jak w przypadku zmiany regionu lub typu reguły, musisz nadać funkcji 2 generacji nową nazwę i powoli przenosić na nią ruch.
Nie można uaktualnić funkcji 1 generacji do 2 generacji o tej samej nazwie i uruchomić funkcji firebase deploy. Spowoduje to wyświetlenie tego komunikatu o błędzie:
Upgrading from GCFv1 to GCFv2 is not yet supported. Please delete your old function or wait for this feature to be ready.
Zanim wykonasz te czynności, upewnij się, że funkcja jest idempotentna, ponieważ podczas zmiany będą działać jednocześnie nowa i stara wersja funkcji. Jeśli na przykład masz funkcję 1 generacji, która reaguje na zdarzenia zapisu w Firestore, upewnij się, że w odpowiedzi na te zdarzenia funkcja 1 generacji reaguje na zapis dwukrotnie, a funkcja 2 generacji reaguje na niego raz. Dzięki temu aplikacja będzie w spójnym stanie.
- Zmień nazwę funkcji w kodzie funkcji. Na przykład zmień nazwę
resizeImagenaresizeImageSecondGen. - Wdróż funkcję, aby działała zarówno pierwotna funkcja 1 generacji, jak i funkcja 2 generacji.
- W przypadku wywoływalnych funkcji, kolejek zadań i aktywacji HTTP zacznij kierować wszystkich klientów do funkcji 2 generacji, aktualizując kod klienta o nazwa lub adres URL funkcji 2 generacji.
- W przypadku reguł działających w tle funkcje 1 i 2 generacji będą reagować na każde zdarzenie natychmiast po wdrożeniu.
- Gdy cały ruch zostanie przeniesiony, usuń funkcję 1 generacji za pomocą polecenia
firebase functions:deletew interfejsie wiersza poleceń Firebase.- Opcjonalnie zmień nazwę funkcji 2 generacji, aby pasowała do nazwy funkcji 1 generacji.