Pierwsze kroki: pisanie, testowanie i wdrażanie pierwszych funkcji (1 generacji)

Aby rozpocząć korzystanie z Cloud Functions, zapoznaj się z tym samouczkiem, który zaczyna się od wymaganych zadań konfiguracyjnych i obejmuje tworzenie, testowanie i wdrażanie 2 powiązanych funkcji:

• Funkcja „add message” (dodaj wiadomość), która udostępnia adres URL akceptujący wartość tekstową i zapisujący ją w Cloud Firestore.
• Funkcja „zmień na wielkie litery”, która jest aktywowana przez zapis w Cloud Firestore i przekształca tekst na wielkie litery.

W tym przykładzie wybraliśmy Cloud Firestore i funkcje JavaScript aktywowane przez HTTP, ponieważ te aktywatory działające w tle można dokładnie przetestować za pomocą Firebase Local Emulator Suite. Ten zestaw narzędzi obsługuje też Realtime Database, PubSub, Auth i wywoływalne aktywatory HTTP. Inne typy reguł działających w tle, takie jak Remote Config, TestLab i Analytics, można testować interaktywnie za pomocą zestawów narzędzi, które nie zostały opisane na tej stronie.

W kolejnych sekcjach tego samouczka znajdziesz szczegółowe instrukcje tworzenia, testowania i wdrażania przykładowej aplikacji. Jeśli wolisz po prostu uruchomić kod i go sprawdzić, przejdź do sekcji Przeglądanie pełnego przykładowego kodu.

Tworzenie projektu w Firebase

Konfigurowanie Node.js i interfejsu wiersza poleceń Firebase

Do pisania funkcji potrzebujesz środowiska Node.js, a do wdrażania funkcji w środowisku wykonawczym Cloud Functions – interfejsu wiersza poleceń Firebase. Do instalacji Node.js i npm zalecamy użycie Menedżera wersji Node.

Po zainstalowaniu Node.js i npm zainstaluj interfejs wiersza poleceń Firebase, korzystając z preferowanej metody. Aby zainstalować interfejs wiersza poleceń za pomocą npm, użyj:

npm install -g firebase-tools

Spowoduje to zainstalowanie polecenia firebase dostępnego na całym świecie. Jeśli polecenie się nie powiedzie, może być konieczna zmiana uprawnień npm. Aby zaktualizować firebase-tools do najnowszej wersji, uruchom ponownie to samo polecenie.

Inicjowanie projektu

Podczas inicjowania pakietu SDK Firebase dla Cloud Functions tworzysz pusty projekt zawierający zależności i minimalny przykładowy kod, a następnie wybierasz TypeScript lub JavaScript do tworzenia funkcji. Na potrzeby tego samouczka musisz też zainicjować Cloud Firestore.

Aby zainicjować projekt:

1. Uruchom firebase login, aby zalogować się przez przeglądarkę i uwierzytelnić interfejs wiersza poleceń Firebase.

2. Przejdź do katalogu projektu Firebase.

3. Uruchom firebase init firestore. W tym samouczku możesz zaakceptować wartości domyślne, gdy pojawi się prośba o podanie reguł Firestore i plików indeksu. Jeśli nie używasz jeszcze Cloud Firestore w tym projekcie, musisz też wybrać tryb początkowy i lokalizację dla Firestore, jak opisano w artykule Pierwsze kroki z Cloud Firestore.

4. Uruchom firebase init functions. Interfejs wiersza poleceń poprosi Cię o wybranie istniejącej bazy kodu lub zainicjowanie i nazwanie nowej. Na początku wystarczy jedna baza kodu w domyślnej lokalizacji. Później, gdy implementacja się rozrośnie, możesz uporządkować funkcje w bazach kodu.

5. Interfejs wiersza poleceń udostępnia te opcje obsługi języków:

   • JavaScript
   • Python
   • TypeScript Więcej informacji znajdziesz w artykule Pisanie funkcji w TypeScript.

   Na potrzeby tego samouczka wybierz JavaScript.

6. Interfejs wiersza poleceń umożliwia instalowanie zależności za pomocą npm. Jeśli chcesz zarządzać zależnościami w inny sposób, możesz bezpiecznie odrzucić tę opcję. Jeśli jednak to zrobisz, przed emulacją lub wdrożeniem funkcji musisz uruchomić npm install.

