Erste Schritte: Erste Funktionen schreiben, testen und bereitstellen

2. Generation 1. Generation

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.

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

Hinweis: Sie können Funktionen in jedem Firebase-Projekt emulieren. Für die Bereitstellung in der empfohlenen Node.js 14-Laufzeitumgebung muss Ihr Projekt jedoch das Blaze-Preismodell haben. Siehe Cloud Functions-Preise.

In den folgenden Abschnitten dieser Anleitung werden die Schritte zum Erstellen, Testen und Bereitstellen des Beispiels beschrieben. Wenn Sie den Code lieber einfach ausführen und prüfen möchten, springen Sie zu „Vollständigen Beispielcode ansehen“.

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.

     Firebase generiert eine eindeutige ID für Ihr Firebase-Projekt basierend auf dem von Ihnen angegebenen Namen. Wenn Sie diese Projekt-ID bearbeiten möchten, müssen Sie dies jetzt tun. Sie kann nicht mehr geändert werden, nachdem Firebase Ressourcen für Ihr Projekt bereitgestellt hat. Unter Informationen zu Firebase-Projekten erfahren Sie, wie Firebase die Projekt-ID verwendet.

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 nutzen zu können:

   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.

   Sie können Google Analytics jederzeit später in den Projekteinstellungen auf dem Tab Integrationen von einrichten.

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.

Node.js und die Firebase CLI einrichten

Sie benötigen eine Node.js-Umgebung zum Schreiben von Funktionen und die Firebase-Befehlszeile, um Funktionen in der Cloud Functions-Laufzeit bereitzustellen. Für die Installation von Node.js und npm wird der Node Version Manager empfohlen.

Wichtig: Die Node.js-Versionen 14 und 16 werden unterstützt. Wichtige Informationen zum laufenden Support für diese Node.js-Versionen finden Sie unter Laufzeitoptionen festlegen.

Nachdem Sie Node.js und npm installiert haben, installieren Sie die Firebase-Befehlszeile mit der gewünschten Methode. So installieren Sie die Befehlszeile über npm:

npm install -g firebase-tools

Dadurch wird der global verfügbare Befehl „firebase“ installiert. Wenn der Befehl fehlschlägt, müssen Sie möglicherweise die npm-Berechtigungen ändern. Führen Sie denselben Befehl noch einmal aus, um auf die neueste Version von firebase-tools zu aktualisieren.

In vielen Fällen sind neue Funktionen und Fehlerkorrekturen nur mit der neuesten Version der Firebase CLI und des firebase-functions SDK verfügbar. Es empfiehlt sich, sowohl die Firebase CLI als auch das SDK regelmäßig mit diesen Befehlen im Ordner functions Ihres Firebase-Projekts zu aktualisieren:

npm install firebase-functions@latest firebase-admin@latest --save
npm install -g firebase-tools

Projekt initialisieren

Wenn Sie das Firebase SDK für Cloud Functions initialisieren, erstellen Sie ein leeres Projekt mit Abhängigkeiten und etwas Minimalbeispielcode und wählen Sie entweder TypeScript oder JavaScript zum Erstellen von Funktionen aus. 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 Speicherort 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 Befehlszeile 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 zwei Optionen für die Sprachunterstützung:

   • JavaScript
   • TypeScript Weitere Informationen finden Sie unter Funktionen mit TypeScript schreiben.

   Wählen Sie für diese Anleitung JavaScript aus.

6. Die Befehlszeile bietet Ihnen die Möglichkeit, Abhängigkeiten mit npm zu installieren. Sie können die Option auch ablehnen, wenn Sie Abhängigkeiten auf andere Weise verwalten möchten. Wenn Sie sie jedoch ablehnen, müssen Sie npm install ausführen, bevor Sie Ihre Funktionen emulieren oder bereitstellen.

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

Die während der Initialisierung erstellte Datei package.json enthält einen wichtigen Schlüssel: "engines": {"node": "16"}. Hier wird die Node.js-Version für das Schreiben und Bereitstellen von Funktionen angegeben. Sie können andere unterstützte Versionen auswählen.

Erforderliche Module importieren und App initialisieren

Nachdem Sie die Einrichtungsschritte abgeschlossen haben, können Sie das Quellverzeichnis öffnen und mit dem Hinzufügen von Code beginnen, wie in den folgenden Abschnitten beschrieben. Für dieses Beispiel müssen die Cloud Functions- und Admin SDK-Module mithilfe von Node require-Anweisungen in Ihr Projekt importiert werden. Fügen Sie der Datei index.js Zeilen wie die folgenden hinzu:

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

Mit diesen Zeilen werden die firebase-functions- und firebase-admin-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- und Firebase-SDK für Cloud Functions-Node-Module, wenn Sie Ihr Projekt initialisieren. Wenn Sie Ihrem Projekt Bibliotheken von Drittanbietern hinzufügen möchten, können Sie package.json ändern und npm install ausführen. Weitere Informationen finden Sie unter Abhängigkeiten behandeln.

