Anwendung mit dem Cloud Functions-Emulator verbinden

Bevor Sie Ihre App mit dem Cloud Functions-Emulator verbinden, sollten Sie sich mit dem Firebase Local Emulator Suite-Workflow vertraut machen und Local Emulator Suite installieren und konfigurieren sowie die CLI-Befehle prüfen.

Firebase-Projekt auswählen

Die Firebase Local Emulator Suite emuliert Produkte für ein einzelnes Firebase-Projekt.

Wenn Sie das zu verwendende Projekt auswählen möchten, führen Sie vor dem Starten der Emulatoren in der Befehlszeile firebase use in Ihrem Arbeitsverzeichnis aus. Alternativ können Sie das Flag --project an jeden Emulatorbefehl übergeben.

Local Emulator Suite unterstützt die Emulation von echten und Demo-Firebase-Projekten.

Projekttyp Funktionen Mit Emulatoren verwenden
Real

Ein echtes Firebase-Projekt ist ein Projekt, das Sie erstellt und konfiguriert haben, höchstwahrscheinlich über die Firebase Console.

Echte Projekte haben Liveressourcen wie Datenbankinstanzen, Speicher-Buckets, Funktionen oder andere Ressourcen, die Sie für dieses Firebase-Projekt eingerichtet haben.

Wenn Sie mit echten Firebase-Projekten arbeiten, können Sie Emulatoren für eines oder alle unterstützten Produkte ausführen.

Bei Produkten, die Sie nicht emulieren, interagieren Ihre Apps und Ihr Code mit der Live-Ressource (Datenbankinstanz, Speicher-Bucket, Funktion usw.).

Demo

Ein Demo-Firebase-Projekt hat keine echte Firebase-Konfiguration und keine Liveressourcen. Normalerweise wird über Codelabs oder andere Tutorials auf diese Projekte zugegriffen.

Projekt-IDs für Demoprojekte haben das Präfix demo-.

Wenn Sie mit Demo-Firebase-Projekten arbeiten, interagieren Ihre Apps und Ihr Code nur mit Emulatoren. Wenn Ihre App versucht, mit einer Ressource zu interagieren, für die kein Emulator ausgeführt wird, schlägt der Code fehl.

Wir empfehlen, nach Möglichkeit Demoprojekte zu verwenden. Die wichtigsten Vorteile:

  • Einfachere Einrichtung, da Sie die Emulatoren ausführen können, ohne ein Firebase-Projekt zu erstellen
  • Höhere Sicherheit, da bei versehentlichem Aufruf nicht emulierter (Produktions-)Ressourcen durch Ihren Code keine Daten geändert werden und keine Nutzung und Abrechnung erfolgt
  • Bessere Offlineunterstützung, da kein Zugriff auf das Internet erforderlich ist, um die SDK-Konfiguration herunterzuladen.

App für die Kommunikation mit den Emulatoren instrumentieren

App für aufrufbare Funktionen instrumentieren

Wenn Ihre Prototyp- und Testaktivitäten aufrufbare Backend-Funktionen umfassen, konfigurieren Sie die Interaktion mit dem Cloud Functions for Firebase-Emulator so:

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
MainActivity.kt
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFunctions functions = FirebaseFunctions.getInstance();
functions.useEmulator("10.0.2.2", 5001);
MainActivity.java
Swift
Functions.functions().useFunctionsEmulator(origin: "http://127.0.0.1:5001")
ViewController.swift

Web

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);
fb_functions_emulator_connect.js

Web

firebase.functions().useEmulator("127.0.0.1", 5001);
emulator-suite.js

App für die Emulation von HTTPS-Funktionen instrumentieren

Jede HTTPS-Funktion in Ihrem Code wird vom lokalen Emulator mit dem folgenden URL-Format bereitgestellt:

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

Eine einfache helloWorld-Funktion mit dem Standardhostport und der Standardregion wird beispielsweise unter folgender Adresse bereitgestellt:

https://localhost:5001/$PROJECT/us-central1/helloWorld

App für die Emulation von Funktionen der Aufgabenwarteschlange instrumentieren

Der Emulator richtet automatisch emulierte Aufgabenwarteschlangen basierend auf Triggerdefinitionen ein. Das Admin SDK leitet anstehende Anfragen an den Emulator weiter, wenn es erkennt, dass er über die Umgebungsvariable CLOUD_TASKS_EMULATOR_HOST ausgeführt wird.

