Pierwsze kroki: pisanie, testowanie i wdrażanie pierwszych funkcji

.


Aby zacząć korzystać z Cloud Functions, skorzystaj z tego samouczka, która rozpoczyna się od wymaganych zadań konfiguracyjnych, a kończy tworzenie, testowanie i wdrożę 2 powiązane funkcje:

  • „Dodaj wiadomość”. funkcja ujawniająca i zapisująca adres URL przyjmujący wartość tekstową do Cloud Firestore.
  • Użyj wielkich liter funkcja wyzwalająca się przy zapisie i przekształceniu Cloud Firestore zapisać tekst wielkimi literami.

Wybraliśmy do tego celu funkcje Cloud Firestore i aktywowane przez HTTP ponieważ te aktywatory działające w tle można dokładnie przetestować w Firebase Local Emulator Suite. Ten zestaw narzędzi obsługuje też Realtime Database, Aktywatory PubSub, Auth i HTTP dostępne do wywołania. Inne typy reguł działających w tle takich jak Remote Config, Laboratorium i Analytics, można testowanych interaktywnie za pomocą zbiorów narzędzi, opisane na tej stronie.

W sekcjach tego samouczka znajdziesz szczegółowe instrukcje tworzenia testować i wdrażać przykład. Jeśli wolisz po prostu uruchomić kod i go sprawdzić, przejdź do artykułu Zobacz pełny przykładowy kod.

Tworzenie projektu Firebase

  1. W konsoli Firebase kliknij Dodaj projekt.

    • Aby dodać zasoby Firebase do istniejącego projektu Google Cloud, wpisz jego nazwę lub wybierz ją z menu.

    • Aby utworzyć nowy projekt, wpisz odpowiednią nazwę. Opcjonalnie możesz też zmień identyfikator projektu wyświetlany pod jego nazwą.

  2. W razie potrzeby przeczytaj i zaakceptuj warunki korzystania z Firebase.

  3. Kliknij Dalej.

  4. (Opcjonalnie) Skonfiguruj w swoim projekcie usługę Google Analytics, która pozwoli Ci aby zoptymalizować jedną z następujących usług Firebase:

    Wybierz istniejący Konto Google Analytics lub utworzyć nowe konto.

    Jeśli tworzysz nowe konto, wybierz Analytics lokalizacja raportowania, a następnie zaakceptuj ustawienia udostępniania danych i warunki korzystania z usługi Google Analytics dotyczące Twojego projektu.

  5. Kliknij Utwórz projekt (lub Dodaj Firebase, jeśli używasz istniejący projekt Google Cloud).

Firebase automatycznie udostępnia zasoby projektu Firebase. Kiedy Gdy proces się zakończy, pojawi się strona przeglądu Firebase projekt w konsoli Firebase.

Skonfiguruj Node.js i interfejs wiersza poleceń Firebase

Do pisania funkcji potrzebujesz środowiska Node.js, i do wdrażania funkcji w interfejsie wiersza poleceń Firebase potrzebny Ci będzie w środowisku wykonawczym Cloud Functions. Aby zainstalować Node.js i npm: Menedżer wersji węzłów .

Po zainstalowaniu Node.js i npm zainstalować interfejs wiersza poleceń Firebase za pomocą wybranej przez Ciebie metody. Aby zainstalować interfejs wiersza poleceń przy użyciu npm, użyj:

npm install -g firebase-tools

Spowoduje to zainstalowanie dostępnego globalnie polecenia Firebase. Jeśli nie powiedzie się, może być konieczne zmień uprawnienia npm. Aby zaktualizować aplikację firebase-tools do najnowszej wersji, uruchom to samo polecenie ponownie.

Zainicjuj projekt

Gdy zainicjujesz pakiet SDK Firebase dla aplikacji Cloud Functions, utworzysz pusty projekt zawierający zależności i minimalną ilość przykładowego kodu, a następnie wybierzesz jedną z opcji TypeScript lub JavaScript do tworzenia funkcji. Na potrzeby niniejszego dokumentu samouczka, musisz też zainicjować Cloud Firestore.

