Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

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 akceptujący 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 , a następnie wybierz lub wprowadź nazwę projektu .

    Jeśli masz już projekt Google Cloud, możesz wybrać projekt z menu, aby dodać do niego zasoby Firebase.

  2. (Opcjonalnie) Jeśli tworzysz nowy projekt, możesz edytować identyfikator projektu .

    Firebase automatycznie przypisuje do Twojego projektu Firebase unikalny identyfikator. Odwiedź stronę Understand Firebase Projects, aby dowiedzieć się, jak Firebase używa identyfikatora projektu.

  3. Kliknij Kontynuuj .

  4. (Opcjonalnie) Skonfiguruj Google Analytics dla swojego projektu, co zapewni Ci optymalne działanie przy użyciu dowolnej z następujących usług Firebase:

    Po wyświetleniu monitu wybierz, czy chcesz użyć istniejącego konta Google Analytics, czy utworzyć nowe.
    Jeśli zdecydujesz się utworzyć 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 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 korzystasz jeszcze z 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 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. W tym przykładzie 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 setup 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-admin 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 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 {documentId} — na przykład {documentId} otaczają „parametry”, symbole wieloznaczne, które ujawniają 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 emulatorów lokalnych Firebase umożliwia tworzenie i testowanie aplikacji na komputerze lokalnym zamiast wdrażania w projekcie Firebase. Zdecydowanie zaleca się testowanie lokalne podczas opracowywania, po części dlatego, że zmniejsza to 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 pod kątem 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 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ć http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme 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 wykonuje 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 wyświetlać dzienniki w konsoli Firebase dla Cloud Functions . Jeśli musisz usunąć funkcje w fazie rozwoju lub produkcji, użyj interfejsu wiersza polecenia Firebase.

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.

09cfd61e0

Następne kroki

W tej dokumentacji znajdziesz 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:

Wideo poradnik

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