Erste Schritte: Erste Funktionen schreiben, testen und bereitstellen

In dieser Anleitung erfahren Sie, wie Sie Cloud Functions einrichten und zwei zugehörige Funktionen erstellen, testen und bereitstellen.

• Eine Funktion „add message“, die eine URL bereitstellt, die einen Textwert akzeptiert und in Cloud Firestore schreibt.
• Eine Funktion „in Großbuchstaben schreiben“, die bei einem Cloud Firestore-Schreibvorgang ausgelöst wird und den Text in Großbuchstaben umwandelt.

Hier ist der vollständige Beispielcode mit den Funktionen:

// 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

Informationen zu dieser Anleitung

Wir haben für dieses Beispiel teilweise Cloud Firestore und durch HTTP ausgelöste Funktionen ausgewählt, weil diese Hintergrundtrigger über Firebase Local Emulator Suite gründlich getestet werden können. Dieses Toolset unterstützt auch Realtime Database, Cloud Storage, PubSub, Auth und HTTP-aufrufbare Trigger. Andere Arten von Hintergrundtriggern wie Remote Config- und TestLab-Trigger können mit Toolsets, die auf dieser Seite nicht beschrieben werden, interaktiv getestet werden.

In den folgenden Abschnitten dieser Anleitung werden die Schritte zum Erstellen, Testen und Bereitstellen des Beispiels beschrieben.

Firebase-Projekt erstellen

1. Klicken Sie in der Firebase Console auf Projekt hinzufügen.

   • Wenn Sie einem vorhandenen Google Cloud-Projekt Firebase-Ressourcen hinzufügen möchten, geben Sie den Projektnamen ein oder wählen Sie ihn aus dem Drop-down-Menü aus.

   • Geben Sie den gewünschten Projektnamen ein, um ein neues Projekt zu erstellen. Optional können Sie auch die Projekt-ID bearbeiten, die unter dem Projektnamen angezeigt wird.

2. Lesen und akzeptieren Sie die Nutzungsbedingungen von Firebase, wenn Sie dazu aufgefordert werden.

3. Klicken Sie auf Weiter.

4. (Optional) Richten Sie Google Analytics für Ihr Projekt ein, um die folgenden Firebase-Produkte optimal zu nutzen:

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Remote Config-Personalisierung Firebase A/B Testing

   Wählen Sie entweder ein vorhandenes Google Analytics-Konto aus oder erstellen Sie ein neues.

   Wenn Sie ein neues Konto erstellen, wählen Sie Ihren AnalyticsSpeicherort für Berichte aus und akzeptieren Sie dann die Datenfreigabeeinstellungen und Google Analytics-Nutzungsbedingungen für Ihr Projekt.

5. Klicken Sie auf Projekt erstellen (oder auf Firebase hinzufügen, wenn Sie ein vorhandenes Google Cloud-Projekt verwenden).

Firebase stellt automatisch Ressourcen für Ihr Firebase-Projekt bereit. Nach Abschluss des Vorgangs werden Sie zur Übersichtsseite für Ihr Firebase-Projekt in der Firebase Console weitergeleitet.

Umgebung und Firebase CLI einrichten

Projekt initialisieren

Wenn Sie das Firebase SDK für Cloud Functions initialisieren, erstellen Sie ein leeres Projekt mit Abhängigkeiten und etwas Minimalbeispielcode. Wenn Sie Node.js verwenden, können Sie entweder TypeScript oder JavaScript zum Erstellen von Funktionen auswählen. Für diese Anleitung müssen Sie auch Cloud Firestore initialisieren.

So initialisieren Sie Ihr Projekt:

1. Führen Sie firebase login aus, um sich über den Browser anzumelden und die Firebase-Befehlszeile zu authentifizieren.
2. Rufen Sie das Firebase-Projektverzeichnis auf.
3. Führen Sie firebase init firestore aus. Für diese Anleitung können Sie die Standardwerte akzeptieren, wenn Sie nach Firestore-Regeln und Indexdateien gefragt werden. Wenn Sie Cloud Firestore in diesem Projekt noch nicht verwendet haben, müssen Sie auch einen Startmodus und einen Standort für Firestore auswählen, wie unter Erste Schritte mit Cloud Firestore beschrieben.
4. Führen Sie firebase init functions aus. Sie werden aufgefordert, eine vorhandene Codebasis auszuwählen oder eine neue zu initialisieren und zu benennen. Wenn Sie gerade erst anfangen, reicht eine einzelne Codebasis am Standardspeicherort aus. Wenn Sie Ihre Implementierung später erweitern, können Sie Funktionen in Codebases organisieren.