Aby zainicjować projekt:

  1. Uruchom firebase login, aby zalogować się w przeglądarce i uwierzytelnić Interfejs wiersza poleceń Firebase.
  2. Przejdź do katalogu projektów Firebase.
  3. Uruchom firebase init firestore. W tym samouczku możesz zaakceptować wartość domyślną gdy pojawi się prośba o podanie reguł Firestore oraz plików indeksu. Jeśli nie używałeś(-aś) usługi Cloud Firestore w tym projekcie, musisz też musisz wybrać tryb początkowy i lokalizację dla Firestore, jak opisano w Pierwsze kroki w Cloud Firestore.
  4. Uruchom firebase init functions. W interfejsie wiersza poleceń wyświetli się prośba o wybranie istniejącego bazy kodu lub zainicjowanie i nazwanie nowej. Dopiero zaczynasz, wystarczy jedna baza kodu w lokalizacji domyślnej; później, wraz z rozwojem implementacji, chcesz uporządkować funkcje w bazach kodu.

  5. Interfejs wiersza poleceń oferuje 2 opcje obsługi języków:

    Na potrzeby tego samouczka wybierz JavaScript.

  6. Interfejs wiersza poleceń umożliwia instalowanie zależności przy użyciu npm. Jest bezpieczna odrzucić, jeśli chcesz zarządzać zależnościami w inny sposób, Jeśli jednak odrzucisz warunki, konieczne będzie uruchomienie programu npm install przed emulacją lub wdrażanie funkcji.

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

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 element klucz: "engines": {"node": "16"}. Określa Twoją wersję Node.js dla pisania i wdrażania funkcji. Dostępne opcje wybierz inne obsługiwane wersje.

Zaimportuj wymagane moduły i zainicjuj aplikację

Po ukończeniu zadań konfiguracyjnych możesz otwórz katalog źródłowy i zacznij dodawać kod zgodnie z opisem w poniższych sekcji. W tym przykładzie projekt musi zaimportować Moduły Cloud Functions i pakiet Admin SDK używający węzła require wyciągów. Dodaj wiersze np. w pliku index.js:

// 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 ładują moduły firebase-functions i firebase-admin, a także zainicjować instancję aplikacji admin, w której można wprowadzić zmiany w usłudze Cloud Firestore. Wszędzie tam, gdzie dostępna jest obsługa pakietu Admin SDK, dla FCM, Authentication i Firebase Realtime Database zapewnia skuteczny sposób integracji Firebase z użyciem Cloud Functions.

interfejs wiersza poleceń Firebase automatycznie. instaluje przy inicjowaniu moduł Firebase i pakiet SDK Firebase dla Cloud Functions węzłów węzłów w Twoim projekcie. Aby dodać biblioteki zewnętrzne w projekcie, możesz zmodyfikować package.json i uruchomić npm install. Więcej informacji: Obsługuj zależności.

Dodaj funkcję addMessage()

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

// 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() jest punktem końcowym HTTP. Dowolne żądanie skierowane do punktu końcowego w wynikach w stylu ExpressJS Żądanie i odpowiedź obiekty przekazane do Wywołanie zwrotne onRequest().

Funkcje HTTP są synchroniczne (podobnie do funkcji wywoływanych), więc musisz wysłać odpowiedź jak najszybciej i odrocz pracę, korzystając z Cloud Firestore. addMessage() Funkcja HTTP przekazuje wartość tekstową do punktu końcowego HTTP i wstawia ją do parametru w bazie danych w ścieżce /messages/:documentId/original.

Dodaj funkcję makeUppercase()

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

// 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 po zapisaniu elementu Cloud Firestore. Funkcja ref.set definiuje dokument do nasłuchiwania. Aby zwiększyć wydajność, powinny być jak najbardziej szczegółowe.

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

Cloud Firestore wyzwala onCreate(). wywołanie zwrotne po dodaniu nowych wiadomości.

Funkcje oparte na zdarzeniach, takie jak zdarzenia Cloud Firestore, są asynchronicznie. Funkcja wywołania zwrotnego powinna zwrócić null, Object, lub Promise. Jeśli niczego nie zwrócisz, funkcja przekroczy limit czasu, sygnalizując błąd i zostanie ponowiona. Zobacz Synchronizacja, asynchroniczne i obietnice.

Emuluj wykonywanie funkcji

Firebase Local Emulator Suite pozwala tworzyć i testować aplikacje na komputerze lokalnym, zamiast dla projektu Firebase. Zdecydowanie zalecamy testowanie lokalne podczas programowania, Częściowo zmniejsza to ryzyko błędów w kodzie, które mogłyby potencjalnie mogą powodować koszty w środowisku produkcyjnym (np. nieskończona pętla).

Aby emulować funkcje:

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

  2. Sprawdź dane wyjściowe funkcji firebase emulators:start dla adresu URL funkcji HTTP addMessage(). Będzie ona wyglądać podobnie do: http://localhost:5001/MY_PROJECT/us-central1/addMessage, z tym wyjątkiem:

    1. Pole MY_PROJECT zostanie zastąpione identyfikatorem projektu.
    2. Port może się różnić w zależności od komputera lokalnego.

  3. Dodaj ciąg zapytania ?text=uppercaseme na końcu adresu URL funkcji. To powinno wyglądać mniej więcej tak: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme Opcjonalnie możesz zmienić komunikat „wielkie litery” na niestandardowy .

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

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

    1. Na karcie Logi powinny być widoczne nowe logi wskazujące, że funkcje Harmonogram addMessage() i makeUppercase() uruchomiły się:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. Na karcie Firestore powinien być widoczny dokument zawierający oryginał a także wersję wiadomości pisaną wielkimi literami (jeśli była „WIELKIE LITERY” zobaczysz tylko „WIELKIE LITERY”).

Wdrażanie funkcji w środowisku produkcyjnym

Gdy funkcje w emulatorze będą działać zgodnie z oczekiwaniami, możesz przejść do wdrażaniem, testowaniem i uruchamianiem ich w środowisku produkcyjnym; Pamiętaj aby wdrożyć ją w zalecanym środowisku wykonawczym Node.js 14, musi być objęta abonamentem Blaze. Zobacz Cennik Cloud Functions.

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

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

     firebase deploy --only functions

    Po uruchomieniu tego polecenia interfejs wiersza poleceń Firebase wyświetla adres URL każdej Funkcja HTTP i punktów końcowych. 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 dla żądania HTTP . Chociaż nie musisz się tym teraz przejmować, niektóre produkcyjne wersje HTTP funkcje powinny określać lokalizację oraz zminimalizować opóźnienia sieciowe.

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

  2. Korzystając z danych wyjściowych adresu URL addMessage() przez interfejs wiersza poleceń, dodaj tekstowy parametr zapytania, i otwórz go w przeglądarce:

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

    Funkcja uruchamia się i przekierowuje przeglądarkę do Konsola Firebase w lokalizacji bazy danych gdzie zapisany jest ciąg tekstowy. Ten zdarzenie zapisu aktywuje zdarzenie makeUppercase(), które zapisuje wielkie litery wersji ciągu znaków.

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

W środowisku produkcyjnym warto zoptymalizować wydajność funkcji i kontrolę przez ustawienie minimalnej i maksymalnej liczby uruchomionych instancji. Zobacz Sterowanie skalowaniem .

Zobacz pełny przykładowy kod

Oto gotowe zadanie functions/index.js zawierające funkcje addMessage() i makeUppercase(). Te funkcje umożliwiają przekazywanie do punktu końcowego HTTP który zapisuje wartość pod kątem Cloud Firestore, a następnie przekształca ją według wszystkie znaki w ciągu są pisane wielkimi literami.

// 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

Z tej dokumentacji dowiesz się, jak: zarządzaj funkcjami dla klienta Cloud Functions oraz instrukcje do obsługi wszystkich typów zdarzeń obsługiwanych przez Cloud Functions.

Aby dowiedzieć się więcej o stronie Cloud Functions, może też: