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

Aby rozpocząć korzystanie z Cloud Functions, wykonaj kroki opisane w tym samouczku, Zaczyna się on od wymaganych zadań konfiguracyjnych, a następnie opisuje tworzenie, testowanie, i wdrażanie 2 powiązanych funkcji:

• Funkcja „dodaj wiadomość”, która udostępnia adres URL akceptujący wartość tekstową i zapisujący ją w Cloud Firestore.
• Funkcja „zmień na wielkie litery”, która jest wywoływana podczas zapisu w Cloud Firestore i przekształca tekst na wielkie litery.

Oto pełny przykładowy kod zawierający te funkcje:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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 saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Informacje o tym samouczku

W tym przykładzie wybraliśmy Cloud Firestore i funkcje wywoływane przez HTTP częściowo dlatego, że te aktywatory działające w tle można dokładnie przetestować za pomocą Firebase Local Emulator Suite. Ten zestaw narzędzi obsługuje też Realtime Database, Cloud Storage, PubSub, Auth i aktywatory wywoływane przez HTTP. Inne typy aktywatorów działających w tle takich jak Remote Config i aktywatory TestLab można testować interaktywnie za pomocą zestawów narzędzi, które nie są opisane na tej stronie.

W kolejnych sekcjach tego samouczka opisujemy kroki wymagane do utworzenia, przetestowania i wdrożenia przykładu.

Tworzenie projektu Firebase

Konfigurowanie środowiska i wiersza poleceń Firebase

Inicjowanie projektu

Gdy zainicjujesz Firebase SDK dla Cloud Functions, utworzysz pusty projekt zawierający zależności i minimalny przykładowy kod. Jeśli używasz Node.js, do tworzenia funkcji możesz wybrać TypeScript lub JavaScript. Na potrzeby tego samouczka musisz też zainicjować Cloud Firestore.

Aby zainicjować projekt:

1. Uruchom firebase login, aby zalogować się w przeglądarce i uwierzytelnić Firebase interfejs wiersza poleceń.
2. Otwórz katalog projektu w Firebase.
3. Uruchom polecenie firebase init firestore. Na potrzeby tego samouczka możesz zaakceptować wartości domyślne, gdy pojawi się prośba o podanie reguł Firestore i plików indeksu. Jeśli nie używasz jeszcze 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 polecenie firebase init functions. Interfejs wiersza poleceń wyświetli prośbę o wybranie dotychczasowej bazy kodu lub zainicjowanie i nazwanie nowej. Na początek wystarczy jedna baza kodu w domyślnej lokalizacji. Później, gdy implementacja się rozrośnie, możesz chcieć zorganizować funkcje w bazach kodu.

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

   • JavaScript
   • TypeScript
   • Python

   Na potrzeby tego samouczka wybierz JavaScript lub Python. Informacje o tworzeniu w TypeScript znajdziesz w artykule Tworzenie funkcji w TypeScript.

6. Interfejs wiersza poleceń umożliwia zainstalowanie zależności. Możesz odmówić, jeśli chcesz zarządzać zależnościami w inny sposób.

Po pomyślnym 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

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
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

Importowanie wymaganych modułów i inicjowanie aplikacji

Po wykonaniu zadań konfiguracyjnych możesz otworzyć katalog źródłowy i zacząć dodawać kod zgodnie z opisem w kolejnych sekcjach. W tym przykładzie projekt musi importować moduły Cloud Functions i pakietu Admin SDK. Dodaj do pliku źródłowego wiersze podobne do tych:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

Te wiersze wczytują wymagane moduły i inicjują instancję aplikacji admin, z której można wprowadzać Cloud Firestore zmiany. Wszędzie tam, gdzie dostępna jest obsługa pakietu Admin SDK, np. w przypadku FCM, Authentication, i Firebase Realtime Database, zapewnia on skuteczny sposób integracji Firebase za pomocą Cloud Functions.

Wiersz poleceń Firebase automatycznie instaluje moduły pakietu Firebase Admin SDK i pakietu Firebase SDK dla Cloud Functions podczas inicjowania projektu. Więcej informacji o dodawaniu bibliotek innych firm do projektu znajdziesz w artykule Zarządzanie zależnościami.

Dodawanie funkcji „dodaj wiadomość”

Aby dodać funkcję „dodaj wiadomość”, dodaj do pliku źródłowego te wiersze:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

Funkcja „dodaj wiadomość” to punkt końcowy HTTP. Każde żądanie do punktu końcowego powoduje przekazanie obiektów żądania i odpowiedzi do modułu obsługi żądań na Twojej platformie (onRequest() lub on_request).

Funkcje HTTP są synchroniczne (podobnie jak funkcje wywoływane), dlatego należy jak najszybciej wysłać odpowiedź i odłożyć pracę za pomocą Cloud Firestore. Funkcja HTTP „dodaj wiadomość” przekazuje wartość tekstową do punktu końcowego HTTP i wstawia ją do bazy danych pod ścieżką /messages/:documentId/original.

Dodawanie funkcji „zmień na wielkie litery”

Aby dodać funkcję „zmień na wielkie litery”, dodaj do pliku źródłowego te wiersze:

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Funkcja „zmień na wielkie litery” jest wykonywana, gdy następuje zapis w Cloud Firestore, co definiuje dokument, którego należy nasłuchiwać. Ze względu na wydajność należy podać jak najwięcej szczegółów.

Nawiasy klamrowe, np. {documentId}, otaczają „parametry”, czyli symbole wieloznaczne, które udostępniają dopasowane dane w wywołaniu zwrotnym. Cloud Firestore wywołuje wywołanie zwrotne za każdym razem, gdy dodawane są nowe wiadomości.

W Node.js funkcje oparte na zdarzeniach, takie jak zdarzenia Cloud Firestore, są asynchroniczne. Funkcja wywołania zwrotnego powinna zwracać wartość null, obiekt, lub obietnicę. Jeśli nie zwrócisz niczego, funkcja przekroczy limit czasu, co oznacza błąd, i zostanie ponowiona. Więcej informacji znajdziesz w artykule Synchronizacja, asynchroniczność i obietnice.

Emulowanie wykonywania funkcji

Firebase Local Emulator Suite umożliwia tworzenie i testowanie aplikacji na komputerze lokalnym zamiast wdrażania ich w projekcie w Firebase. Zdecydowanie zalecamy testowanie lokalne podczas tworzenia aplikacji, częściowo dlatego, że zmniejsza to ryzyko błędów w kodzie, które mogą generować koszty w środowisku produkcyjnym (np. nieskończona pętla).

Aby emulować funkcje:

1. Uruchom firebase emulators:start i sprawdź w danych wyjściowych adres URL interfejsu Emulator Suite UI. Domyślnie jest to localhost:4000, ale może być hostowany na innym porcie na Twoim komputerze. Wpisz ten adres URL w przeglądarce, aby otworzyć Emulator Suite UI.

2. Sprawdź w danych wyjściowych polecenia firebase emulators:start adres URL funkcji HTTP. Będzie on podobny do http://localhost:5001/MY_PROJECT/us-central1/addMessage, z tym że:

   1. MY_PROJECT zostanie zastąpiony identyfikatorem projektu.
   2. Port może się różnić na Twoim komputerze lokalnym.

3. Dodaj ciąg zapytania ?text=uppercaseme na końcu adresu URL funkcji. Powinno to wyglądać tak: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Opcjonalnie możesz zmienić wiadomość "uppercaseme" na wiadomość niestandardową.

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 HTTP zostały uruchomione:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. Na karcie Firestore powinien być widoczny dokument zawierający oryginalną wiadomość oraz jej wersję zapisaną wielkimi literami (jeśli pierwotnie była to „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ć funkcje w środowisku produkcyjnym, projekt musi być objęty abonamentem Blaze. Więcej informacji znajdziesz w artykule Cloud Functions Ceny.

Aby ukończyć samouczek, wdróż funkcje, a następnie je uruchom.

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

    firebase deploy --only functions
    

   Po uruchomieniu tego polecenia wiersz poleceń Firebase wyświetli adres URL punktów końcowych funkcji HTTP. W terminalu powinien być widoczny wiersz podobny do tego:

   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 funkcje HTTP w środowisku produkcyjnym 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", sprawdź aliasowanie projektu.

2. Używając adresu URL wyświetlonego przez interfejs wiersza poleceń, dodaj parametr zapytania tekstowego i otwórz go w przeglądarce:

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

   Funkcja zostanie wykonana i przekieruje przeglądarkę do Firebase konsoli w lokalizacji bazy danych w której jest przechowywany ciąg tekstowy. To zdarzenie zapisu wywoła funkcję „zmień na wielkie litery”, która zapisze ciąg znaków w wersji zapisanej wielkimi literami.

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

W środowisku produkcyjnym możesz zoptymalizować wydajność funkcji i kontrolować koszty, ustawiając minimalną i maksymalną liczbę instancji do uruchomienia. Więcej informacji o tych opcjach środowiska wykonawczego znajdziesz w artykule Kontrolowanie skalowania.

Dalsze kroki

W tej dokumentacji znajdziesz więcej informacji o tym, jak zarządzać funkcjami w Cloud Functions, a także o tym, jak obsługiwać wszystkie typy zdarzeń obsługiwanych przez Cloud Functions.

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

• przeczytać o przypadkach użycia Cloud Functions,
• wypróbować ćwiczenie z programowania Cloud Functions.
• przejrzeć i uruchomić przykłady kodu na GitHubie.