Beginnen Sie: Schreiben, testen und implementieren Sie Ihre ersten Funktionen


Um mit Cloud Functions zu beginnen, versuchen Sie, dieses Tutorial durchzuarbeiten. Es beginnt mit den erforderlichen Einrichtungsaufgaben und führt durch das Erstellen, Testen und Bereitstellen zweier verwandter Funktionen:

  • Eine Funktion zum Hinzufügen einer Nachricht, die eine URL bereitstellt, die einen Textwert akzeptiert und ihn in Cloud Firestore schreibt.
  • Eine „Großbuchstaben erstellen“-Funktion, 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, teilweise weil diese Hintergrundauslöser mit der Firebase Local Emulator Suite gründlich getestet werden können. Dieses Toolset unterstützt auch aufrufbare Trigger für Echtzeitdatenbanken, PubSub, Auth und HTTP. Andere Arten von Hintergrundauslösern wie Remote Config-, TestLab- und Analytics-Auslöser können alle interaktiv mit Toolsets getestet werden, die auf dieser Seite nicht beschrieben werden.

In den folgenden Abschnitten dieses Tutorials werden die Schritte detailliert beschrieben, die zum Erstellen, Testen und Bereitstellen des Beispiels erforderlich sind. Wenn Sie den Code lieber einfach ausführen und untersuchen möchten, fahren Sie mit „Vollständigen Beispielcode überprüfen“ fort.

Erstellen Sie ein Firebase-Projekt

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

    • Um Firebase-Ressourcen zu einem vorhandenen Google Cloud-Projekt hinzuzufügen, geben Sie den Projektnamen ein oder wählen Sie ihn aus dem Dropdown-Menü aus.

    • Um ein neues Projekt zu erstellen, geben Sie den gewünschten Projektnamen ein. Optional können Sie auch die unter dem Projektnamen angezeigte Projekt-ID bearbeiten.

  2. Wenn Sie dazu aufgefordert werden, lesen Sie die Firebase-Bedingungen durch und akzeptieren Sie sie.

  3. Klicken Sie auf Weiter .

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

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

    Wenn Sie ein neues Konto erstellen, wählen Sie Ihren Analytics-Berichtsstandort aus und akzeptieren Sie dann die Datenfreigabeeinstellungen und Google Analytics-Bedingungen 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. Wenn der Vorgang abgeschlossen ist, werden Sie zur Übersichtsseite für Ihr Firebase-Projekt in der Firebase-Konsole weitergeleitet.

Richten Sie Node.js und die Firebase-CLI ein

Sie benötigen eine Node.js- Umgebung, um Funktionen zu schreiben, und Sie benötigen die Firebase-CLI, um Funktionen für die Cloud Functions-Laufzeit bereitzustellen. Für die Installation von Node.js und npm wird Node Version Manager empfohlen.

Sobald Sie Node.js und npm installiert haben, installieren Sie die Firebase-CLI mit Ihrer bevorzugten Methode. Um die CLI über npm zu installieren, verwenden Sie:

npm install -g firebase-tools

Dadurch wird der global verfügbare Firebase-Befehl installiert. Wenn der Befehl fehlschlägt, müssen Sie möglicherweise die NPM-Berechtigungen ändern . Um auf die neueste Version von firebase-tools zu aktualisieren, führen Sie denselben Befehl erneut aus.

Initialisieren Sie Ihr Projekt

Wenn Sie das Firebase SDK für Cloud Functions initialisieren, erstellen Sie ein leeres Projekt mit Abhängigkeiten und etwas minimalem Beispielcode und wählen entweder TypeScript oder JavaScript zum Erstellen von Funktionen. Für die Zwecke dieses Tutorials 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-CLI zu authentifizieren.
  2. Gehen Sie zu Ihrem Firebase-Projektverzeichnis.
  3. Führen Sie firebase init firestore aus. Für dieses Tutorial können Sie die Standardwerte akzeptieren, wenn Sie zur Eingabe von Firestore-Regeln und Indexdateien aufgefordert werden. Wenn Sie Cloud Firestore in diesem Projekt noch nicht verwendet haben, müssen Sie außerdem 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. Die CLI fordert Sie auf, eine vorhandene Codebasis auszuwählen oder eine neue zu initialisieren und zu benennen. Wenn Sie gerade erst anfangen, ist eine einzelne Codebasis am Standardspeicherort ausreichend. Später, wenn Ihre Implementierung erweitert wird, möchten Sie möglicherweise Funktionen in Codebasen organisieren .

  5. Die CLI bietet Ihnen zwei Optionen für die Sprachunterstützung:

    Wählen Sie für dieses Tutorial JavaScript aus.

  6. Die CLI bietet Ihnen die Möglichkeit, Abhängigkeiten mit npm zu installieren. Es ist sicher abzulehnen, wenn Sie Abhängigkeiten auf andere Weise verwalten möchten. Wenn 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 wie folgt 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 bei der Initialisierung erstellte Datei package.json enthält einen wichtigen Schlüssel: "engines": {"node": "16"} . Dies gibt Ihre Node.js-Version zum Schreiben und Bereitstellen von Funktionen an. Sie können andere unterstützte Versionen auswählen .

