Erste Schritte: Schreiben, Testen und Bereitstellen von Funktionen (1. Generation)

Wenn Sie mit Cloud Functions beginnen möchten, können Sie diese Anleitung durcharbeiten. Sie beginnt mit den erforderlichen Einrichtungsaufgaben und führt Sie durch das Erstellen, Testen und Bereitstellen von zwei zugehörigen Funktionen:

• Eine Funktion „add message“, die eine URL bereitstellt, die einen Textwert akzeptiert und in Cloud Firestore schreibt.
• Eine Funktion „In Großbuchstaben umwandeln“, 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-getriggerte JavaScript-Funktionen ausgewählt, da diese Hintergrundtrigger mit dem Firebase Local Emulator Suite gründlich getestet werden können. Dieses Toolset unterstützt auch Realtime Database, Pub/Sub, Auth und HTTP-aufrufbare Trigger. Andere Arten von Hintergrundtriggern wie Remote Config, TestLab und Analytics-Trigger können alle interaktiv getestet werden. Dazu werden Toolsets verwendet, die auf dieser Seite nicht beschrieben werden.

In den folgenden Abschnitten dieser Anleitung werden die Schritte zum Erstellen, Testen und Bereitstellen des Beispiels beschrieben. Wenn Sie den Code lieber nur ausführen und prüfen möchten, fahren Sie mit Vollständigen Beispielcode prüfen fort.

Firebase-Projekt erstellen

Node.js und die Firebase CLI einrichten

Sie benötigen eine Node.js-Umgebung, um Funktionen zu schreiben, 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.

Nachdem Sie Node.js und npm installiert haben, installieren Sie die Firebase-Befehlszeile mit Ihrer bevorzugten 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. Wenn Sie auf die aktuelle Version von firebase-tools aktualisieren möchten, führen Sie denselben Befehl noch einmal aus.

Projekt initialisieren

Wenn Sie das Firebase SDK für Cloud Functions initialisieren, erstellen Sie ein leeres Projekt mit Abhängigkeiten und minimalem Beispielcode. Außerdem 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 Verzeichnis Ihres Firebase-Projekts auf.

3. Führen Sie firebase init firestore aus. In dieser Anleitung können Sie die Standardwerte übernehmen, wenn Sie nach Firestore-Regeln und Indexdateien gefragt werden. Wenn Sie Cloud Firestore in diesem Projekt noch nicht verwendet haben, müssen Sie außerdem 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. Die Befehlszeile fordert Sie auf, eine vorhandene Codebasis auszuwählen oder eine neue zu initialisieren und zu benennen. Zu Beginn reicht eine einzelne Codebasis am Standardspeicherort aus. Wenn Ihre Implementierung später umfangreicher wird, sollten Sie die Funktionen in Codebasen organisieren.

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

   • JavaScript
   • Python
   • 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 Anfrage ablehnen, wenn Sie Abhängigkeiten auf andere Weise verwalten möchten. Wenn Sie die Anfrage ablehnen, müssen Sie jedoch 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"}. Damit wird die Node.js-Version zum Schreiben und Bereitstellen von Funktionen angegeben. Sie können andere unterstützte Versionen auswählen.

Erforderliche Module importieren und Anwendung initialisieren

Nachdem Sie die Einrichtungsaufgaben abgeschlossen haben, können Sie das Quellverzeichnis öffnen und Code hinzufügen, wie in den folgenden Abschnitten beschrieben. Für dieses Beispiel muss Ihr Projekt die Module Cloud Functions und Admin SDK mit Node-require-Anweisungen importieren. 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 { initializeApp } = require("firebase-admin/app");
const { getFirestore } = require("firebase-admin/firestore");
initializeApp();
index.js

Mit diesen Zeilen werden die Module firebase-functions und firebase-admin geladen und eine admin-Anwendungsinstanz initialisiert, über die Cloud Firestore-Änderungen vorgenommen werden können. Überall dort, wo Admin SDK-Unterstützung verfügbar ist, wie für FCM, Authentication und Firebase Realtime Database, bietet es eine leistungsstarke Möglichkeit, Firebase mithilfe von Cloud Functions zu integrieren.