Po wykonaniu tych poleceń struktura projektu będzie wyglądać tak:

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

Plik package.json utworzony podczas inicjowania zawiera ważny klucz: "engines": {"node": "16"}. Określa wersję Node.js do pisania i wdrażania funkcji. Możesz wybrać inne obsługiwane wersje.

Importowanie wymaganych modułów i inicjowanie aplikacji

Po ukończeniu zadań konfiguracyjnych możesz otworzyć katalog źródłowy i zacząć dodawać kod zgodnie z opisem w kolejnych sekcjach. W tym przykładzie projekt musi importować moduły Cloud Functions i pakiet Admin SDK za pomocą instrukcji require Node. Dodaj do pliku index.js wiersze podobne do tych:

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();
index.js

Te wiersze wczytują moduły firebase-functions i firebase-admin oraz inicjują instancję aplikacji admin, z której można wprowadzać zmiany w Cloud Firestore. Wszędzie tam, gdzie dostępna jest obsługa pakietu Admin SDK, np. w przypadku FCM, Authentication i Firebase Realtime Database, zapewnia on zaawansowany sposób integracji Firebase za pomocą Cloud Functions.

Interfejs wiersza poleceń Firebase automatycznie instaluje moduły Firebase i Firebase SDK dla Cloud Functions Node podczas inicjowania projektu. Aby dodać do projektu biblioteki innych firm, możesz zmodyfikować package.json i uruchomić npm install. Więcej informacji znajdziesz w sekcji Obsługa zależności.

Dodaj funkcję addMessage()

W przypadku funkcji addMessage() dodaj te wiersze do pliku index.js:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});
index.js

Funkcja addMessage() jest punktem końcowym HTTP. Każde żądanie wysłane do punktu końcowego powoduje przekazanie obiektów Request i Response w stylu ExpressJS do wywołania zwrotnego onRequest().

Funkcje HTTP są synchroniczne (podobnie jak funkcje wywoływalne), więc należy jak najszybciej wysłać odpowiedź i odroczyć pracę za pomocą Cloud Firestore. Funkcja HTTP addMessage() przekazuje wartość tekstową do punktu końcowego HTTP i wstawia ją do bazy danych w ścieżce /messages/:documentId/original.

Dodaj funkcję makeUppercase()

W przypadku funkcji makeUppercase() dodaj te wiersze do pliku index.js:

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

Funkcja makeUppercase() jest wykonywana, gdy dane są zapisywane w Cloud Firestore. Funkcja ref.set określa dokument, który ma być nasłuchiwany. Ze względu na wydajność podaj jak najwięcej szczegółów.

Nawiasy klamrowe, np. {documentId}, otaczają „parametry”, czyli symbole wieloznaczne, które ujawniają dopasowane dane w wywołaniu zwrotnym.

Cloud Firestore wywołuje wywołanie zwrotne onCreate() za każdym razem, gdy dodawane są nowe wiadomości.

Funkcje oparte na zdarzeniach, takie jak zdarzenia Cloud Firestore, są asynchroniczne. Funkcja wywołania zwrotnego powinna zwracać wartość null, obiekt lub obietnicę. Jeśli nic nie zwrócisz, funkcja przekroczy limit czasu, sygnalizując błąd, i zostanie ponowiona. Zobacz Synchronizacja, asynchronizacja i obietnice.

Emulowanie wykonywania funkcji

Firebase Local Emulator Suite umożliwia tworzenie i testowanie aplikacji na komputerze lokalnym zamiast wdrażania ich w projekcie w Firebase. Zdecydowanie zalecamy testowanie lokalne podczas programowania, częściowo dlatego, że zmniejsza to ryzyko błędów w kodzie, które mogą potencjalnie generować koszty w środowisku produkcyjnym (np. pętla nieskończona).

Aby emulować funkcje:

1. Uruchom firebase emulators:start i sprawdź dane wyjściowe pod kątem adresu URL Emulator Suite UI. Domyślnie jest to localhost:4000, ale może być hostowany na innym porcie na Twoim komputerze. Wpisz ten adres URL w przeglądarce, aby otworzyć Emulator Suite UI.

