Anwendung mit dem Cloud Firestore-Emulator verbinden

Bevor Sie Ihre App mit dem Cloud Firestore-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 Firebase-Projekten und Demoprojekten.

Projekttyp Funktionen Mit Emulatoren verwenden
Real

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

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 alle 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. Der Zugriff auf diese Projekte erfolgt normalerweise über Codelabs oder andere Anleitungen.

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 erstellen zu müssen
  • Höhere Sicherheit, da bei versehentlichem Aufruf nicht emulierter (Produktions-)Ressourcen durch Ihren Code keine Daten geändert werden und es keine Nutzung und Abrechnung gibt
  • 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

Beim Starten erstellt der Cloud Firestore-Emulator eine Standarddatenbank und eine benannte Datenbank für jede firestore-Konfiguration in Ihrer firebase.json-Datei.

Benannte Datenbanken werden auch implizit als Reaktion auf SDK- oder REST API-Aufrufe an den Emulator erstellt, die auf eine bestimmte Datenbank verweisen. Solche implizit erstellten Datenbanken arbeiten mit offenen Regeln.

Wenn Sie interaktiv mit Ihren Standarddatenbanken und benannten Datenbanken arbeiten möchten, aktualisieren Sie in der Adressleiste des Browsers die URL, um entweder die Standarddatenbank oder eine benannte Datenbank auszuwählen.Emulator Suite UI

  • Wenn Sie beispielsweise die Daten in Ihrer Standardinstanz durchsuchen möchten, aktualisieren Sie die URL auf localhost:4000/firestore/default/data.
  • Wenn Sie eine Instanz mit dem Namen ecommerce aufrufen möchten, aktualisieren Sie auf localhost:4000/firestore/ecommerce/data.

Android-, Apple-Plattformen und Web-SDKs

So richten Sie Ihre In-App-Konfiguration oder Testklassen ein, damit sie mit Cloud Firestore interagieren: In den folgenden Beispielen stellt der App-Code eine Verbindung zur Standardprojektdatenbank her. Beispiele für zusätzliche Cloud Firestore-Datenbanken, die über die Standarddatenbank hinausgehen, finden Sie im Leitfaden für mehrere Datenbanken.

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 firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
EmulatorSuite.kt
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
EmulatorSuite.java
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
fs_emulator_connect.js

Web

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}
emulator-suite.js

Für den Test von Cloud Functions, die durch Firestore-Ereignisse ausgelöst werden, ist keine zusätzliche Einrichtung erforderlich. Wenn die Firestore- und Cloud Functions-Emulatoren gleichzeitig ausgeführt werden, arbeiten sie automatisch zusammen.

Admin SDK Sek.

Die Firebase Admin SDK stellen automatisch eine Verbindung zum Cloud Firestore-Emulator her, wenn die Umgebungsvariable FIRESTORE_EMULATOR_HOST festgelegt ist:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Wenn Ihr Code im Cloud Functions-Emulator ausgeführt wird, werden Ihre Projekt-ID und andere Konfigurationseinstellungen beim Aufrufen von initializeApp automatisch festgelegt.

Wenn Ihr Admin SDK-Code eine Verbindung zu einem freigegebenen Emulator herstellen soll, der in einer anderen Umgebung ausgeführt wird, müssen Sie dieselbe Projekt-ID angeben, die Sie mit der Firebase CLI festgelegt haben. Sie können eine Projekt-ID direkt an initializeApp übergeben oder die Umgebungsvariable GCLOUD_PROJECT festlegen.

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
Umgebungsvariable
export GCLOUD_PROJECT="your-project-id"

Datenbank zwischen Tests löschen

Firestore für die Produktion bietet keine Plattform-SDK-Methode zum Leeren der Datenbank. Der Firestore-Emulator stellt Ihnen jedoch speziell für diesen Zweck einen REST-Endpunkt bereit, der über einen Einrichtungs-/TearDown-Schritt eines Test-Frameworks, aus einer Testklasse oder aus der Shell (z. B. mit curl) aufgerufen werden kann, bevor ein Test gestartet wird. Sie können diesen Ansatz als Alternative verwenden, um den Emulatorprozess einfach zu beenden.

Führen Sie in einer geeigneten Methode einen HTTP-DELETE-Vorgang aus und geben Sie Ihre Firebase-Projekt-ID, z. B. firestore-emulator-example, an den folgenden Endpunkt weiter:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Natürlich sollte Ihr Code auf eine REST-Bestätigung warten, dass die Flush-Aktion abgeschlossen oder fehlgeschlagen ist.

Sie können diesen Vorgang über die Shell ausführen:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Nachdem Sie einen solchen Schritt implementiert haben, können Sie Ihre Tests sequenzieren und Ihre Funktionen mit der Gewissheit auslösen, dass alte Daten zwischen den Ausführungen gelöscht werden und Sie eine neue Baseline-Testkonfiguration verwenden.

