Uaktualnij funkcje Node.js 1 generacji do 2 generacji

Aplikacje korzystające z funkcji 1 generacji powinny rozważyć migrację do funkcji 2 generacji zgodnie z instrukcjami w tym przewodniku. Funkcje 2 generacji korzystają z Cloud Run, co zapewnia lepszą wydajność, lepszą konfigurację, lepsze monitorowanie i inne korzyści.

Przykłady na tej stronie zakładają, że używasz JavaScriptu z modułami CommonJS (importy w stylu require), ale te same zasady obowiązują w przypadku JavaScriptu z modułami ESM (importy w stylu import … from) i TypeScriptu.

Proces migracji

Funkcje 1 generacji i 2 generacji mogą współistnieć w tym samym pliku. Umożliwia to łatwą migrację krok po kroku, gdy tylko będziesz gotowy. Zalecamy migrację po jednej funkcji, a przed przejściem do następnej przeprowadzenie testów i weryfikacji.

Sprawdzanie wersji wiersza poleceń Firebase i firebase-function

Upewnij się, że używasz co najmniej wiersza poleceń Firebase w wersji 12.00 i firebase-functions w wersji 4.3.0. Każda nowsza wersja będzie obsługiwać zarówno funkcje 2, jak i 1 generacji.

Aktualizowanie importów

Funkcje 2 generacji importują z podpakietu v2 w pakiecie SDK firebase-functions. Ta inna ścieżka importu jest wszystkim, czego potrzebuje wiersz poleceń Firebase, aby określić, czy wdrożyć kod funkcji jako funkcję 1 czy 2 generacji.

Podpakiet v2 jest modułowy i zalecamy importowanie tylko tego modułu, którego potrzebujesz.

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 aktywatorów

Ponieważ pakiet SDK 2 generacji preferuje importy modułowe, zaktualizuj definicje aktywatorów, aby odzwierciedlały zmiany importów z poprzedniego kroku.

Zmieniły się argumenty przekazywane do wywołań zwrotnych niektórych aktywatorów. W tym przykładzie zwróć uwagę, że argumenty wywołania zwrotnego onDocumentCreated zostały skonsolidowane w jednym obiekcie event. Dodatkowo niektóre aktywatory mają wygodne nowe funkcje konfiguracyjne, takie jak opcja cors aktywatora 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) => {
  /* ... */
});

Używanie konfiguracji sparametryzowanej

Funkcje 2. generacji nie obsługują functions.config na rzecz bezpieczniejszego interfejsu do deklaratywnego definiowania parametrów konfiguracji w bazie kodu. Dzięki nowemu modułowi params interfejs wiersza poleceń blokuje wdrożenie, chyba że wszystkie parametry mają prawidłową wartość, co zapewnia, że funkcja nie zostanie wdrożona z brakującą konfiguracją.

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());
    // ...
  }
);

Jeśli masz istniejącą konfigurację środowiska z functions.config, przeprowadź migrację tej konfiguracji w ramach uaktualnienia do 2 generacji.

Interfejs API functions.config został wycofany i zostanie wyłączony w marcu 2027 r. Po tej dacie wdrożenia z functions.config będą się nie powodzić.

Aby zapobiec niepowodzeniom wdrożenia, przeprowadź migrację konfiguracji do Cloud Secret Manager za pomocą interfejsu wiersza poleceń Firebase. Jest to zdecydowanie zalecane jako najskuteczniejszy i najbezpieczniejszy sposób migracji konfiguracji.

  1. Eksportowanie konfiguracji za pomocą Firebase interfejsu wiersza poleceń

    Użyj polecenia config export, aby wyeksportować istniejącą konfigurację środowiska do nowego obiektu tajnego w Cloud Secret Manager:

    $ firebase functions:config:export
i  This command retrieves your Runtime Config values (accessed via functions.config())
   and exports them as a Secret Manager secret.

i  Fetching your existing functions.config() from your project...  ✔
   Fetched your existing functions.config().

i  Configuration to be exported:
⚠  This may contain sensitive data. Do not share this output.

{
   ...
}

✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG

✔  Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```

  2. Aktualizowanie kodu funkcji w celu powiązania obiektów tajnych

    Aby używać konfiguracji przechowywanej w nowym obiekcie tajnym w Cloud Secret Manager, użyj interfejsu API defineJsonSecret w źródle funkcji. Upewnij się też, że obiekty tajne są powiązane ze wszystkimi funkcjami, które ich potrzebują.

    Przed

    const functions = require("firebase-functions/v1");

exports.myFunction = functions.https.onRequest((req, res) => {
  const apiKey = functions.config().someapi.key;
  // ...
});

    Po

    const { onRequest } = require("firebase-functions/v2/https");
const { defineJsonSecret } = require("firebase-functions/params");

const config = defineJsonSecret("RUNTIME_CONFIG");

exports.myFunction = onRequest(
  // Bind secret to your function
  { secrets: [config] },
  (req, res) => {
    // Access secret values via .value()
    const apiKey = config.value().someapi.key;
    // ...
});

  3. Wdrażanie funkcji

    Wdróż zaktualizowane funkcje, aby zastosować zmiany i powiązać uprawnienia do obiektu tajnego.

    firebase deploy --only functions:<your-function-name>

Ustawianie opcji środowiska wykonawczego

Konfiguracja opcji środowiska wykonawczego zmieniła się między 1 a 2 generacją. 2 generacja dodaje 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) => {
  /* ... */
});

Aktualizowanie domyślnego konta usługi (opcjonalnie)

Funkcje 1 generacji używają domyślnego konta usługi Google App Engine do autoryzowania dostępu do interfejsów Firebase API, a funkcje 2 generacji używają domyślnego konta usługi Compute Engine. Ta różnica może prowadzić do problemów z uprawnieniami w przypadku funkcji przeniesionych do 2 generacji, jeśli przyznano specjalne uprawnienia kontu usługi 1 generacji. Jeśli nie zmieniono żadnych uprawnień konta usługi, możesz pominąć ten krok.

Zalecanym rozwiązaniem jest przypisanie istniejącego domyślnego konta usługi App Engine 1 generacji do funkcji, które chcesz przenieść do 2 generacji, zastępując domyślne konto 2 generacji. Możesz to zrobić, upewniając się, że każda przeniesiona funkcja ustawia prawidłową wartość serviceAccountEmail:

const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions");

// Use the App Engine default service account for all functions
setGlobalOptions({serviceAccountEmail: '<my-project-number>@<wbr>appspot.gserviceaccount.com'});

// Now I use the App Engine default service account.
exports.date = onRequest({cors: true}, (req, res) => {
  // ...
});

// I do too!
exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  // ...
});

Możesz też zmodyfikować szczegóły konta usługi, aby pasowały do wszystkich niezbędnych uprawnień zarówno na domyślnym koncie usługi App Engine (w przypadku 1 generacji), jak i na domyślnym koncie usługi Compute Engine (w przypadku 2 generacji).

Używanie współbieżności

Istotną zaletą funkcji 2 generacji jest możliwość obsługi przez jedną instancję funkcji więcej niż 1 żądania naraz. Może to znacznie zmniejszyć liczbę zimnych startów, z którymi spotykają się użytkownicy. Domyślnie współbieżność 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) => {
    // ...
});

Dostrajanie współbieżności może poprawić wydajność i obniżyć koszty funkcji. Więcej informacji o równoczesności znajdziesz w artykule Zezwalanie na żądania równoczesne.

Sprawdzanie użycia zmiennych globalnych

Funkcje 1 generacji napisane bez uwzględnienia współbieżności mogą używać zmiennych globalnych, które są ustawiane i odczytywane przy każdym żądaniu. Gdy równoczesność jest włączona, a jedna instancja zaczyna obsługiwać wiele żądań naraz, może to spowodować błędy w funkcji, ponieważ żądania równoczesne zaczynają jednocześnie ustawiać i odczytywać zmienne globalne.

Podczas uaktualniania możesz ustawić procesor funkcji na gcf_gen1 i concurrency na 1, aby przywrócić działanie 1 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 rozwiązanie długoterminowe, ponieważ powoduje utratę zalet wydajnościowych funkcji 2 generacji. Zamiast tego sprawdź użycie zmiennych globalnych w funkcjach i usuń te ustawienia tymczasowe, gdy będziesz gotowy.

Przenoszenie ruchu do nowych funkcji 2 generacji

Podobnie jak w przypadku zmiany regionu funkcji lub typu aktywatora, musisz nadać funkcji 2 generacji nową nazwę i powoli przenosić do niej ruch.

Nie można uaktualnić funkcji z 1 do 2 generacji pod tą samą nazwą i uruchomić firebase deploy. Spowoduje to błąd:

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 wersja i stara wersja funkcji. Jeśli na przykład masz funkcję 1 generacji, która reaguje na zdarzenia zapisu w Firestore, upewnij się, że reagowanie na zapis 2 razy (raz przez funkcję 1 generacji i raz przez funkcję 2 generacji) w odpowiedzi na te zdarzenia pozostawia aplikację w spójnym stanie.

  1. Zmień nazwę funkcji w kodzie funkcji. Na przykład zmień nazwę resizeImage na resizeImageSecondGen.
  2. Wdróż funkcję, aby działały zarówno oryginalna funkcja 1 generacji, jak i funkcja 2 generacji.
    1. W przypadku aktywatorów wywoływanych, kolejki zadań i HTTP zacznij kierować wszystkich klientów do funkcji 2 generacji, aktualizując kod klienta o nazwę lub adres URL funkcji 2 generacji.
    2. W przypadku aktywatorów w tle zarówno funkcja 1 generacji, jak i funkcja 2 generacji będą reagować na każde zdarzenie natychmiast po wdrożeniu.
  3. Gdy cały ruch zostanie przeniesiony, usuń funkcję 1 generacji za pomocą polecenia firebase functions:delete w wierszu poleceń Firebase.
    1. Opcjonalnie zmień nazwę funkcji 2 generacji, aby pasowała do nazwy funkcji 1 generacji.