Anwendung mit dem Cloud Firestore-Emulator verbinden

Bevor du deine App mit dem Cloud Firestore-Emulator verbindest, prüfe, ob Sie verstehen den gesamten Firebase Local Emulator Suite-Workflow und Sie installieren und konfigurieren Local Emulator Suite und überprüfen Sie die zugehörigen CLI-Befehle.

Firebase-Projekt auswählen

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

Führen Sie vor dem Starten der Emulatoren in der Befehlszeile das Projekt aus, das verwendet werden soll firebase use in Ihrem Arbeitsverzeichnis. Oder Sie können das Flag --project für jeden Emulator .

Local Emulator Suite unterstützt die Emulation realer Firebase-Projekte und demo-Projekte erstellen.

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 Live-Ressourcen wie Datenbankinstanzen, Speicher Buckets, Funktionen oder einer anderen Ressource, die Sie für dieses Firebase eingerichtet haben Projekt arbeiten.

Bei der Arbeit mit echten Firebase-Projekten können Sie Emulatoren für beliebige oder alle unterstützten Produkte.

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

Demo

Ein Firebase-Demoprojekt hat keine echte Firebase-Konfiguration und keine Live-Ressourcen. 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:

  • Die Einrichtung ist einfacher, da Sie die Emulatoren ausführen können, ohne Firebase-Projekt
  • Erhöhte Sicherheit, da wenn Ihr Code versehentlich nicht emulierte (Produktions-)Ressourcen gibt es keine Möglichkeit einer Änderung der Daten, der Nutzung oder der Abrechnung.
  • Besserer Offline-Support, da keine Internetverbindung erforderlich ist, um laden Sie die SDK-Konfiguration herunter.

App instrumentieren, um mit den Emulatoren zu kommunizieren

Beim Start erstellt der Cloud Firestore-Emulator eine Standarddatenbank und einen benannten für jede firestore-Konfiguration in Ihrem firebase.json-Datei.

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

So arbeiten Sie mit Ihren Standarddatenbanken und benannten Datenbanken interaktiv im Emulator Suite UI, aktualisieren Sie in der Adressleiste des Browsers die URL, um die Standarddatenbank oder eine benannte Datenbank.

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

Android-, Apple-Plattformen und Web-SDKs

In-App-Konfiguration oder Testklassen für die Interaktion einrichten Cloud Firestore so. Beachten Sie, dass in den folgenden Beispielen App-Code stellt eine Verbindung zur Standardprojektdatenbank her. Für Beispiele mit zusätzlichen Cloud Firestore Datenbanken über die Standarddatenbank hinaus, siehe die 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

Zum Testen von Cloud Functions ist keine zusätzliche Einrichtung erforderlich durch Firestore-Ereignisse ausgelöst mit dem Emulator. Wenn sowohl der Firestore- als auch der Cloud Functions-Emulator arbeiten sie automatisch zusammen.

Admin SDK Sek.

Die Firebase Admin SDKs stellen automatisch eine Verbindung zu Cloud Firestore her Emulator, wenn die Umgebungsvariable FIRESTORE_EMULATOR_HOST festgelegt ist:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Wenn der Code im Cloud Functions-Emulator ausgeführt wird, ist Ihre Projekt-ID und andere Konfigurationen werden 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 GCLOUD_PROJECT.

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 aus einem Einrichtungs-/TearDown-Schritt eines Test-Frameworks, einer Testklasse oder aus der Shell (z. B. mit curl) aufgerufen werden kann, bevor ein Test gestartet wird. Sie können diesen Ansatz alternativ verwenden, um den Emulatorprozess einfach zu beenden.

Führen Sie in einer geeigneten Methode einen HTTP DELETE-Vorgang mit Ihrem Firebase-Projekt-ID, z. B. firestore-emulator-example, in Endpunkt:

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

Natürlich sollte Ihr Code auf eine REST-Bestätigung warten, ob der Leerungsvorgang abgeschlossen ist 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"

Nach der Implementierung eines solchen Schritts können Sie Ihre Tests sequenzieren und Funktionen mit der Gewissheit, dass alte Daten zwischen Ausführungen Sie eine neue Basistestkonfiguration verwenden.

Daten importieren und exportieren

Mit der Datenbank und den Cloud Storage for Firebase-Emulatoren können Sie Daten exportieren aus einer laufenden Emulator-Instanz. Definieren Sie einen Basisdatensatz für die Unittests oder Continuous-Integration-Workflows, die Sie dann zur gemeinsamen Nutzung exportieren innerhalb des Teams.

firebase emulators:export ./dir

Importieren Sie in Tests beim Start des Emulators die Referenzdaten.

firebase emulators:start --import=./dir

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

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

Diese Datenimport- und -exportoptionen funktionieren mit dem firebase emulators:exec-Befehl hinzu. Weitere Informationen finden Sie in der Referenz zu Emulatorbefehlen

Aktivitäten von Sicherheitsregeln visualisieren

Beim Durcharbeiten von Prototypen und Testschleifen können Sie Visualisierungstools verwenden und Berichte werden von Local Emulator Suite bereitgestellt.

Anfragenmonitor verwenden

Mit dem Emulator Cloud Firestore können Sie Clientanfragen in Emulator Suite UI, einschließlich Bewertungs-Tracing 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 diese mit Local Emulator Suite Debugging-Tools.

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

Hier werden in der HTML-Version des Berichts Bewertungen hervorgehoben, die nicht definierte Fehler und Fehler mit Nullwerten auslösen:

Unterschiede zwischen dem Cloud Firestore-Emulator und der Produktion

Der Cloud Firestore-Emulator versucht, das Verhalten realistisch zu reproduzieren. des Produktionsdienstes mit einigen nennenswerten Einschränkungen.

Unterstützung mehrerer Datenbanken für Cloud Firestore

Derzeit unterstützt die Emulator Suite UI das interaktive Erstellen, Bearbeiten und Löschung, Anforderungsmonitoring und Sicherheitsvisualisierung für eine Standarddatenbank, aber 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 in der Produktion gesehen werden. Wenn Sie Funktionen testen, die mehrere gleichzeitig in ein Dokument schreiben, kann der Emulator den Schreibvorgang lange dauern. -Anfragen. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis die Sperre aufgehoben wird. Passen Sie die Testzeitlimits bei Bedarf entsprechend an.

Indexe

Der Emulator verfolgt keine zusammengesetzten Indexe, sondern führt stattdessen gültige Abfrage. Teste deine App unbedingt mit einer echten Cloud Firestore Instanz, um zu bestimmen, welche Indexe Sie benötigen.

Limits

Der Emulator erzwingt nicht alle in der Produktion erzwungenen Limits. Beispiel: kann der Emulator Transaktionen zulassen, die vom Produktionsdiensts. Machen Sie sich mit den dokumentierten Limits vertraut und entwerfen Sie Ihre App so, dass sie diese proaktiv vermeidet.

Und jetzt?