Die Firebase-Befehlszeile installiert automatisch das Firebase SDK und das Firebase SDK für Cloud Functions-Node-Module, wenn Sie Ihr Projekt initialisieren. Wenn Sie Ihrem Projekt Drittanbieterbibliotheken hinzufügen möchten, können Sie package.json ändern und npm install ausführen. Weitere Informationen finden Sie unter Abhängigkeiten verarbeiten.

Fügen Sie die Funktion addMessage() hinzu:

Fügen Sie für die Funktion addMessage() die folgenden Zeilen in index.js ein:

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

Die Funktion addMessage() ist ein HTTP-Endpunkt. Jede Anfrage an den Endpunkt führt dazu, dass Request- und Response-Objekte im ExpressJS-Stil 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.

Fügen Sie die Funktion makeUppercase() hinzu:

Fügen Sie für die Funktion makeUppercase() die folgenden Zeilen in index.js ein:

// 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. Die Funktion ref.set definiert das zu überwachende Dokument. Aus Leistungsgründen sollten Sie so spezifisch wie möglich sein.

Geschweifte Klammern, z. B. {documentId}, umschließen „Parameter“, also Platzhalter, die ihre übereinstimmenden Daten im Callback verfügbar machen.

Cloud Firestore löst den Callback onCreate() aus, wenn neue Nachrichten hinzugefügt werden.

Ereignisgesteuerte Funktionen wie Cloud Firestore-Ereignisse sind asynchron. Die Callback-Funktion sollte entweder ein null, ein Objekt oder ein Promise zurückgeben. Wenn Sie nichts zurückgeben, kommt es zu einer Zeitüberschreitung der Funktion, was einen Fehler signalisiert, und die Funktion wird noch einmal ausgeführt. Weitere Informationen finden Sie unter Synchron, asynchron und Promises.

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, unter anderem, weil sie das Risiko von Programmierfehlern verringern, die in einer Produktionsumgebung potenziell Kosten verursachen könnten (z. B. eine Endlosschleife).

So emulieren Sie Ihre Funktionen:

1. Führen Sie firebase emulators:start aus und prüfen Sie die Ausgabe auf die URL des Emulator Suite UI. Der Standardwert ist localhost:4000, aber die Anwendung kann 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 die Ausgabe des Befehls firebase emulators:start auf die URL der HTTP-Funktion addMessage(). Sie sieht ähnlich aus wie http://localhost:5001/MY_PROJECT/us-central1/addMessage, mit folgenden Ausnahmen:

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

3. Fügen Sie den Abfragestring ?text=uppercaseme am Ende der Funktions-URL hinzu. Das sollte in 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 Emulator Suite UI an:

   1. Auf dem Tab Logs sollten Sie neue Logs sehen, 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 sowie der Version Ihrer Nachricht in Großbuchstaben angezeigt werden (wenn sie ursprünglich „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 Node.js 14-Laufzeitumgebung das Blaze-Preismodell verwenden muss. Weitere Informationen finden Sie unter Cloud Functions-Preise.

Stellen Sie zum Abschließen der Anleitung Ihre 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 HTTP-Funktionsendpunkte 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 HTTP-Funktionen in der Produktion sollte ein Standort angegeben werden, um die Netzwerklatenz zu minimieren.

   Wenn Zugriffsfehler wie „Zugriff auf Projekt kann nicht autorisiert werden“ auftreten, prüfen Sie das Projekt-Aliasing.

2. Fügen Sie der von der Befehlszeile ausgegebenen addMessage()-URL einen Suchparameter 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 zur Firebase-Konsole am Speicherort der Datenbank weiter, an dem der Textstring gespeichert ist. Dieses Schreibereignis löst makeUppercase() aus, wodurch eine Großbuchstabenversion des Strings geschrieben wird.

Nachdem Sie Funktionen bereitgestellt und ausgeführt haben, können Sie Logs in der Google Cloud-Konsole aufrufen. Wenn Sie Funktionen in der Entwicklung oder Produktion 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 Höchstzahl von Instanzen festlegen, die ausgeführt werden sollen. Weitere Informationen zu diesen Laufzeitoptionen finden Sie unter Skalierungsverhalten steuern.

Vollständigen Beispielcode ansehen

Hier ist die vollständige 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 transformiert, indem alle Zeichen im String in Großbuchstaben umgewandelt 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 { 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 = 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 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 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.

Wenn Sie mehr über Cloud Functions erfahren möchten, können Sie auch Folgendes tun:

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