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

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

  • addMessage() , która udostępnia adres URL, który akceptuje wartość tekstową i zapisuje ją w Cloud Firestore.
  • makeUppercase() , która uruchamia się przy zapisie Cloud Firestore i przekształca tekst na wielkie litery.

Wybraliśmy dla tego przykładu funkcje Cloud Firestore i wyzwalane przez HTTP funkcje JavaScript po części dlatego, że 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ływane Bazy danych czasu rzeczywistego, PubSub, Auth i HTTP. Inne typy wyzwalaczy działających w tle, takie jak Zdalna konfiguracja, TestLab i wyzwalacze Analytics, można testować interaktywnie przy użyciu zestawów narzędzi, które nie zostały opisane 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 kompletny 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 jego nazwę projektu lub wybierz go z menu.

    • Aby utworzyć nowy projekt, wprowadź żądaną nazwę projektu. Możesz również 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 zapewni optymalne działanie przy korzystaniu 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 projektu Firebase w konsoli Firebase.

Skonfiguruj Node.js i Firebase CLI

Do pisania funkcji potrzebne będzie środowisko Node.js , a do wdrażania funkcji w środowisku wykonawczym Cloud Functions potrzebny będzie interfejs wiersza polecenia Firebase. Do instalacji Node.js i npm zaleca się Node Version Manager .

Po zainstalowaniu Node.js i npm zainstaluj Firebase CLI za pomocą preferowanej metody. Aby zainstalować CLI przez npm, użyj:

npm install -g firebase-tools

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

Zainicjuj swój projekt

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

Aby zainicjować swój projekt:

  1. Uruchom firebase login , aby zalogować się przez przeglądarkę i uwierzytelnić narzędzie Firebase.
  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 reguły Firestore i pliki indeksu. Jeśli nie korzystałeś jeszcze z Cloud Firestore w tym projekcie, musisz także wybrać tryb początkowy i lokalizację Firestore zgodnie z opisem w artykule Pierwsze kroki z Cloud Firestore .
  4. Uruchom firebase init functions . Narzędzie daje możliwość zainstalowania zależności z npm. Można bezpiecznie odrzucić, jeśli chcesz zarządzać zależnościami w inny sposób, ale jeśli odmówisz, musisz uruchomić npm install przed emulacją lub wdrożeniem funkcji.

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

    W tym samouczku wybierz JavaScript .

Po pomyślnym zakończeniu tych poleceń struktura projektu 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 inicjalizacji zawiera ważny klucz: "engines": {"node": "10"} . Określa 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ń konfiguracyjnych możesz otworzyć katalog źródłowy i rozpocząć dodawanie kodu zgodnie z opisem w poniższych sekcjach. Na potrzeby tego przykładu Twój projekt musi zaimportować moduły Cloud Functions i Admin SDK przy użyciu instrukcji Node require . Dodaj wiersze podobne do poniższych do index.js :

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

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();
index.js

Te wiersze ładują firebase-functions Firebase 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 , tak jak w przypadku FCM, uwierzytelniania i bazy danych czasu rzeczywistego Firebase, zapewnia ona zaawansowany sposób integracji Firebase za pomocą Cloud Functions.

Firebase CLI 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 . Aby uzyskać więcej informacji, zobacz temat Obsługa zależności .

Dodaj funkcję addMessage()

W przypadku funkcji addMessage() dodaj te wiersze do 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 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ływane ), dlatego 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 pod ścieżką /messages/:documentId/original .

Dodaj funkcję makeUppercase()

W przypadku funkcji makeUppercase() dodaj te 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 podczas zapisu w Cloud Firestore. Funkcja ref.set definiuje dokument do odsłuchania. Ze względu na wydajność powinieneś być jak najbardziej konkretny.

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

Cloud Firestore uruchamia wywołanie zwrotne onWrite() za każdym razem, gdy dane są zapisywane lub aktualizowane w danym dokumencie.

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

Emuluj wykonywanie swoich funkcji

Pakiet Firebase Local Emulator Suite umożliwia tworzenie i testowanie aplikacji na komputerze lokalnym zamiast wdrażania w projekcie Firebase. Zdecydowanie zaleca się lokalne testowanie podczas opracowywania, po części dlatego, że zmniejsza ryzyko błędów kodowania, które mogą potencjalnie wiązać się z kosztami 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ć hostowany na innym porcie na twoim komputerze. Wprowadź ten adres URL w przeglądarce, aby otworzyć interfejs użytkownika pakietu emulatorów.

  2. Sprawdź dane wyjściowe polecenia firebase emulators:start pod kątem 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 identyfikatorem Twojego projektu.
    2. Port może być inny na twoim lokalnym komputerze.

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

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

  5. Zobacz efekty funkcji w interfejsie Emulator Suite:

    1. W zakładce Logs powinieneś zobaczyć nowe logi wskazujące, że funkcje addMessage() i makeUppercase() uruchomione:

      i funkcje: Rozpoczęcie wykonywania "addMessage"

      i funkcje: Rozpoczęcie wykonywania "makeUppercase"

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

Wdrażaj funkcje w środowisku produkcyjnym

Gdy funkcje działają zgodnie z wymaganiami w emulatorze, 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() , aby wyzwolić makeUppercase() .

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

     firebase deploy --only functions

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

    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 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ć alias projektu .

  2. Używając adresu URL addMessage() z interfejsu CLI, dodaj parametr zapytania tekstowego i otwórz go w przeglądarce:

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

    Funkcja uruchamia i przekierowuje przeglądarkę do konsoli Firebase w lokalizacji bazy danych, w której przechowywany jest ciąg tekstowy. To zdarzenie zapisu wyzwala makeUppercase() , która zapisuje wielką wersję ciągu.

Po wdrożeniu i wykonaniu funkcji możesz przeglądać logi w Google Cloud Console . Jeśli musisz 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ę wystąpień do uruchomienia. Zobacz Sterowanie zachowaniem skalowania, aby uzyskać więcej informacji na temat tych opcji środowiska uruchomieniowego.

Przejrzyj kompletny przykładowy kod

Oto ukończone functions/index.js zawierające 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ą przez zapisanie wszystkich znaków w ciągu wielkimi literami.

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

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

W tej dokumentacji można znaleźć więcej informacji na temat ogólnych koncepcji Cloud Functions, a także przewodniki dotyczące pisania funkcji obsługujących typy zdarzeń obsługiwane przez Cloud Functions.

Aby dowiedzieć się więcej o Cloud Functions, możesz również wykonać następujące czynności:

Instrukcja wideo

Możesz dowiedzieć się więcej o Cloud Functions, oglądając samouczki wideo. W tym filmie znajdziesz szczegółowe wskazówki dotyczące rozpoczęcia pracy z Cloud Functions, w tym konfiguracji Node.js i CLI.