2. Sprawdź dane wyjściowe polecenia firebase emulators:start, aby znaleźć adres URL funkcji HTTP addMessage(). Będzie on wyglądać podobnie do http://localhost:5001/MY_PROJECT/us-central1/addMessage, z tym że:

   1. MY_PROJECT zostanie zastąpiony identyfikatorem Twojego projektu.
   2. Port na komputerze lokalnym może być inny.

3. Dodaj ciąg zapytania ?text=uppercaseme na końcu adresu URL funkcji. Powinna ona wyglądać mniej więcej tak: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Opcjonalnie możesz zmienić wiadomość „uppercaseme” na niestandardową.

4. Utwórz nową wiadomość, otwierając adres URL w nowej karcie przeglądarki.

5. Wyświetl efekty działania funkcji w Emulator Suite UI:

   1. Na karcie Logi powinny pojawić się nowe logi wskazujące, że funkcje addMessage() i makeUppercase() zostały uruchomione:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. Na karcie Firestore powinien pojawić się dokument zawierający oryginalną wiadomość oraz jej wersję zapisaną wielkimi literami (jeśli oryginalna wiadomość to „zamieńnawielkielitery”, zobaczysz „ZAMIEŃNAWIELKIELITERY”).

wdrażać funkcje w środowisku produkcyjnym,

Gdy funkcje będą działać w emulatorze zgodnie z oczekiwaniami, możesz je wdrożyć, przetestować i uruchomić w środowisku produkcyjnym. Pamiętaj, że aby wdrożyć środowisko wykonawcze Node.js 14, Twój projekt musi być objęty abonamentem Blaze. Sprawdź ceny Cloud Functions.

Aby ukończyć samouczek, wdróż funkcje, a następnie wykonaj addMessage(), aby aktywować makeUppercase().

1. Uruchom to polecenie, aby wdrożyć funkcje:

    firebase deploy --only functions
    

   Po uruchomieniu tego polecenia interfejs wiersza poleceń Firebase wyświetli adres URL wszystkich punktów końcowych funkcji HTTP. W terminalu powinien pojawić się następujący wiersz:

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   Adres URL zawiera identyfikator projektu oraz region funkcji HTTP. Nie musisz się tym teraz przejmować, ale niektóre produkcyjne funkcje HTTP powinny określać lokalizację, aby zminimalizować opóźnienie sieci.

   Jeśli wystąpią błędy dostępu, takie jak „Nie udało się autoryzować dostępu do projektu”, sprawdź aliasy projektu.

2. Używając adresu URL addMessage() wygenerowanego przez interfejs wiersza poleceń, dodaj parametr zapytania tekstowego i otwórz go w przeglądarce:

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   Funkcja zostanie wykonana i przekieruje przeglądarkę do konsoli Firebase w lokalizacji bazy danych, w której przechowywany jest ciąg tekstowy. To zdarzenie zapisu aktywuje funkcję makeUppercase(), która zapisuje ciąg znaków wielkimi literami.

Po wdrożeniu i wykonaniu funkcji możesz wyświetlić logi w konsoli Google Cloud. Jeśli chcesz usunąć funkcje w środowisku programistycznym lub produkcyjnym, użyj interfejsu wiersza poleceń Firebase.

W środowisku produkcyjnym możesz zoptymalizować wydajność funkcji i kontrolować koszty, ustawiając minimalną i maksymalną liczbę instancji do uruchomienia. Więcej informacji o tych opcjach środowiska wykonawczego znajdziesz w artykule na temat kontrolowania skalowania.

Przeglądanie pełnego przykładowego kodu

Oto gotowy plik functions/index.js zawierający funkcje addMessage() i makeUppercase(). Te funkcje umożliwiają przekazanie parametru do punktu końcowego HTTP, który zapisuje wartość w Cloud Firestore, a następnie przekształca ją, zamieniając wszystkie znaki w ciągu na wielkie litery.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

Dalsze kroki

Z tej dokumentacji dowiesz się, jak zarządzać funkcjami w Cloud Functions oraz jak obsługiwać wszystkie typy zdarzeń obsługiwane przez Cloud Functions.

Aby dowiedzieć się więcej o Cloud Functions, możesz też wykonać te czynności:

• Przeczytaj o przypadkach użycia Cloud Functions.
• Wypróbuj ćwiczenie w Codelabs dotyczące Cloud Functions.
• Przeglądanie i uruchamianie przykładowego kodu na GitHubie