Daten importieren und exportieren

Mit den Datenbank- und Cloud Storage for Firebase-Emulatoren können Sie Daten aus einer laufenden Emulatorinstanz exportieren. Legen Sie einen Datenbestand als Referenz für Ihre Unit-Tests oder Continuous-Integration-Workflows fest und exportieren Sie ihn, um ihn für das Team freizugeben.

firebase emulators:export ./dir

Importieren Sie bei Tests beim Starten des Emulators die Baseline-Daten.

firebase emulators:start --import=./dir

Sie können den Emulator anweisen, Daten beim Herunterfahren zu exportieren. Dazu geben Sie entweder einen Exportpfad an oder verwenden einfach den Pfad, der an das Flag --import übergeben wird.

firebase emulators:start --import=./dir --export-on-exit

Diese Datenimport- und -exportoptionen funktionieren auch mit dem Befehl firebase emulators:exec. Weitere Informationen finden Sie in der Befehlsreferenz für den Emulator.

Aktivität zu Sicherheitsregeln visualisieren

Während Sie die Prototyp- und Testschleifen durcharbeiten, können Sie die Visualisierungstools und Berichte des Local Emulator Suite verwenden.

Anfragenmonitor verwenden

Mit dem Cloud Firestore-Emulator können Sie Clientanfragen in der Emulator Suite UI visualisieren, einschließlich des Bewertungs-Tracings für Firebase Security Rules.

Öffnen Sie den Tab Firestore > Anfragen, um die detaillierte Bewertungssequenz für jede Anfrage aufzurufen.

Firestore-Emulator-Anfragen-Monitor, der Sicherheitsregelbewertungen zeigt

Berichte zur Regelbewertung visualisieren

Wenn Sie Ihrem Prototyp Sicherheitsregeln hinzufügen, können Sie sie mit den Local Emulator Suite-Debug-Tools beheben.

Nachdem Sie eine Reihe von Tests ausgeführt haben, können Sie auf Berichte zur Testabdeckung zugreifen, die Aufschluss darüber geben, wie die einzelnen Sicherheitsregeln bewertet wurden.

Um die Berichte abzurufen, fragen Sie einen bereitgestellten Endpunkt im Emulator ab, während er ausgeführt wird. Verwenden Sie für eine browserfreundliche Version die folgende URL:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

Dadurch werden Ihre Regeln in Ausdrücke und Teilausdrücke aufgeteilt. Bewegen Sie die Maus auf einen Ausdruck oder Teilausdruck, um weitere Informationen zu erhalten, einschließlich der Anzahl der Bewertungen und der zurückgegebenen Werte. Fügen Sie für die JSON-Rohversion dieser Daten die folgende URL in Ihre Abfrage ein:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

In der HTML-Version des Berichts werden hier Bewertungen hervorgehoben, bei denen Fehler mit undefinierten und Nullwerten auftreten:

Unterschiede zwischen dem Cloud Firestore-Emulator und der Produktion

Der Cloud Firestore-Emulator versucht, das Verhalten des Produktionsdienstes mit einigen bemerkenswerten Einschränkungen originalgetreu nachzubilden.

Unterstützung mehrerer Datenbanken für Cloud Firestore

Derzeit unterstützt die Emulator Suite UI das interaktive Erstellen, Bearbeiten, Löschen, Anfragenmonitoring und Sicherheitsvisualisierung für eine Standarddatenbank, jedoch keine zusätzlichen benannten Datenbanken.

Der Emulator selbst erstellt jedoch eine benannte Datenbank basierend auf der Konfiguration in Ihrer firebase.json-Datei und implizit als Reaktion auf SDK- oder REST API-Aufrufe.

Transaktionen

Der Emulator implementiert derzeit nicht das gesamte Transaktionsverhalten, das in der Produktion zu sehen ist. Wenn Sie Funktionen testen, die mehrere gleichzeitige Schreibvorgänge in ein Dokument umfassen, dauert es möglicherweise etwas länger, bis der Emulator Schreibanfragen abschließt. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis die Sperre aufgehoben wird. Passen Sie bei Bedarf die Zeitlimits für Tests entsprechend an.

Indexe

Der Emulator überwacht keine zusammengesetzten Indexe und führt stattdessen jede gültige Abfrage aus. Testen Sie Ihre App an einer echten Cloud Firestore-Instanz, um festzustellen, welche Indexe Sie benötigen.

Limits

Im Emulator werden nicht alle in der Produktion erzwungenen Limits erzwungen. Beispielsweise kann der Emulator Transaktionen zulassen, die vom Produktionsdienst als zu groß abgelehnt würden. Machen Sie sich mit den dokumentierten Limits vertraut und entwerfen Sie Ihre App so, dass sie diese proaktiv vermeidet.

Und jetzt?