Importieren Sie die erforderlichen Module und initialisieren Sie eine App

Nachdem Sie die Einrichtungsaufgaben 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 muss Ihr Projekt die Cloud Functions- und Admin SDK-Module mithilfe von Node- require Anweisungen importieren. Fügen Sie Ihrer index.js Datei 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

Diese Zeilen laden die firebase-functions und firebase-admin Module und initialisieren eine admin -App-Instanz, von der aus Cloud Firestore-Änderungen vorgenommen werden können. Überall dort, wo Admin-SDK- Unterstützung verfügbar ist, wie zum Beispiel für FCM, Authentifizierung und Firebase Realtime Database, bietet sie eine leistungsstarke Möglichkeit, Firebase mithilfe von Cloud Functions zu integrieren.

Die Firebase-CLI installiert automatisch die Module Firebase und Firebase SDK für Cloud Functions Node, wenn Sie Ihr Projekt initialisieren. Um Bibliotheken von Drittanbietern zu Ihrem Projekt hinzuzufügen, können Sie package.json ändern und npm install ausführen. Weitere Informationen finden Sie unter Abhängigkeiten behandeln .

Fügen Sie die Funktion addMessage() hinzu

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 Anfrage- und Antwortobjekten im ExpressJS-Stil, die an den onRequest() Rückruf übergeben werden.

HTTP-Funktionen sind synchron (ähnlich wie aufrufbare Funktionen ), daher sollten Sie 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() 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. Die Funktion ref.set definiert das abzuhörende Dokument. Aus Leistungsgründen sollten Sie so genau wie möglich sein.

Klammern – zum Beispiel {documentId} – umgeben „Parameter“, Platzhalter, die ihre übereinstimmenden Daten im Rückruf offenlegen.

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

Ereignisgesteuerte Funktionen wie Cloud Firestore-Ereignisse sind asynchron. Die Rückruffunktion sollte entweder ein null , ein Object oder ein Promise zurückgeben. Wenn Sie nichts zurückgeben, läuft die Funktion ab, signalisiert einen Fehler und wird erneut versucht. Siehe Synchronisierung, Asynchronisierung und Versprechen .

Emulieren Sie die Ausführung Ihrer Funktionen

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, auch weil dadurch das Risiko von Codierungsfehlern verringert wird, die in einer Produktionsumgebung möglicherweise Kosten verursachen könnten (z. B. eine Endlosschleife).

So emulieren Sie Ihre Funktionen:

  1. Führen Sie firebase emulators:start und überprüfen Sie die Ausgabe auf die URL der Emulator Suite-Benutzeroberfläche. Der Standardwert 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-Benutzeroberfläche zu öffnen.

  2. Überprüfen Sie die Ausgabe des Befehls firebase emulators:start auf die URL der HTTP-Funktion addMessage() . Es wird ähnlich wie http://localhost:5001/MY_PROJECT/us-central1/addMessage aussehen, außer dass:

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

  3. Fügen Sie die Abfragezeichenfolge ?text=uppercaseme am Ende der URL der Funktion hinzu. Dies 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 Benutzeroberfläche der Emulator Suite an:

    1. Auf der Registerkarte „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 der Registerkarte „Firestore“ sollten Sie ein Dokument sehen, das Ihre ursprüngliche Nachricht sowie die in Großbuchstaben geschriebene Version Ihrer Nachricht enthält (wenn sie ursprünglich „uppercaseme“ lautete, wird „UPPERCASEME“ angezeigt).

Stellen Sie Funktionen in einer Produktionsumgebung bereit

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

Um das Tutorial abzuschließen, stellen Sie 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-CLI die URL für alle HTTP-Funktionsendpunkte aus. In Ihrem Terminal sollten Sie eine Zeile wie die folgende sehen:

    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 darüber keine Sorgen machen müssen, sollten einige Produktions-HTTP-Funktionen einen Speicherort angeben, um die Netzwerklatenz zu minimieren.

    Wenn Zugriffsfehler wie „Der Zugriff auf das Projekt konnte nicht autorisiert werden“ auftreten, überprüfen Sie das Aliasing Ihres Projekts .

  2. Fügen Sie mithilfe der von der CLI ausgegebenen URL addMessage() einen Textabfrageparameter hinzu und öffnen Sie ihn 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 Datenbankspeicherort weiter, an dem die Textzeichenfolge gespeichert ist. Dieses Schreibereignis löst makeUppercase() aus, das eine Großbuchstabenversion der Zeichenfolge schreibt.

Nach der Bereitstellung und Ausführung von Funktionen können Sie Protokolle in der Google Cloud Console anzeigen. Wenn Sie Funktionen in der Entwicklung oder Produktion löschen müssen, verwenden Sie die Firebase-CLI.

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

Überprüfen Sie den vollständigen Beispielcode

Hier ist die fertige Datei functions/index.js , die die Funktionen addMessage() und makeUppercase() enthält. Mit diesen Funktionen können Sie einen Parameter an einen HTTP-Endpunkt übergeben, der einen Wert in Cloud Firestore schreibt und ihn dann umwandelt, indem alle Zeichen in der Zeichenfolge 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.

Um mehr über Cloud Functions zu erfahren, können Sie auch Folgendes tun: