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

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 pliku Cloud Firestore.
• Funkcja „make uppercase”, która jest wywoływana po zapisie za pomocą funkcji Cloud Firestore i przekształca tekst na wielkie litery.

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

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/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

Wybraliśmy do tego celu funkcje Cloud Firestore i aktywowane przez HTTP ponieważ te aktywatory działające w tle można dokładnie przetestować w Firebase Local Emulator Suite. Ten zestaw narzędzi obsługuje też Realtime Database, Cloud Storage, PubSub, Auth i wywoływane przez HTTP uruchamiane przez HTTP. Inne typy wyzwalaczy w tle, np. Remote Config i wyzwalacze TestLab, można testować interaktywnie za pomocą zestawów narzędzi, które nie są opisane na tej stronie.

W sekcjach tego samouczka znajdziesz szczegółowe instrukcje tworzenia testować i wdrażać przykład.

Tworzenie projektu Firebase

1. 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 odpowiednią nazwę. Opcjonalnie możesz też edytować identyfikator projektu wyświetlany pod nazwą projektu.

2. W razie potrzeby przeczytaj i zaakceptuj warunki korzystania z Firebase.

3. Kliknij Dalej.

4. (Opcjonalnie) Skonfiguruj w swoim projekcie usługę Google Analytics, aby optymalnie korzystać z tych usług Firebase:

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Remote Config personalizacja Firebase A/B Testing

   Wybierz istniejący Konto Google Analytics lub utworzyć 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.

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

Firebase automatycznie udostępnia zasoby projektu Firebase. Kiedy Gdy proces się zakończy, pojawi się strona przeglądu Firebase projekt w konsoli Firebase.

Konfigurowanie środowiska i interfejsu wiersza poleceń Firebase

Zainicjuj projekt

Gdy zainicjujesz pakiet SDK Firebase dla aplikacji Cloud Functions, utworzysz pusty projekt który zawiera zależności i minimalny przykładowy kod. Jeśli jesteś używając Node.js, możesz wybrać jedną z tych opcji TypeScript lub JavaScript do tworzenia funkcji. W tym samouczku musisz też zainicjować Cloud Firestore.

Aby zainicjować projekt:

1. Uruchom firebase login, aby zalogować się w przeglądarce i uwierzytelnić Interfejs wiersza poleceń Firebase.
2. Przejdź do katalogu projektów Firebase.
3. Uruchom firebase init firestore. W tym samouczku możesz zaakceptować wartość domyślną gdy pojawi się prośba o podanie reguł Firestore oraz plików 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.
4. Uruchom firebase init functions. W interfejsie wiersza poleceń wyświetli się prośba o wybranie istniejącego bazy kodu lub zainicjowanie i nazwanie nowej. Dopiero zaczynasz, wystarczy jedna baza kodu w lokalizacji domyślnej; później, wraz z rozwojem implementacji, chcesz uporządkować funkcje w bazach kodu.

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

   • JavaScript
   • TypeScript
   • Python

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

6. Interfejs wiersza poleceń pozwala zainstalować zależności. To jest bezpieczne chcesz odrzucić, jeśli chcesz zarządzać zależnościami w inny sposób.

Po wykonaniu tych poleceń struktura projektu będzie wyglądać tak to:

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

Zaimportuj wymagane moduły i inicjuj aplikację

Po zakończeniu zadań konfiguracyjnych możesz otworzyć katalog źródeł i rozpocząć dodawanie kodu zgodnie z instrukcjami podanymi w następnych sekcjach. W tym przykładzie projekt musi zaimportować moduły Cloud Functions i Admin SDK. Dodaj wiersze np. do pliku źródłowego:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/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 wprowadzić zmiany 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ą pakietu Cloud Functions.

interfejs wiersza poleceń Firebase automatycznie. instaluje podczas inicjowania pakiet SDK Firebase Admin SDK i pakiet SDK Firebase dla modułów Cloud Functions w Twoim projekcie. Więcej informacji o dodawaniu bibliotek innych firm do swojego projektu, zobacz Obsługuj zależności.

