Erste Schritte: Erste Funktionen schreiben, testen und bereitstellen

Wenn Sie mit Cloud Functions beginnen möchten, arbeiten Sie diese Anleitung durch. Sie beginnt mit den erforderlichen Einrichtungsaufgaben und führt Sie durch das Erstellen, Testen, und Bereitstellen von zwei verknüpften Funktionen:

• Eine Funktion zum Hinzufügen von Nachrichten, die eine URL bereitstellt, die einen Textwert akzeptiert und ihn in Cloud Firestoreschreibt.
• Eine Funktion zum Umwandeln in Großbuchstaben, 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/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

Informationen zu dieser Anleitung

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

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

Firebase-Projekt erstellen

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 minimalem Beispielcode. Wenn Sie Node.js verwenden, können Sie für das Erstellen von Funktionen entweder TypeScript oder JavaScript auswählen. Für diese Anleitung müssen Sie auch Cloud Firestoreinitialisieren.

So initialisieren Sie Ihr Projekt:

1. Führen Sie firebase login aus, um sich über den Browser anzumelden und die Firebase CLI zu authentifizieren.
2. Wechseln Sie zum Verzeichnis Ihres Firebase-Projekts.
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 von der CLI 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. Später, wenn Ihre Implementierung umfangreicher wird, sollten Sie Funktionen möglicherweise in Codebasen organisieren.

5. Die CLI 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 CLI 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 Einrichtung abgeschlossen haben, können Sie das Quellverzeichnis öffnen und Code hinzufügen, wie in den folgenden Abschnitten beschrieben. Für dieses Beispiel müssen in Ihrem Projekt die Cloud Functions und Admin SDK Module 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/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

Diese Zeilen laden die erforderlichen Module und initialisieren eine admin App-Instanz, über die Cloud Firestore Änderungen vorgenommen werden können. Überall dort, wo Admin SDK-Unterstützung verfügbar ist, wie bei FCM, Authentication, und Firebase Realtime Database, bietet es eine leistungsstarke Möglichkeit, Firebase mit Cloud Functions zu verknüpfen.

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

Funktion zum Hinzufügen von Nachrichten hinzufügen

Fügen Sie für die Funktion zum Hinzufügen von Nachrichten diese Zeilen Ihrer Quelldatei 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 zum Hinzufügen von Nachrichten ist ein HTTP-Endpunkt. Jede Anfrage an den Endpunkt führt dazu, dass Anfrage- und Antwortobjekte an den 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 aufschieben. Die HTTP-Funktion zum Hinzufügen von Nachrichten übergibt einen Textwert an den HTTP-Endpunkt und fügt ihn unter dem Pfad /messages/:documentId/original in die Datenbank ein.

Funktion zum Umwandeln in Großbuchstaben hinzufügen

Fügen Sie für die Funktion zum Umwandeln in Großbuchstaben diese Zeilen Ihrer Quelldatei 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 zum Umwandeln in Großbuchstaben wird ausgeführt, wenn Cloud Firestore geschrieben wird, und definiert das Dokument, das überwacht werden soll. Aus Leistungsgründen sollten Sie so genau wie möglich sein.

Geschweifte Klammern, z. B. {documentId}, umgeben „Parameter“, Platzhalter, die ihre übereinstimmenden Daten im Callback verfügbar machen. Cloud Firestore löst den Callback aus, wenn neue Nachrichten hinzugefügt werden.

In Node.js sind ereignisgesteuerte Funktionen wie Cloud Firestore Ereignisse asynchron. Die Callback-Funktion sollte entweder ein null, ein Objekt, oder ein Promise zurückgeben. Wenn Sie nichts zurückgeben, tritt für die Funktion ein Zeitlimit auf, was einen Fehler signalisiert, und sie wird noch einmal ausgeführt. Weitere Informationen finden Sie unter Synchron, asynchron und Promises.

Ausführung der Funktionen emulieren

Die Firebase Local Emulator Suite ermöglicht Ihnen das Erstellen und Testen von Apps auf Ihrem lokalen Computer, anstatt sie in einem Firebase-Projekt bereitzustellen. Lokale Tests während der Entwicklung werden dringend empfohlen, da sie unter anderem das Risiko von Programmierfehlern verringern, die in einer Produktionsumgebung Kosten verursachen könnten (z. B. eine Endlosschleife).

So emulieren Sie Ihre Funktionen:

1. Führen Sie firebase emulators:start aus und suchen Sie in der Ausgabe nach der URL der Emulator Suite UI. Standardmäßig ist sie „localhost:4000“, kann aber auf einem anderen Port auf Ihrem Computer gehostet werden. Geben Sie diese URL in Ihrem Browser ein, um die Emulator Suite UI zu öffnen.

2. Suchen Sie in der Ausgabe des Befehls firebase emulators:start nach der URL der HTTP-Funktion. Sie sieht etwa so aus: http://localhost:5001/MY_PROJECT/us-central1/addMessage. Dabei gilt:

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

3. Fügen Sie den Abfragestring ?text=uppercaseme am Ende der URL der Funktion hinzu. Sie sollte etwa so aussehen: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Optional können Sie die Nachricht "uppercaseme" in eine benutzerdefinierte Nachricht ändern.

4. Erstellen Sie eine neue Nachricht, indem Sie die URL in einem neuen Tab in Ihrem Browser öffnen.

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

   1. Auf dem Tab Logs sollten neue Logs 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 mit Ihrer ursprünglichen Nachricht sowie der in Großbuchstaben umgewandelten Version Ihrer Nachricht angezeigt werden. Wenn die ursprüngliche Nachricht „uppercaseme“ war, sehen Sie „UPPERCASEME“.

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. Beachten Sie, dass Ihr Projekt für die Bereitstellung in der Produktion den Blaze-Tarif haben muss. Weitere Informationen finden Sie unter Cloud Functions Preise.

Um die Anleitung abzuschließen, stellen Sie Ihre Funktionen bereit und führen Sie sie dann aus.

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 CLI die URL für alle HTTP-Funktions endpunkte aus. In Ihrem 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. Obwohl Sie sich jetzt keine Sorgen machen müssen, sollten einige HTTP Funktionen in der Produktion einen Standort angeben, um die Netzwerklatenz zu minimieren.

   Wenn Zugriffsfehler wie „Unable to authorize access to project“ auftreten, prüfen Sie die Aliasnamen Ihres Projekts.

2. Fügen Sie der von der CLI ausgegebenen 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 der Browser wird zum Firebase Konsolenstandort in der Datenbank weitergeleitet, an dem der Textstring gespeichert ist. Dieses Schreibereignis löst die Funktion zum Umwandeln in Großbuchstaben aus, die eine in Großbuchstaben umgewandelte Version des Strings schreibt.

Nachdem Sie Funktionen bereitgestellt und ausgeführt haben, können Sie Logs in der Google Cloud Console ansehen. Wenn Sie Funktionen löschen in der Entwicklung oder Produktion müssen, verwenden Sie die Firebase CLI.

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

Nächste Schritte

In dieser Dokumentation erfahren Sie mehr über das Verwalten von Funktionen für Cloud Functions sowie über den Umgang mit allen von Cloud Functionsunterstützten Ereignistypen.

Weitere Informationen zu Cloud Functions:

• Anwendungsfälle für Cloud Functions
• Probieren Sie das Cloud Functions Codelab aus.
• Codebeispiele auf GitHub ansehen und ausführen