5. Die Befehlszeile bietet die folgenden Optionen für die Sprachunterstützung:

   • JavaScript
   • TypeScript
   • Python

   Wählen Sie für diese Anleitung JavaScript oder Python aus. Informationen zum Erstellen in TypeScript finden Sie unter Funktionen mit TypeScript schreiben.

6. Die Befehlszeile bietet Ihnen die Möglichkeit, Abhängigkeiten zu installieren. Sie können dies ablehnen, wenn Sie Abhängigkeiten auf andere Weise verwalten möchten.

Nachdem diese Befehle erfolgreich ausgeführt wurden, sieht Ihre Projektstruktur so aus:

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

Erforderliche Module importieren und eine App initialisieren

Nachdem Sie die Einrichtungsaufgaben abgeschlossen haben, können Sie das Quellverzeichnis öffnen und wie in den folgenden Abschnitten beschrieben Code hinzufügen. Für dieses Beispiel müssen die Module Cloud Functions und Admin SDK in Ihr Projekt importiert werden. Fügen Sie Ihrer Quelldatei Zeilen wie die folgenden hinzu:

// 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

Mit diesen Zeilen werden die erforderlichen Module geladen und eine admin-App-Instanz initialisiert, über die Cloud Firestore-Änderungen vorgenommen werden können. Überall dort, wo das Admin SDK unterstützt wird, z. B. für FCM, Authentication und Firebase Realtime Database, ist es eine leistungsstarke Möglichkeit, Firebase mit Cloud Functions zu integrieren.

Die Firebase-Befehlszeile installiert automatisch das Firebase Admin SDK und das Firebase SDK für Cloud Functions-Module, wenn Sie Ihr Projekt initialisieren. Weitere Informationen zum Hinzufügen von Drittanbieterbibliotheken zu Ihrem Projekt finden Sie unter Abhängigkeiten handhaben.

Funktion „Nachricht hinzufügen“ hinzufügen

Fügen Sie der Quelldatei für die Funktion „add message“ die folgenden Zeilen hinzu:

// 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

Die Funktion „add message“ ist ein HTTP-Endpunkt. Jede Anfrage an den Endpunkt führt zu Anfrage- und Antwortobjekten, die an den Anfragehandler für Ihre Plattform (onRequest() oder on_request) übergeben werden.

HTTP-Funktionen sind synchron (ähnlich wie aufrufbare Funktionen). Sie sollten daher so schnell wie möglich eine Antwort senden und die Arbeit mit Cloud Firestore verschieben. Die HTTP-Funktion „add message“ übergibt einen Textwert an den HTTP-Endpunkt und fügt ihn unter dem Pfad /messages/:documentId/original in die Datenbank ein.

Funktion „in Großbuchstaben“ hinzufügen

Fügen Sie Ihrer Quelldatei für die Funktion „in Großbuchstaben“ die folgenden Zeilen hinzu:

// 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

Die Funktion „in Großbuchstaben“ wird ausgeführt, wenn in Cloud Firestore geschrieben wird. Damit wird das Dokument definiert, das überwacht werden soll. Aus Leistungsgründen sollten Sie so konkret wie möglich sein.

Schrägstriche (z. B. {documentId}) umschließen „Parameter“, also Platzhalter, die die übereinstimmenden Daten im Rückruf freigeben. Cloud Firestore löst den Rückruf aus, wenn neue Nachrichten hinzugefügt werden.

In Node.js sind ereignisgesteuerte Funktionen wie Cloud Firestore-Ereignisse asynchron. Die Rückgabe der Callback-Funktion muss entweder ein null, ein Objekt oder ein Versprechen sein. Wenn Sie nichts zurückgeben, läuft die Funktion ab, es wird ein Fehler ausgegeben und der Vorgang wird wiederholt. Weitere Informationen finden Sie unter Synchronisieren, asynchron und verspricht.

Ausführung Ihrer Funktionen emulieren

Mit der Firebase Local Emulator Suite können Sie Apps auf Ihrem lokalen Computer erstellen und testen, anstatt sie in einem Firebase-Projekt bereitzustellen. Lokale Tests während der Entwicklung werden dringend empfohlen, zum Teil, weil dadurch das Risiko von Programmierfehlern verringert wird, die in einer Produktionsumgebung möglicherweise Kosten verursachen (z. B. ein Endlos-Loop).

So emulieren Sie Ihre Funktionen:

1. Führen Sie firebase emulators:start aus und prüfen Sie in der Ausgabe, ob die URL des Emulator Suite UI enthalten ist. Die Standardeinstellung ist localhost:4000, kann aber auf einem anderen Port auf Ihrem Computer gehostet werden. Geben Sie diese URL in Ihren Browser ein, um die Emulator Suite UI zu öffnen.

2. Prüfen Sie in der Ausgabe des Befehls firebase emulators:start, ob die URL der HTTP-Funktion enthalten ist. Sie sieht ungefähr so aus wie http://localhost:5001/MY_PROJECT/us-central1/addMessage, mit folgenden Unterschieden:

   1. MY_PROJECT wird durch Ihre Projekt-ID ersetzt.
   2. Der Port kann auf Ihrem lokalen Computer anders sein.

3. Fügen Sie den Suchstring ?text=uppercaseme an das Ende der URL der Funktion an. Er sollte in etwa so aussehen: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Optional können Sie die Nachricht „uppercaseme“ durch eine benutzerdefinierte Nachricht ersetzen.

4. Öffnen Sie die URL in einem neuen Tab in Ihrem Browser, um eine neue Nachricht zu erstellen.

5. Sehen Sie sich die Auswirkungen der Funktionen in der Emulator Suite UI an:

   1. Auf dem Tab Protokolle sollten neue Protokolle angezeigt werden, die darauf hinweisen, dass Ihre HTTP-Funktionen erfolgreich ausgeführt wurden:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. Auf dem Tab Firestore sollte ein Dokument zu sehen sein, das sowohl Ihre ursprüngliche Nachricht als auch Ihre Version in Großbuchstaben enthält. Wenn sie ursprünglich in Großbuchstaben geschrieben war, wird sie in GROSSBUCHSTABEN angezeigt.

Funktionen in einer Produktionsumgebung bereitstellen

Sobald Ihre Funktionen im Emulator wie gewünscht funktionieren, können Sie sie in der Produktionsumgebung bereitstellen, testen und ausführen. Für die Bereitstellung in der Produktion muss Ihr Projekt den Blaze-Tarif haben. Weitere Informationen finden Sie unter Cloud Functions-Preise.

Zum Abschluss der Anleitung müssen Sie Ihre Funktionen bereitstellen und dann ausführen.

1. Führen Sie diesen Befehl aus, um Ihre Funktionen bereitzustellen:

    firebase deploy --only functions
    

   Nachdem Sie diesen Befehl ausgeführt haben, gibt die Firebase-Befehlszeile die URL für alle Endpunkte der HTTP-Funktion aus. Im Terminal sollte eine Zeile wie die folgende angezeigt werden:

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   Die URL enthält Ihre Projekt-ID sowie eine Region für die HTTP-Funktion. Auch wenn Sie sich jetzt noch keine Gedanken darüber machen müssen, sollten einige Produktions-HTTP-Funktionen einen Speicherort angeben, um die Netzwerklatenz zu minimieren.

   Wenn Zugriffsfehler wie „Zugriff auf Projekt kann nicht autorisiert werden“ auftreten, prüfen Sie den Alias Ihres Projekts.

2. Fügen Sie der von der Befehlszeile ausgegeben URL einen Textabfrageparameter hinzu und öffnen Sie sie in einem Browser:

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

   Die Funktion wird ausgeführt und leitet den Browser an die Firebase-Konsole an dem Datenbankstandort weiter, in dem der Textstring gespeichert ist. Dieses Schreibereignis löst die Funktion „in Großbuchstaben schreiben“ aus, die eine Großbuchstabenversion des Strings schreibt.

Nach der Bereitstellung und Ausführung von Funktionen können Sie sich die Logs in der Google Cloud-Konsole ansehen. Wenn Sie in der Entwicklung oder Produktion Funktionen löschen müssen, verwenden Sie die Firebase-Befehlszeile.

In der Produktion können Sie die Funktionsleistung optimieren und die Kosten kontrollieren, indem Sie eine Mindest- und eine Höchstanzahl von Instanzen festlegen, die ausgeführt werden sollen. Weitere Informationen zu diesen Laufzeitoptionen finden Sie unter Skalierungsverhalten steuern.

Nächste Schritte

In dieser Dokumentation erfahren Sie mehr darüber, wie Sie Funktionen für Cloud Functions verwalten und wie Sie alle von Cloud Functions unterstützten Ereignistypen verarbeiten.

Weitere Informationen zu Cloud Functions findest du auch hier:

• Weitere Informationen zu Anwendungsfällen für Cloud Functions
• Cloud Functions-Codelab ausprobieren
• Codebeispiele auf GitHub ansehen und ausführen