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

Aby zacząć korzystać z Cloud Functions, skorzystaj z tego samouczka: która rozpoczyna się od wymaganych zadań konfiguracyjnych, a kończy tworzenie, testowanie i wdrożę 2 powiązane funkcje:

• „Dodaj wiadomość”. funkcja ujawniająca i zapisująca adres URL przyjmujący wartość tekstową do Cloud Firestore.
• Użyj wielkich liter funkcja aktywująca się przy zapisie i przekształcaniu Cloud Firestore zapisać tekst wielkimi literami.

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 funkcje aktywowane przez HTTP ponieważ te aktywatory działające w tle można dokładnie przetestować korzystając z Pakietu emulatorów lokalnych Firebase. Ten zestaw narzędzi obsługuje również Bazy danych czasu rzeczywistego, Cloud Storage, Aktywatory PubSub, Auth i HTTP dostępne do wywołania. Inne typy reguł działających w tle takich jak aktywatory Zdalnej konfiguracji i TestLab, testowanych interaktywnie z użyciem zbiorów narzędzi, 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ż zmień identyfikator projektu wyświetlany pod jego nazwą.

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

3. Kliknij Dalej.

4. (Opcjonalnie) Skonfiguruj usługę Google Analytics w swoim projekcie. Pozwoli Ci to aby zoptymalizować jedną z następujących usług Firebase:

   Firebase Crashlytics. Komunikacja w chmurze Firebase

   Wysyłanie wiadomości w aplikacji za pomocą Firebase Zdalna konfiguracja Firebase

   Personalizacja Zdalnej konfiguracji Testy A/B Firebase

   Wybierz istniejący Konto Google Analytics lub utworzyć nowe konto.

   Jeśli tworzysz nowe konto, wybierz Lokalizacja raportowania Analytics, a następnie zaakceptuj ustawienia udostępniania danych i warunki korzystania z Google Analytics dotyczące Twojego 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 w konsoli Firebase.

Konfigurowanie środowiska i interfejsu wiersza poleceń Firebase

Zainicjuj projekt

Gdy zainicjujesz pakiet SDK Firebase dla 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. Na potrzeby niniejszego dokumentu musisz też zainicjować Cloud Firestore.

Aby zainicjować projekt:

1. Uruchom firebase login, aby zalogować się w przeglądarce i uwierzytelnić interfejsu 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 używałeś(-aś) usługi Cloud Firestore działa jeszcze w tym projekcie musisz wybrać tryb początkowy i lokalizację dla Firestore, jak opisano w Pierwsze kroki w 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. Do tworzenia w języku: TypeScript: przeczytaj artykuł na temat zapisywania funkcji za pomocą skryptu 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 zainicjuj aplikację

Po ukończeniu zadań konfiguracyjnych możesz otwórz katalog źródłowy i zacznij dodawać kod zgodnie z opisem w poniższych sekcji. 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

Wczytują one wymagane moduły oraz zainicjować instancję aplikacji admin, z której będzie można wprowadzać zmiany w Cloud Firestore. Wszędzie tam, gdzie dostępna jest obsługa pakietu Admin SDK, dla FCM, uwierzytelniania i Bazy danych czasu rzeczywistego Firebase, zapewnia to skuteczny sposób na integrację Firebase za pomocą Cloud Functions.

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

Użycie przycisku „Dodaj wiadomość”. funkcja

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. Dowolne żądanie skierowane do punktu końcowego w wynikach wyszukiwania obiektów żądań i odpowiedzi przekazywanych do moduł obsługi żądań na Twojej platformie (onRequest()), lub on_request).

Funkcje HTTP są synchroniczne (podobnie do funkcji wywoływanych), więc musisz wysłać odpowiedź jak najszybciej i opóźnij pracę w 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 słowo „małe litery”, funkcja

Aby używać wielkich liter, 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”, jest wykonywana, gdy w Cloud Firestore jest zapisywana określając dokument, którego chcesz nasłuchiwać. Aby zwiększyć wydajność, powinny być jak najbardziej szczegółowe.

Nawiasy klamrowe, np. {documentId}, przestrzenne „parametry” symbole wieloznaczne które ujawniają pasujące dane w wywołaniu zwrotnym. 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 zwrócić null, Object, lub Promise. 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

Pakiet emulatorów lokalnych Firebase pozwala tworzyć i testować aplikacje na komputerze lokalnym, zamiast dla projektu Firebase. Zdecydowanie zalecamy testowanie lokalne podczas 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 adresu URL pakietu emulatorów. Domyślna wartość to localhost:4000, ale może być hostowany w innym miejscu na komputerze. Wpisz ten adres URL w przeglądarce, aby otworzyć Interfejs pakietu emulatorów.

2. Sprawdź dane wyjściowe funkcji firebase emulators:start dla adresu URL funkcji HTTP. Będzie ona wyglądać podobnie do: http://localhost:5001/MY_PROJECT/us-central1/addMessage, z tym wyjątkiem:

   1. Pole MY_PROJECT zostanie zastąpione 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. To powinno wyglądać mniej więcej tak: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme Opcjonalnie możesz zmienić komunikat „wielkie litery” na niestandardowy .

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

5. Sprawdź efekty funkcji w interfejsie użytkownika Pakietu emulatorów:

   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 oryginał a także wersję wiadomości pisaną wielkimi literami (jeśli była „WIELKIE LITERY” zobaczysz tylko „WIELKIE LITERY”).

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 który trzeba wdrożyć w środowisku produkcyjnym, musi być objęta abonamentem Blaze. Zobacz Cennik Cloud Functions

Aby ukończyć samouczek, wdróż funkcje, a następnie wykonaj te czynności .

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

    firebase deploy --only functions
    

   Po uruchomieniu tego polecenia interfejs wiersza poleceń Firebase wyświetla URL każdej wartości Funkcja HTTP i punktów końcowych. 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 żądania HTTP . Chociaż nie musisz się tym teraz przejmować, niektóre produkcyjne wersje HTTP funkcje powinny określać lokalizację oraz zminimalizować opóźnienia sieciowe.

   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. Ten zdarzenie zapisu uruchamia działanie „wielkimi literami”; funkcja, która zapisuje wielkie litery wersji ciągu znaków.

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 interfejsu wiersza poleceń Firebase.

W środowisku produkcyjnym warto zoptymalizować wydajność funkcji i kontrolę przez ustawienie minimalnej i maksymalnej liczby uruchomionych instancji. Zobacz Sterowanie skalowaniem .

Dalsze kroki

Z tej dokumentacji dowiesz się, jak: zarządzanie funkcjami w Cloud Functions oraz instrukcje do obsługi wszystkich typów zdarzeń obsługiwanych przez Cloud Functions.

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

• Zapoznaj się z przypadkami użycia Cloud Functions.
• Wykonaj ćwiczenie z programowania w Cloud Functions.
• Sprawdź i uruchom przykładowy kod na GitHubie