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

Aby rozpocząć korzystanie z Cloud Functions, wykonaj czynności opisane w tym samouczku, Zaczyna się on od wymaganych zadań konfiguracyjnych, a następnie opisuje 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 „make uppercase” (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 aktywatory wywoływane przez HTTP. Inne typy aktywatorów działających w tle takich jak Remote Config, TestLab i Analytics, można testować interaktywnie za pomocą zestawów narzędzi, które nie są opisane na tej stronie.

W kolejnych sekcjach tego samouczka opisujemy kroki wymagane do utworzenia, przetestowania i wdrożenia przykładu. Jeśli wolisz po prostu uruchomić kod i go sprawdzić, przejdź do sekcji Przeglądanie pełnego przykładowego kodu.

Tworzenie projektu Firebase

Konfigurowanie Node.js i 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 instalowania Node.js i npm, zalecany jest Menedżer wersji Node.

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

npm install -g firebase-tools

Spowoduje to zainstalowanie polecenia firebase dostępnego globalnie. 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

Gdy zainicjujesz Firebase SDK dla Cloud Functions, utworzysz pusty projekt zawierający zależności i minimalny przykładowy kod. Wybierzesz też język 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ę w przeglądarce i uwierzytelnić Firebase interfejs wiersza poleceń.

2. Otwórz katalog projektu w Firebase.

3. Uruchom polecenie firebase init firestore. Na potrzeby tego samouczka 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ę Firestore zgodnie z opisem w artykule Pierwsze kroki z Cloud Firestore.

4. Uruchom polecenie firebase init functions. Interfejs wiersza poleceń wyświetli prośbę o wybranie istniejącej bazy kodu lub zainicjowanie i nazwanie nowej. Na początek wystarczy jedna baza kodu w domyślnej lokalizacji. Później, gdy implementacja się rozrośnie, możesz chcieć zorganizować funkcje w bazach kodu.

5. Interfejs wiersza poleceń oferuje 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 zainstalowanie zależności za pomocą npm. Możesz odmówić, jeśli chcesz zarządzać zależnościami w inny sposób. Jeśli jednak odmówisz, przed emulowaniem lub wdrożeniem funkcji musisz uruchomić polecenie npm install.

Po pomyślnym 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 on wersję Node.js do pisania i wdrażania funkcji. Możesz wybrać inne obsługiwane wersje.

Importowanie wymaganych modułów i inicjowanie aplikacji

Po wykonaniu 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 pakietu Admin SDK za pomocą instrukcji Node require. Dodaj do pliku index.js wiersze takie jak te:

// 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 admin = require("firebase-admin");
admin.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 skuteczny sposób integracji Firebase za pomocą Cloud Functions.

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

Dodawanie funkcji addMessage()

Aby dodać funkcję 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 admin
    .firestore()
    .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() to punkt końcowy HTTP. Każde żądanie do punktu końcowego powoduje przekazanie do wywołania zwrotnego onRequest() obiektów żądania Request i Response w stylu ExpressJS.

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

Dodawanie funkcji makeUppercase()

Aby dodać funkcję 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órego ma nasłuchiwać. Ze względu na wydajność należy być jak najbardziej precyzyjnym.

Nawiasy klamrowe, np. {documentId}, otaczają „parametry”, czyli symbole wieloznaczne, które udostępniają 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 reagujące na zdarzenia, takie jak Cloud Firestore zdarzenia, są asynchroniczne. Funkcja wywołania zwrotnego powinna zwracać wartość null, obiekt, lub obietnicę. Jeśli nie zwrócisz niczego, funkcja przekroczy limit czasu, co oznacza błąd, i zostanie ponowiona. Zobacz Synchronizacja, asynchroniczność 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 tworzenia aplikacji, ponieważ zmniejsza to ryzyko błędów w kodzie, które mogą generować koszty w środowisku produkcyjnym (np. nieskończona pętla).

Aby emulować funkcje:

1. Uruchom firebase emulators:start i sprawdź w danych wyjściowych adres URL interfejsu 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ź w danych wyjściowych polecenia firebase emulators:start adres URL funkcji HTTP addMessage(). Będzie on wyglądać mniej więcej tak: http://localhost:5001/MY_PROJECT/us-central1/addMessage, z tym że:

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

3. Dodaj ciąg zapytania ?text=uppercaseme na końcu adresu URL funkcji. Powinno to wyglądać mniej więcej tak: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Opcjonalnie możesz zmienić wiadomość "uppercaseme" na własną wiadomość.

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

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

   1. Na karcie Dzienniki powinny pojawić się nowe dzienniki wskazujące, że uruchomiono funkcje addMessage() i makeUppercase():

      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 pierwotnie była to „uppercaseme”, zobaczysz „UPPERCASEME”).

Wdrażanie funkcji 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ć funkcje w środowisku wykonawczym Node.js 14, projekt musi być objęty abonamentem Blaze. Zobacz Cloud Functions ceny.

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

1. Aby wdrożyć funkcje, uruchom to polecenie:

    firebase deploy --only functions
    

   Po uruchomieniu tego polecenia wiersz poleceń Firebase wyświetli adres URL punktów końcowych funkcji HTTP. W terminalu powinien pojawić się wiersz podobny do tego:

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

   Adres URL zawiera identyfikator projektu oraz region funkcji HTTP. Chociaż nie musisz się tym teraz przejmować, niektóre funkcje HTTP w środowisku produkcyjnym powinny określać lokalizację, aby zminimalizować opóźnienie sieci.

   Jeśli napotkasz błędy dostępu, takie jak "Nie można autoryzować dostępu do projektu", sprawdź aliasowanie projektu.

2. Używając adresu URL addMessage() wyświetlonego 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 Firebase konsoli w lokalizacji bazy danych w której jest przechowywany ciąg tekstowy. To zdarzenie zapisu wywołuje funkcję makeUppercase(), która zapisuje wersję ciągu zapisaną wielkimi literami.

Po wdrożeniu i wykonaniu funkcji możesz wyświetlić dzienniki w konsoli Google Cloud. Jeśli musisz usunąć funkcje w środowisku deweloperskim lub produkcyjnym, użyj 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 Kontrolowanie skalowania.

Przeglądanie pełnego przykładowego kodu

Oto ukończony plik functions/index.js zawierający funkcje addMessage() i makeUppercase(). Te funkcje umożliwiają przekazywanie parametru do punktu końcowego HTTP, który zapisuje wartość w Cloud Firestore, a następnie przekształca ją, zmieniają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 admin = require("firebase-admin");
admin.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 admin
    .firestore()
    .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

W tej dokumentacji znajdziesz więcej informacji o tym, jak zarządzać funkcjami w Cloud Functions, a także o tym, jak obsługiwać wszystkie typy zdarzeń obsługiwanych 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 Cloud Functions codelab.
• Przejrzyj i uruchom przykłady kodu na GitHubie.