Firebase is back at Google I/O on May 10! Register now

Legen Sie los: Schreiben, testen und implementieren Sie Ihre ersten Funktionen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Um mit Cloud Functions zu beginnen, versuchen Sie, dieses Tutorial durchzuarbeiten, das mit den erforderlichen Einrichtungsaufgaben beginnt und durch das Erstellen, Testen und Bereitstellen von zwei verwandten Funktionen führt:

  • addMessage() , das eine URL bereitstellt, die einen Textwert akzeptiert und in Cloud Firestore schreibt.
  • makeUppercase() , das beim Schreiben in Cloud Firestore ausgelöst wird und den Text in Großbuchstaben umwandelt.

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

In den folgenden Abschnitten dieses Lernprogramms werden die Schritte beschrieben, die zum Erstellen, Testen und Bereitstellen des Beispiels erforderlich sind. Wenn Sie den Code lieber einfach ausführen und untersuchen möchten, wechseln Sie zu Vollständigen Beispielcode überprüfen .

Erstellen Sie ein Firebase-Projekt

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

    • Geben Sie zum Hinzufügen von Firebase-Ressourcen zu einem vorhandenen Google Cloud-Projekt seinen Projektnamen ein oder wählen Sie ihn aus dem Dropdown-Menü aus.

    • Um ein neues Projekt anzulegen, geben Sie den gewünschten Projektnamen ein. Optional können Sie auch die unterhalb des Projektnamens angezeigte Projekt-ID bearbeiten.

  2. Wenn Sie dazu aufgefordert werden, lesen und akzeptieren Sie die Firebase-Nutzungsbedingungen .

  3. Klicken Sie auf Weiter .

  4. (Optional) Richten Sie Google Analytics für Ihr Projekt ein, damit Sie mit einem der folgenden Firebase-Produkte ein optimales Erlebnis haben:

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

    Wenn Sie ein neues Konto erstellen, wählen Sie Ihren Standort für Analytics-Berichte aus und akzeptieren Sie dann die Einstellungen für die Datenfreigabe und die 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. 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-Befehlszeilenschnittstelle, 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 über Ihre bevorzugte 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 Firebase SDK for Cloud Functions initialisieren, erstellen Sie ein leeres Projekt, das Abhängigkeiten und minimalen Beispielcode enthält, und Sie wählen entweder TypeScript oder JavaScript zum Erstellen von Funktionen aus. 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 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 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 Codebases 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 dies 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 während 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 Module Cloud Functions und Admin SDK 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');

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

Diese Zeilen laden die Module firebase-functions und firebase-admin 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 z. B. für FCM, Authentifizierung und Firebase Realtime Database, bietet es eine leistungsstarke Möglichkeit, Firebase mithilfe von Cloud Functions zu integrieren.

Die Firebase CLI installiert automatisch die Module Firebase und Firebase SDK for 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 Umgang mit Abhängigkeiten .

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 Request- und Response- Objekten im ExpressJS-Stil, die an den onRequest() -Callback ü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 zurückstellen. 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 zu überwachende Dokument. Aus Performance-Gründen sollten Sie so spezifisch 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() Callback immer dann aus, wenn neue Nachrichten hinzugefügt werden.

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

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. Lokales Testen während der Entwicklung wird dringend empfohlen, zum Teil, weil es das Risiko von Codierungsfehlern verringert, 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 und überprüfen Sie die Ausgabe auf die URL der Benutzeroberfläche der Emulator Suite. Es ist standardmäßig localhost:4000 , kann aber auf einem anderen Port auf Ihrem Computer gehostet werden. Geben Sie diese URL in Ihren Browser ein, um die Benutzeroberfläche der Emulator Suite zu öffnen.

  2. Überprüfen Sie die Ausgabe des Befehls firebase emulators:start auf die URL der HTTP-Funktion addMessage() . Es sieht ähnlich aus wie http://localhost:5001/MY_PROJECT/us-central1/addMessage , 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 in etwa so aussehen: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Optional können Sie die Nachricht "Großbuchstaben" in eine benutzerdefinierte Nachricht ändern.

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

  5. Sehen Sie sich die Auswirkungen der Funktionen in der Benutzeroberfläche der Emulator Suite an:

    1. Auf der Registerkarte Protokolle sollten Sie neue Protokolle sehen, die darauf hinweisen, dass die Funktionen addMessage() und makeUppercase() ausgeführt wurden:

      i-Funktionen: Ausführung von "addMessage" beginnen

      i-Funktionen: Ausführung von "makeUppercase" beginnen

    2. Auf der Registerkarte Firestore sollten Sie ein Dokument sehen, das Ihre ursprüngliche Nachricht sowie die Version Ihrer Nachricht in Großbuchstaben enthält (wenn es ursprünglich „uppercaseme“ war, sehen Sie „UPPERCASEME“).

Stellen Sie Funktionen in einer Produktionsumgebung bereit

Sobald Ihre Funktionen wie gewünscht im Emulator funktionieren, können Sie damit fortfahren, sie in der Produktionsumgebung bereitzustellen, zu testen und auszuführen. Beachten Sie, dass für die Bereitstellung in der empfohlenen Node.js 14-Laufzeitumgebung Ihr Projekt den Blaze-Preisplan haben muss . Siehe Cloud Functions-Preise .

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. Obwohl Sie sich jetzt 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 das Projekt konnte nicht autorisiert werden" auftreten, versuchen Sie, Ihr Projekt-Aliasing zu überprüfen.

  2. Fügen Sie mithilfe der URL-Ausgabe addMessage() der CLI 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 des Strings schreibt.

Nach dem Bereitstellen und Ausführen 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 minimale und maximale Anzahl der auszuführenden Instanzen festlegen. Weitere Informationen zu diesen Laufzeitoptionen finden Sie unter Steuerung des Skalierungsverhaltens .

Überprüfen Sie den vollständigen Beispielcode

Hier ist die 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 umwandelt, indem er alle Zeichen in der Zeichenfolge in Großbuchstaben umwandelt.

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

// 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 finden Sie weitere Informationen zu allgemeinen Konzepten für Cloud Functions sowie Leitfäden zum Schreiben von Funktionen zur Verarbeitung der von Cloud Functions unterstützten Ereignistypen.

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

Videoanleitung

Sie können mehr über Cloud-Funktionen erfahren, indem Sie sich Video-Tutorials ansehen. In diesem Video finden Sie detaillierte Anleitungen zu den ersten Schritten mit Cloud Functions, einschließlich der Node.js- und CLI-Einrichtung.