Zacznij: pisz, testuj i wdrażaj swoje pierwsze funkcje


Aby rozpocząć korzystanie z Cloud Functions, wypróbuj ten samouczek, który zaczyna się od wymaganych zadań konfiguracyjnych i obejmuje tworzenie, testowanie i wdrażanie dwóch powiązanych funkcji:

  • Funkcja „dodaj wiadomość”, która udostępnia adres URL akceptujący wartość tekstową i zapisuje ją w Cloud Firestore.
  • Funkcja „utwórz wielkie litery”, która uruchamia zapis w Cloud Firestore i przekształca tekst na wielkie litery.

W tym przykładzie wybraliśmy Cloud Firestore i funkcje JavaScript wyzwalane przez HTTP, ponieważ te wyzwalacze działające w tle można dokładnie przetestować za pomocą pakietu Firebase Local Emulator Suite . Ten zestaw narzędzi obsługuje również wyzwalacze wywoływalne w czasie rzeczywistym, PubSub, Auth i HTTP. Inne typy wyzwalaczy działających w tle, takie jak wyzwalacze Remote Config, TestLab i Analytics, można testować interaktywnie przy użyciu zestawów narzędzi nieopisanych na tej stronie.

W poniższych sekcjach tego samouczka szczegółowo opisano kroki wymagane do skompilowania, przetestowania i wdrożenia przykładu. Jeśli wolisz po prostu uruchomić kod i sprawdzić go, przejdź do sekcji Przejrzyj cały przykładowy kod .

Utwórz projekt Firebase

  1. W konsoli Firebase kliknij Dodaj projekt .

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

    • Aby utworzyć nowy projekt, wprowadź żądaną nazwę projektu. Możesz także opcjonalnie edytować identyfikator projektu wyświetlany pod nazwą projektu.

  2. Jeśli pojawi się monit, przejrzyj i zaakceptuj warunki Firebase .

  3. Kliknij Kontynuuj .

  4. (Opcjonalnie) Skonfiguruj Google Analytics dla swojego projektu, co pozwoli Ci optymalnie korzystać z dowolnego z następujących produktów Firebase:

    Wybierz istniejące konto Google Analytics lub utwórz nowe konto.

    Jeśli tworzysz nowe konto, wybierz lokalizację raportowania Analytics , a następnie zaakceptuj ustawienia udostępniania danych i warunki Google Analytics dla swojego projektu.

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

Firebase automatycznie udostępnia zasoby dla Twojego projektu Firebase. Po zakończeniu procesu zostaniesz przeniesiony na stronę przeglądu swojego projektu Firebase w konsoli Firebase.

Skonfiguruj Node.js i Firebase CLI

Będziesz potrzebować środowiska Node.js do pisania funkcji, a interfejsu wiersza polecenia Firebase będziesz potrzebować do wdrażania funkcji w środowisku wykonawczym Cloud Functions. Do instalacji Node.js i npm zalecany jest Menedżer wersji węzła .

Po zainstalowaniu Node.js i npm zainstaluj Firebase CLI preferowaną metodą. Aby zainstalować CLI przez npm, użyj:

npm install -g firebase-tools

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

Zainicjuj swój projekt

Podczas inicjowania Firebase SDK for Cloud Functions tworzysz pusty projekt zawierający zależności i minimalną ilość przykładowego kodu, a następnie wybierasz TypeScript lub JavaScript do tworzenia funkcji. Na potrzeby tego samouczka musisz także zainicjować Cloud Firestore.

Aby zainicjować projekt:

  1. Uruchom firebase login , aby zalogować się przez przeglądarkę i uwierzytelnić Firebase CLI.
  2. Przejdź do katalogu projektu Firebase.
  3. Uruchom firebase init firestore . W tym samouczku możesz zaakceptować wartości domyślne po wyświetleniu monitu o podanie reguł Firestore i plików indeksu. Jeśli jeszcze nie korzystałeś z Cloud Firestore w tym projekcie, musisz także wybrać tryb początkowy i lokalizację dla Firestore, jak opisano w Rozpoczęcie pracy z Cloud Firestore .
  4. Uruchom firebase init functions . CLI wyświetla monit o wybranie istniejącej bazy kodu lub zainicjowanie i nazwanie nowej. Gdy dopiero zaczynasz, wystarczy pojedyncza baza kodu w domyślnej lokalizacji; później, gdy twoja implementacja się rozrośnie, możesz zechcieć zorganizować funkcje w bazach kodu .

  5. CLI oferuje dwie opcje obsługi języków:

    W tym samouczku wybierz JavaScript .

  6. Interfejs CLI daje możliwość zainstalowania zależności za pomocą npm. Bezpiecznie jest odrzucić, jeśli chcesz zarządzać zależnościami w inny sposób, ale jeśli odmówisz, będziesz musiał uruchomić npm install przed emulacją lub wdrożeniem swoich funkcji.

Po pomyślnym wykonaniu tych poleceń struktura projektu wygląda następująco:

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 inicjalizacji zawiera ważny klucz: "engines": {"node": "16"} . Określa to wersję Node.js do pisania i wdrażania funkcji. Możesz wybrać inne obsługiwane wersje .

Zaimportuj wymagane moduły i zainicjuj aplikację

