Aby rozpocząć korzystanie z Cloud Functions, zapoznaj się z tym samouczkiem, który zaczyna się od wymaganych zadań konfiguracyjnych, a kończy na tworzeniu, testowaniu i wdrażaniu 2 powiązanych ze sobą funkcji:
- Funkcja „add message”, która udostępnia adres URL, który przyjmuje wartość tekstową i zapisuje ją w funkcji Cloud Firestore.
- Funkcja „make uppercase”, która jest wywoływana przez zapis Cloud Firestore i przekształca tekst na wielkie litery.
W tym przykładzie wybraliśmy funkcje JavaScript Cloud Firestore i funkcję JavaScript uruchamianą przez HTTP, ponieważ te tła można dokładnie przetestować za pomocą Firebase Local Emulator Suite. Ten zestaw narzędzi obsługuje też Realtime Database, PubSub, Auth i wyzwalania wywoływane przez HTTP. Inne typy reguł działania w tle, takie jak Remote Config, TestLab i reguły Analytics, można testować interaktywnie za pomocą zestawów narzędzi, które nie są opisane na tej stronie.
W kolejnych sekcjach tego samouczka znajdziesz szczegółowe instrukcje kompilowania, testowania i wdrażania przykładu. Jeśli wolisz uruchomić kod i go sprawdzić, przejdź do sekcji Przeglądanie pełnego przykładowego kodu.
Tworzenie projektu Firebase
-
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 jego nazwę. Opcjonalnie możesz też edytować identyfikator projektu wyświetlany pod nazwą projektu.
-
-
Jeśli pojawi się taka prośba, zapoznaj się z warunkami usługi Firebase i je zaakceptuj.
-
Kliknij Dalej.
-
(Opcjonalnie) Skonfiguruj w projekcie Google Analytics, aby optymalnie korzystać z tych usług Firebase:
Wybierz istniejące konto Google Analytics lub utwórz nowe konto.
Jeśli tworzysz nowe konto, wybierz Analyticslokalizację raportowania, a następnie zaakceptuj ustawienia udostępniania danych i zasady Google Analytics dotyczące projektu.
-
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 wyświetli się strona podsumowania projektu Firebase w konsoli Firebase.
Konfigurowanie Node.js i wiersza poleceń Firebase
Do tworzenia 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 zalecamy użycie menedżera wersji Node.js.
Po zainstalowaniu Node.js i npm zainstaluj interfejs wiersza poleceń Firebase 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 na całym świecie. Jeśli polecenie się nie powiedzie, konieczna może być zmiana uprawnień npm.
Aby zaktualizować aplikację firebase-tools
do najnowszej wersji, ponownie uruchom to samo polecenie.
Zainicjuj projekt
Podczas inicjowania pakietu SDK Firebase na potrzeby Cloud Functions tworzysz pusty projekt zawierający zależności i minimalny przykładowy kod. Do tworzenia funkcji możesz użyć języka TypeScript lub JavaScript. W tym samouczku musisz też zainicjować Cloud Firestore.
Aby zainicjować projekt:
- Uruchom
firebase login
, aby zalogować się w przeglądarce i uwierzytelnić interfejs wiersza poleceń Firebase. - Otwórz katalog projektu Firebase.
- Uruchom
firebase init firestore
. W tym samouczku możesz zaakceptować wartości domyślne, gdy pojawi się prośba 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 instrukcjami w artykule Początkowanie pracy z Cloud Firestore. - Uruchom
firebase init functions
. Narzędzie wiersza poleceń wyświetli prośbę o wybranie istniejącej bazy kodu lub zainicjowanie i nazwanie nowej. Na początku wystarczy użyć jednej bazy kodu w domyślnej lokalizacji. Później, gdy Twoja implementacja się rozrośnie, możesz uporządkować funkcje w bazach kodu. Interfejs wiersza poleceń oferuje 2 opcje obsługi języka:
- JavaScript
- TypeScript: więcej informacji znajdziesz w artykule Tworzenie funkcji za pomocą TypeScript.
Na potrzeby tego samouczka wybierz JavaScript.
Interfejs wiersza poleceń umożliwia instalowanie zależności za pomocą npm. Jeśli chcesz zarządzać zależnościami w inny sposób, możesz bezpiecznie odrzucić tę prośbę. Jeśli jednak to zrobisz, przed emulacją lub wdrażaniem funkcji musisz uruchomić
npm install
.
Po 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 inicjalizacji zawiera ważny klucz: "engines": {"node": "16"}
. To ustawienie określa wersję Node.js używaną do zapisywania i wdrażania funkcji. Możesz wybrać inne obsługiwane wersje.
Zaimportuj wymagane moduły i inicjuj aplikację
Po wykonaniu zadań konfiguracyjnych możesz otworzyć katalog źródeł i rozpocząć dodawanie kodu zgodnie z instrukcjami podanymi w następnych sekcjach. W tym przykładzie Twój projekt musi zaimportować moduły Cloud Functions i Admin SDK za pomocą instrukcji Node require
. Dodaj do pliku index.js
wiersze podobne do tych:
// 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();
Te wiersze wczytują moduły firebase-functions
i firebase-admin
oraz inicjują wystąpienie aplikacji admin
, z którego można wprowadzać zmiany w elementach Cloud Firestore.
Wszędzie tam, gdzie jest dostępny pakiet Admin SDK (jak w przypadku FCM, Authentication i Firebase Realtime Database), stanowi on potężne narzędzie do integracji Firebase za pomocą Cloud Functions.
Gdy inicjujesz projekt, wiersz poleceń Firebase automatycznie instaluje pakiet SDK Firebase i Firebase dla modułów Cloud Functions Node. Aby dodać biblioteki innych firm do projektu, możesz zmodyfikować package.json
i uruchomić npm install
.
Więcej informacji znajdziesz w artykule Zarządzanie zależnościami.
Dodaj funkcję addMessage()
W przypadku funkcji addMessage()
dodaj te wiersze do funkcji 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.` }); });
Funkcja addMessage()
jest punktem końcowym HTTP. Każde żądanie do punktu końcowego powoduje przekazanie obiektów Request i Response w stylu ExpressJS do funkcji wywołania zwrotnego onRequest()
.
Funkcje HTTP są synchroniczne (podobnie jak funkcje wywoływane), dlatego odpowiedź należy wysłać tak szybko, jak to możliwe, i odłożyć wykonanie kodu za pomocą funkcji 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 funkcji 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 }); });
Funkcja makeUppercase()
jest wykonywana, gdy do zmiennej Cloud Firestore jest zapisywany element. Funkcja ref.set
określa dokument, na który ma reagować. Ze względu na wydajność podawaj jak najwięcej szczegółów.
W nawiasach klamrowych (np. {documentId}
) otaczasz „parametry”, czyli symbole wieloznaczne, które w wywołaniu zwrotnym udostępniają dopasowane dane.
Cloud Firestore wywołuje funkcję onCreate()
, gdy dodane zostaną nowe wiadomości.
Funkcje reagujące na zdarzenia, takie jak zdarzenia Cloud Firestore, są asynchroniczne. Funkcja wywołania zwrotnego powinna zwracać wartość null
, obiekt lub obietnica.
Jeśli nie zwrócisz niczego, funkcja zostanie przerwana, co spowoduje błąd i ponownie podjęta próba. Zobacz Synchronizacja, asynchroniczność i obietnice.
Emulowanie wykonania funkcji
Firebase Local Emulator Suiteumożliwia tworzenie i testowanie aplikacji na komputerze lokalnym zamiast wdrażania ich w projekcie Firebase. Zalecamy testowanie lokalne podczas tworzenia aplikacji, ponieważ zmniejsza to ryzyko błędów w kodzie, które mogą potencjalnie generować koszty w środowisku produkcyjnym (np. nieskończona pętla).
Aby emulować funkcje:
Uruchom
firebase emulators:start
i sprawdź dane wyjściowe pod kątem adresu URL Emulator Suite UI. Domyślnie jest to localhost:4000, ale może być hostowane na innym porcie na komputerze. Wpisz ten adres URL w przeglądarce, aby otworzyć Emulator Suite UI.Sprawdź dane wyjściowe polecenia
firebase emulators:start
dotyczące adresu URL funkcji HTTPaddMessage()
. Będzie on wyglądał podobnie dohttp://localhost:5001/MY_PROJECT/us-central1/addMessage
, z tym że:MY_PROJECT
zostanie zastąpiony identyfikatorem projektu.- Port może być inny na Twoim komputerze.
Dodaj ciąg zapytania
?text=uppercaseme
na końcu adresu URL funkcji. Powinna ona wyglądać mniej więcej tak:http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme
. Opcjonalnie możesz zmienić wiadomość „uppercaseme” na wiadomość niestandardową.Utwórz nową wiadomość, otwierając adres URL w nowej karcie przeglądarki.
Wyświetl efekty działania funkcji w sekcji Emulator Suite UI:
Na karcie Logi powinny pojawić się nowe logi wskazujące, że funkcje
addMessage()
imakeUppercase()
zostały wykonane:i functions: Beginning execution of "addMessage"
i functions: Beginning execution of "makeUppercase"
Na karcie Firestore powinien pojawić się dokument zawierający oryginalną wiadomość oraz jej wersję z wielkimi literami (jeśli oryginalna wiadomość brzmiała „uppercaseme”, zobaczysz „UPPERCASEME”).
Wdrażanie funkcji w środowisku produkcyjnym
Gdy funkcje będą działać zgodnie z oczekiwaniami w emulatorze, możesz je wdrożyć, przetestować i uruchomić w środowisku produkcyjnym. Pamiętaj, że aby wdrożyć aplikację w zalecanym środowisku wykonawczym Node.js 14, musisz mieć projekt w abonamentem Blaze. Sprawdź cennikCloud Functions.
Aby ukończyć samouczek, wdróż funkcje, a potem wykonaj funkcję addMessage()
, aby aktywować funkcję makeUppercase()
.
Aby wdrożyć funkcje, uruchom to polecenie:
firebase deploy --only functions
Po uruchomieniu tego polecenia interfejs wiersza poleceń Firebase wyświetli adres URL dowolnego punktu końcowego 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 dla funkcji HTTP. Nie musisz się teraz tym martwić, ale niektóre produkcyjne funkcje HTTP powinny określać lokalizację, aby zminimalizować opóźnienia w sieci.
Jeśli wystąpią błędy dostępu, takie jak „Nie można autoryzować dostępu do projektu”, sprawdź aliasy projektu.
Korzystając z adresu URL
addMessage()
wygenerowanego przez CLI, dodaj parametr zapytania tekstowego i otwórz go w przeglądarce:https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
Funkcja jest wykonywana i przekierowuje przeglądarkę do konsoli Firebase w lokalizacji bazy danych, w której przechowywany jest ciąg tekstowy. To zdarzenie zapisu powoduje wywołanie funkcji
makeUppercase()
, która zapisuje ciąg znaków w wersji z wielkimi literami.
Po wdrożeniu i wykonywaniu funkcji możesz wyświetlać dzienniki w konsoli Google Cloud. Jeśli chcesz usunąć funkcje w wersji rozwojowej lub produkcyjnej, użyj interfejsu wiersza poleceń Firebase.
W środowisku produkcyjnym możesz optymalizować wydajność funkcji i kontrolować koszty, ustawiając minimalną i maksymalną liczbę instancji. Więcej informacji o tych opcjach w czasie wykonywania znajdziesz w artykule Kontrolowanie zachowania skalowania.
Sprawdzanie pełnego przykładowego kodu
Oto gotowa funkcja functions/index.js
zawierająca funkcje addMessage()
i makeUppercase()
. Te funkcje umożliwiają przekazanie parametru do punktu końcowego HTTP, który zapisuje wartość w parametrie Cloud Firestore, a potem 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 }); });
Dalsze kroki
W tej dokumentacji znajdziesz więcej informacji o zarządzaniu funkcjami w przypadku usługi Cloud Functions, a także o obsługiwaniu wszystkich typów zdarzeń obsługiwanych przez usługę Cloud Functions.
Aby dowiedzieć się więcej o Cloud Functions, możesz też:
- Dowiedz się więcej o przypadkach użycia usługi Cloud Functions.
- Wypróbuj ćwiczenia z programowania Cloud Functions.
- Przeglądanie i uruchamianie przykładów kodu na GitHubie