Uaktualnij funkcje Node.js 1 generacji do 2 generacji

Aplikacje, które obecnie korzystają z funkcji 1 generacji, powinny rozważyć migrację do 2 generacji, korzystając z instrukcji zawartych w tym przewodniku. Funkcje 2 generacji korzystają z Cloud Run, aby zapewnić lepszą wydajność, lepszą konfigurację, lepszy monitoring itp.

W przykładach na tej stronie zakładamy, że używasz JavaScriptu z modułami CommonJS (importy stylów require), ale te same zasady dotyczą JavaScriptu z importami stylów ESM (import … from) i TypeScriptu.

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, aby przed przejściem dalej przenosić po jednej funkcji, a potem ją testować i weryfikować.

Weryfikacja interfejsu wiersza poleceń Firebase i wersji 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ć zarówno urządzenia 2 generacji, jak i 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");

Zaktualizuj definicje aktywatorów

Ponieważ pakiet SDK 2 generacji preferuje importowanie modułów, zaktualizuj definicje reguł, aby odzwierciedlały one 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. Poza tym niektóre aktywatory mają nowe, wygodne funkcje konfiguracji, 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żyj konfiguracji z parametrami

Funkcje 2 generacji przestają obsługiwać interfejs functions.config na rzecz bezpieczniejszego interfejsu do deklaratywnego definiowania parametrów konfiguracyjnych w bazie kodu. 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.

Przejdź do podpakietu 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 wyświetli prompt z prośbą 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ć typyreguły walidacji parametrów.

Przypadek specjalny: 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 obiektu tajnego.

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

Ustaw opcje ś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) => {
  /* ... */
});

Używaj równoczesności

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

Dostrajanie równoczesności może zwiększyć 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. Gdy równoczesność jest włączona, a pojedyncza instancja zaczyna obsługiwać wiele żądań jednocześnie, może to wprowadzić w Twojej funkcji błędy, gdy równoczesne żądania zaczynają ustawiać i odczytywać zmienne globalne jednocześnie.

Podczas uaktualniania możesz ustawić procesor funkcji na gcf_gen1, a 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 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.

Przeprowadź migrację ruchu do nowych funkcji 2 generacji

Tak jak przy zmianie regionu lub typu aktywatora funkcji, musisz nadać funkcji 2 generacji nową nazwę i stopniowo przenosić do niej ruch.

Nie można uaktualnić funkcji z 1 do 2 generacji o tej samej nazwie i uruchomić 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.

  1. Zmień nazwę funkcji w kodzie funkcji. Na przykład zmień nazwę resizeImage na resizeImageSecondGen.
  2. Wdróż funkcję, aby działała zarówno pierwotna funkcja 1 generacji, jak i funkcja 2 generacji.
    1. W przypadku aktywatorów wywoływanych, kolejki zadań i aktywatorów HTTP zacznij wskazywać wszystkim klientom funkcję 2 generacji, aktualizując kod klienta o nazwę lub adres URL funkcji 2 generacji.
    2. W przypadku reguł działających w tle funkcje 1 i 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 interfejsie wiersza poleceń Firebase.
    1. Opcjonalnie zmień nazwę funkcji 2 generacji, aby pasowała do nazwy funkcji 1 generacji.