Das in der Produktion verwendete Dispatchsystem ist komplexer als das im Emulator implementierte. Daher sollte nicht davon ausgegangen werden, dass das emulierte Verhalten Produktionsumgebungen genau widerspiegelt. Die Parameter im Emulator legen eine Obergrenze für die Rate fest, mit der Aufgaben gesendet und noch einmal versucht werden.

App für die Emulation von im Hintergrund ausgelösten Funktionen instrumentieren

Der Cloud Functions-Emulator unterstützt Hintergrundfunktionen aus den folgenden Quellen:

  • Realtime Database-Emulator
  • Cloud Firestore-Emulator
  • Authentication-Emulator
  • Pub/Sub-Emulator
  • Firebase-Benachrichtigungsemulator

Wenn Sie Hintergrundereignisse auslösen möchten, ändern Sie die Back-End-Ressourcen mithilfe von Emulator Suite UI oder verbinden Sie Ihre App oder Ihren Testcode über das SDK für Ihre Plattform mit den Emulatoren.

Handler für benutzerdefinierte Ereignisse testen, die von Erweiterungen gesendet werden

Bei Funktionen, die Sie zum Verarbeiten benutzerdefinierter Firebase Extensions-Ereignisse mit Cloud Functions v2 implementieren, wird der Cloud Functions-Emulator mit dem Eventarc-Emulator gekoppelt, um Eventarc-Trigger zu unterstützen.

Wenn Sie benutzerdefinierte Event-Handler für Erweiterungen testen möchten, die Ereignisse senden, müssen Sie die Cloud Functions- und Eventarc-Emulatoren installieren.

Die Cloud Functions-Laufzeit legt die Umgebungsvariable EVENTARC_EMULATOR im aktuellen Prozess auf localhost:9299 fest, wenn der Eventarc-Emulator ausgeführt wird. Die Firebase Admin SDK stellen automatisch eine Verbindung zum Eventarc-Emulator her, wenn die Umgebungsvariable EVENTARC_EMULATOR festgelegt ist. Sie können den Standardport wie unter Local Emulator Suite konfigurieren beschrieben ändern.

Wenn die Umgebungsvariablen richtig konfiguriert sind, sendet Firebase Admin SDK automatisch Ereignisse an den Eventarc-Emulator. Der Eventarc-Emulator führt dann einen Callback an den Cloud Functions-Emulator aus, um alle registrierten Handler auszulösen.

Details zur Ausführung des Handlers finden Sie in den Functions-Logs im Emulator Suite UI.

Lokale Testumgebung konfigurieren

Wenn Ihre Funktionen auf einer dotenv-basierten Umgebungskonfiguration basieren, können Sie dieses Verhalten in Ihrer lokalen Testumgebung emulieren.

Wenn Sie einen lokalen Cloud Functions-Emulator verwenden, können Sie Umgebungsvariablen für Ihr Projekt überschreiben, indem Sie eine .env.local-Datei einrichten. Der Inhalt von .env.local hat Vorrang vor .env und der projektspezifischen .env-Datei.

Ein Projekt könnte beispielsweise die folgenden drei Dateien mit leicht unterschiedlichen Werten für die Entwicklung und lokale Tests enthalten:

.env .env.dev .env.local
PLANET=Earth

AUDIENCE=Mensch

AUDIENCE=Dev Humans AUDIENCE=Local Humans

Wenn der Emulator im lokalen Kontext gestartet wird, lädt er die Umgebungsvariablen wie hier gezeigt:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Secrets und Anmeldedaten im Cloud Functions-Emulator

Der Cloud Functions-Emulator unterstützt die Verwendung von Secrets zum Speichern und Abrufen vertraulicher Konfigurationsinformationen. Standardmäßig versucht der Emulator, mit den Standardanmeldedaten für Anwendungen auf Ihre Produktionssecrets zuzugreifen. In bestimmten Situationen, z. B. in CI-Umgebungen, kann der Emulator aufgrund von Berechtigungseinschränkungen nicht auf geheime Werte zugreifen.

Ähnlich wie bei der Cloud Functions-Emulatorunterstützung für Umgebungsvariablen können Sie Geheimdatenwerte überschreiben, indem Sie eine .secret.local-Datei einrichten. So können Sie Ihre Funktionen ganz einfach lokal testen, insbesondere wenn Sie keinen Zugriff auf den geheimen Wert haben.

Welche anderen Tools zum Testen von Cloud Functions gibt es?