Dodaj funkcję „add message”

W polu „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

Opcja „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 żądania na Twojej platformie (onRequest() lub on_request).

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. Opcja „Dodaj wiadomość” Funkcja HTTP przekazuje wartość tekstową do punktu końcowego HTTP i wstawia ją do parametru w bazie danych w ścieżce /messages/:documentId/original.

Dodaj funkcję „zapisywanie wielkimi literami”.

W przypadku funkcji „make uppercase” 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

Używaj metody „pisz wielkimi literami”, funkcja jest wykonywana, gdy w funkcji Cloud Firestore jest zapisana funkcja, określając dokument, którego chcesz nasłuchiwać. Aby zwiększyć wydajność, powinny być jak najbardziej szczegółowe.

W nawiasach klamrowych (np. {documentId}) otaczasz „parametry”, czyli symbole wieloznaczne, które w zwrotnym wywołaniu udostępniają dopasowane dane. Cloud Firestore wyzwala wywołanie zwrotne po dodaniu nowych wiadomości.

W Node.js funkcje oparte na zdarzeniach, takie jak zdarzenia Cloud Firestore, są asynchronicznie. Funkcja wywołania zwrotnego powinna zwracać wartość null, obiekt lub obietnica. Jeśli niczego nie zwrócisz, funkcja przekroczy limit czasu, sygnalizując błąd i zostanie ponowiona. Zobacz Synchronizacja, asynchroniczne i obietnice.

Emuluj wykonywanie funkcji

Firebase Local Emulator Suite pozwala tworzyć i testować aplikacje na komputerze lokalnym, zamiast dla projektu Firebase. Zdecydowanie zalecamy testowanie lokalne w trakcie programowania, Częściowo zmniejsza to ryzyko błędów w kodzie, które mogłyby potencjalnie mogą powodować koszty w środowisku produkcyjnym (np. nieskończona pętla).

Aby emulować funkcje:

1. 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

2. Sprawdź dane wyjściowe polecenia firebase emulators:start dotyczące adresu URL funkcji HTTP. Będzie on wyglądał podobnie 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ć w zależności od komputera lokalnego.

3. 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ą.

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 pojawić się nowe logi wskazujące, że funkcje HTTP zostały wykonane pomyślnie:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. 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 w emulatorze będą działać zgodnie z oczekiwaniami, możesz przejść do wdrażaniem, testowaniem i uruchamianiem ich w środowisku produkcyjnym; Pamiętaj, że aby wdrożyć aplikację w produkcji, musisz mieć projekt objęty abonamentem Blaze. Zobacz Cennik Cloud Functions.

Aby ukończyć samouczek, wdróż funkcje, a potem je wykonaj.

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

    firebase deploy --only functions
    

   Po uruchomieniu tego polecenia interfejs wiersza poleceń Firebase wyświetla adres URL wszystkich punktów końcowych 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 napotkasz błędy dostępu, takie jak „Nie udało się autoryzować dostępu do w projekcie”, sprawdź aliasy projektu.

2. Korzystając z danych wyjściowych adresu URL interfejsu wiersza poleceń, dodaj tekstowy parametr zapytania, i otwórz go w przeglądarce:

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

   Funkcja uruchamia się i przekierowuje przeglądarkę do Konsola Firebase w lokalizacji bazy danych gdzie zapisany jest ciąg tekstowy. To zdarzenie zapisu powoduje wywołanie funkcji „make uppercase”, która zapisuje wersję ciągu znaków w wielkich literach.

Po wdrożeniu i wykonywaniu funkcji możesz wyświetlać dzienniki w konsoli Google Cloud. Jeśli musisz usunąć funkcje w środowisku programistycznym lub produkcyjnym, 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.

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 stronie Cloud Functions, może też:

• Dowiedz się więcej o przypadkach użycia usługi Cloud Functions.
• Wypróbuj ćwiczenia z programowania Cloud Functions.
• Sprawdź i uruchom przykładowy kod na GitHubie