Po zakończeniu zadań instalacyjnych możesz otworzyć katalog źródłowy i rozpocząć dodawanie kodu zgodnie z opisem w poniższych sekcjach. W przypadku tego przykładu projekt musi zaimportować moduły Cloud Functions i Admin SDK przy użyciu instrukcji Node require . Dodaj wiersze podobne do poniższego do 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 oraz inicjują instancję aplikacji admin , z poziomu której można wprowadzać zmiany w Cloud Firestore. Wszędzie tam, gdzie dostępna jest obsługa pakietu Admin SDK , na przykład w przypadku FCM, uwierzytelniania i bazy danych czasu rzeczywistego Firebase, zapewnia ona skuteczny sposób integracji Firebase przy użyciu Cloud Functions.

Firebase CLI automatycznie instaluje moduły Firebase i Firebase SDK for Cloud Functions Node podczas inicjowania projektu. Aby dodać biblioteki innych firm do swojego projektu, możesz zmodyfikować package.json i uruchomić npm install . Aby uzyskać więcej informacji, zobacz Obsługa zależności .

Dodaj funkcję addMessage()

W przypadku funkcji addMessage() dodaj następujące 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() jest punktem końcowym HTTP. Każde żądanie skierowane do punktu końcowego skutkuje przekazaniem 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 odłożyć pracę z 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 .

Dodaj funkcję makeUppercase()

W przypadku funkcji makeUppercase() dodaj następujące wiersze do 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 zapisuje się do Cloud Firestore. Funkcja ref.set definiuje dokument do nasłuchiwania. Ze względu na wydajność powinieneś być jak najbardziej szczegółowy.

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

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

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

Emuluj wykonywanie swoich funkcji

Pakiet Firebase Local Emulator Suite umożliwia tworzenie i testowanie aplikacji na komputerze lokalnym zamiast wdrażania ich w projekcie Firebase. Lokalne testowanie podczas opracowywania jest zdecydowanie zalecane, po części dlatego, że zmniejsza ryzyko błędów kodowania, które mogą potencjalnie generować koszty w środowisku produkcyjnym (na przykład nieskończona pętla).

Aby emulować swoje funkcje:

  1. Uruchom firebase emulators:start i sprawdź dane wyjściowe dla adresu URL interfejsu użytkownika pakietu emulatorów. Domyślnie jest to localhost:4000 , ale może być hostowane na innym porcie na twoim komputerze. Wprowadź ten adres URL w przeglądarce, aby otworzyć interfejs użytkownika Emulator Suite.

  2. Sprawdź dane wyjściowe polecenia firebase emulators:start dla adresu URL funkcji HTTP addMessage() . Będzie wyglądać podobnie do http://localhost:5001/MY_PROJECT/us-central1/addMessage , z tą różnicą, że:

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

  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ść „wielkimi literami” na wiadomość niestandardową.

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

  5. Zobacz efekty funkcji w interfejsie użytkownika Emulator Suite:

    1. W zakładce Logs powinieneś zobaczyć nowe logi wskazujące na uruchomienie funkcji addMessage() i makeUppercase() :

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. Na karcie Firestore powinieneś zobaczyć dokument zawierający oryginalną wiadomość, a także wersję wiadomości pisaną wielkimi literami (jeśli oryginalnie była to „wielkie litery”, zobaczysz „WIELKIE LITERY”).

Wdróż funkcje w środowisku produkcyjnym

Gdy funkcje działają w emulatorze zgodnie z oczekiwaniami, możesz przystąpić do wdrażania, testowania i uruchamiania ich w środowisku produkcyjnym. Pamiętaj, że aby wdrożyć w zalecanym środowisku wykonawczym Node.js 14, Twój projekt musi być objęty planem cenowym Blaze . Zobacz cennik Cloud Functions .

Aby ukończyć samouczek, wdróż swoje funkcje, a następnie wykonaj addMessage() w celu wywołania makeUppercase() .

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

     firebase deploy --only functions

    Po uruchomieniu tego polecenia Firebase CLI wyświetla adres URL dla wszystkich punktów końcowych funkcji HTTP. W terminalu powinieneś zobaczyć linię podobną do następującej:

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

    Adres URL zawiera identyfikator Twojego projektu oraz region dla funkcji HTTP. Chociaż teraz nie musisz się tym martwić, niektóre produkcyjne funkcje HTTP 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”, spróbuj sprawdzić aliasowanie projektu .

  2. Korzystając z adresu URL addMessage() generowanego przez CLI, dodaj parametr zapytania tekstowego i otwórz go w przeglądarce:

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

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

Po wdrożeniu i wykonaniu funkcji możesz przeglądać logi w Google Cloud Console . Jeśli chcesz usunąć funkcje w fazie rozwoju lub produkcji, użyj interfejsu wiersza polecenia Firebase.

W środowisku produkcyjnym możesz chcieć zoptymalizować wydajność funkcji i kontrolować koszty, ustawiając minimalną i maksymalną liczbę instancji do uruchomienia. Zobacz zachowanie skalowania sterowania, aby uzyskać więcej informacji na temat tych opcji środowiska uruchomieniowego.

Przejrzyj pełny przykładowy kod

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ść do 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 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

Następne kroki

Z tej dokumentacji dowiesz się więcej o zarządzaniu funkcjami Cloud Functions oraz obsłudze wszystkich typów zdarzeń obsługiwanych przez Cloud Functions.

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