Der Cloud Functions-Emulator wird durch andere Prototyp- und Testtools ergänzt:

  • Die Cloud Functions-Shell, die interaktives, iteratives Prototyping und die Entwicklung von Funktionen ermöglicht. Die Shell verwendet den Cloud Functions-Emulator mit einer REPL-Oberfläche für die Entwicklung. Es gibt keine Integration mit den Cloud Firestore- oder Realtime Database-Emulatoren. Mit der Shell können Sie Daten simulieren und Funktionsaufrufe ausführen, um die Interaktion mit Produkten zu simulieren, die von der Local Emulator Suite derzeit nicht unterstützt werden: Analytics, Remote Config und Crashlytics.
  • Das Firebase Test SDK for Cloud Functions, ein Node.js-Mocha-Framework für die Funktionsentwicklung. Das Cloud Functions Test SDK bietet also eine Automatisierung über die Cloud Functions-Shell.

Weitere Informationen zur Cloud Functions-Shell und zum Cloud Functions Test SDK finden Sie unter Funktionen interaktiv testen und Einen Cloud Functions-Code mit dem Test SDK testen.

Unterschiede zwischen dem Cloud Functions-Emulator und der Produktion

Der Cloud Functions-Emulator entspricht für die meisten Anwendungsfälle in etwa der Produktionsumgebung. Wir haben viel Arbeit darauf verwendet, dass alles in der Node-Laufzeit so nah wie möglich an der Produktion ist. Der Emulator ahmt jedoch nicht die gesamte containerisierte Produktionsumgebung nach.Ihr Funktionscode wird zwar realistisch ausgeführt, andere Aspekte Ihrer Umgebung (z. B. lokale Dateien, Verhalten nach Funktionsabstürzen) unterscheiden sich jedoch.

Cloud IAM

Die Firebase Emulator Suite versucht nicht, IAM-bezogenes Laufverhalten zu replizieren oder zu berücksichtigen. Emulatoren halten sich an die bereitgestellten Firebase-Sicherheitsregeln. In Situationen, in denen normalerweise IAM verwendet würde, z. B. zum Festlegen des Dienstkontos und damit der Berechtigungen für Cloud Functions, ist der Emulator jedoch nicht konfigurierbar und verwendet das global verfügbare Konto auf Ihrem Entwicklercomputer, ähnlich wie beim direkten Ausführen eines lokalen Scripts.

Arbeitsspeicher- und Prozessoreinschränkungen

Der Emulator erzwingt keine Speicher- oder Prozessorbeschränkungen für Ihre Funktionen. Der Emulator unterstützt jedoch das Ablaufen von Funktionen über das Laufzeitargument timeoutSeconds.

Die Ausführungszeit von Funktionen kann sich von der in der Produktion unterscheiden, wenn Funktionen im Emulator ausgeführt werden. Wir empfehlen, nach dem Entwerfen und Testen von Funktionen mit dem Emulator begrenzte Tests in der Produktion durchzuführen, um die Ausführungszeiten zu bestätigen.

Unterschiede zwischen lokalen und Produktionsumgebungen berücksichtigen

Da der Emulator auf Ihrem lokalen Computer ausgeführt wird, hängt er von Ihrer lokalen Umgebung für Anwendungen und integrierten Programmen und Dienstprogrammen ab.

Ihre lokale Umgebung für die Cloud Functions-Entwicklung kann sich von der Produktionsumgebung von Google unterscheiden:

  • Anwendungen, die Sie lokal installieren, um die Produktionsumgebung zu simulieren (z.B. ImageMagick aus dieser Anleitung), können sich im Verhalten von der Produktionsumgebung unterscheiden, insbesondere wenn Sie andere Versionen benötigen oder in einer anderen Umgebung als Linux entwickeln. Sie können neben der Bereitstellung Ihrer Funktion auch eine eigene Binärkopie des fehlenden Programms bereitstellen.

  • Ebenso können integrierte Dienstprogramme (z.B. Shell-Befehle wie ls oder mkdir) von den Versionen abweichen, die in der Produktion verfügbar sind, insbesondere wenn Sie in einer anderen Umgebung als Linux (z.B. macOS) entwickeln. Sie können dieses Problem beheben, indem Sie nur für Node entwickelte Alternativen zu nativen Befehlen verwenden oder Linux-Binärdateien erstellen, die Sie mit Ihrer Bereitstellung bündeln.

Neuer Versuch

Der Cloud Functions-Emulator unterstützt keine Wiederholungsversuche bei Fehlern.

Und jetzt?