Funktion addMessage() hinzufügen

Fügen Sie für die Funktion addMessage() diese Zeilen zu index.js hinzu:

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

Die Funktion addMessage() ist ein HTTP-Endpunkt. Jede Anfrage an den Endpunkt führt zu Request- und Response-Objekten im ExpressJS-Stil, die an den Callback onRequest() ü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 addMessage() übergibt einen Textwert an den HTTP-Endpunkt und fügt ihn unter dem Pfad /messages/:documentId/original in die Datenbank ein.

makeUppercase()-Funktion hinzufügen

Fügen Sie für die Funktion makeUppercase() diese Zeilen zu index.js hinzu:

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

Die Funktion makeUppercase() wird ausgeführt, wenn in Cloud Firestore geschrieben wird. Mit der Funktion ref.set wird das Dokument definiert, das überwacht werden soll. Aus Leistungsgründen sollten Sie möglichst genau 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 onCreate() aus, sobald neue Nachrichten hinzugefügt werden.

Achtung :Achten Sie darauf, dass das Ergebnis der Funktion die Funktion nicht noch einmal auslöst und so eine Endlosschleife entsteht. Das ist beispielsweise bei einer Funktion der Fall, die durch Schreibvorgänge in ein bestimmtes Cloud Firestore-Dokument ausgelöst wird und durch Schreibvorgänge in denselben Pfad beendet wird. Schreiben Sie Funktionen außerdem idempotent, sodass sie dasselbe Ergebnis erzeugen, wenn sie für ein einzelnes Ereignis mehrmals ausgeführt werden.

Ereignisgesteuerte Funktionen wie Cloud Firestore-Ereignisse sind 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 Anwendungen auf Ihrem lokalen Computer erstellen und testen, anstatt sie in einem Firebase-Projekt bereitzustellen. Lokale Tests während der Entwicklung werden dringend empfohlen. Das liegt unter anderem daran, dass dadurch das Risiko von Codierungsfehlern verringert wird, die in einer Produktionsumgebung (z. B. bei einer Endlosschleife) potenziell Kosten verursachen können.

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. Standardmäßig ist localhost:4000 festgelegt, es kann aber auch 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 addMessage() 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 Emulator Suite UI an:

   1. Auf dem Tab Protokolle sollten neue Protokolle angezeigt werden, die darauf hinweisen, dass die Funktionen addMessage() und makeUppercase() 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 und der Großbuchstabenversion Ihrer Nachricht angezeigt werden. Wenn die ursprüngliche Nachricht „uppercaseme“ lautete, wird „UPPERCASEME“ angezeigt.

Funktionen in einer Produktionsumgebung bereitstellen

Sobald Ihre Funktionen im Emulator wie gewünscht funktionieren, können Sie mit der Bereitstellung, dem Testen und dem Ausführen in der Produktionsumgebung fortfahren. Beachten Sie, dass Ihr Projekt für die Bereitstellung in der empfohlenen Node.js 14-Laufzeitumgebung den Blaze-Tarif haben muss. Siehe Cloud Functions-Preise.

Stellen Sie zum Abschließen der Anleitung die Funktionen bereit und führen Sie dann addMessage() aus, um makeUppercase() auszulösen.

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. Sie müssen sich jetzt noch keine Gedanken darüber machen, aber für einige Produktions-HTTP-Funktionen sollte ein Speicherort angegeben werden, 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 addMessage()-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 an die Firebase-Konsole am Speicherort der Datenbank weitergeleitet, in der der Textstring gespeichert ist. Dieses Schreibereignis löst makeUppercase() aus, wodurch eine Großbuchstabenversion des Strings geschrieben wird.

Nach der Bereitstellung und Ausführung von Funktionen können Sie sich die Logs in der Google Cloud-Konsole ansehen. Wenn Sie Funktionen in der Entwicklungs- oder Produktionsumgebung löschen möchten, verwenden Sie die Firebase CLI.

In der Produktion können Sie die Funktionsleistung optimieren und die Kosten steuern, indem Sie eine Mindest- und eine Höchstzahl von Instanzen festlegen. Weitere Informationen zu diesen Laufzeitoptionen finden Sie unter Skalierungsverhalten steuern.

Hinweis: Die Bereitstellung von Funktionen über die Firebase-Befehlszeile unterliegt Ratenbegrenzungen. Weitere Informationen finden Sie unter Kontingentlimits für die Bereitstellung der Firebase-Befehlszeile.

Vollständigen Beispielcode ansehen

Hier ist der fertige functions/index.js mit den Funktionen addMessage() und makeUppercase(). Mit diesen Funktionen können Sie einen Parameter an einen HTTP-Endpunkt übergeben, der einen Wert in Cloud Firestore schreibt und ihn dann so transformiert, dass alle Zeichen im String in Großbuchstaben geschrieben werden.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

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

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin
    .firestore()
    .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 creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

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