Anwendung mit dem Cloud Firestore-Emulator verbinden

Bevor Sie Ihre App mit dem Cloud Firestore Emulator verbinden, sollten Sie sich mit dem allgemeinen Firebase Local Emulator Suite Workflow vertraut machen, die Local Emulator Suite installieren und konfigurieren und 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 CLI im Arbeitsverzeichnis firebase use aus. Alternativ können Sie das Flag an jeden Emulator Befehl übergeben.--project

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

Wir empfehlen, Demoprojekte nach Möglichkeit zu verwenden. Dies sind 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 von nicht emulierten (Produktions-)Ressourcen durch Ihren Code keine Datenänderungen, Nutzung und Abrechnung erfolgen
• Bessere Offlineunterstützung, da Sie nicht auf das Internet zugreifen müssen, um Ihre 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. Für diese implizit erstellten Datenbanken gelten offene Regeln.

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

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

Android-, Apple-Plattformen und Web-SDKs

Richten Sie Ihre In-App-Konfiguration oder Testklassen so ein, dass sie mit Cloud Firestore interagieren. In den folgenden Beispielen stellt der App-Code eine Verbindung zur Standarddatenbank des Projekts her. Beispiele für zusätzliche Cloud Firestore Datenbanken über die Standarddatenbank hinaus finden Sie im Leitfaden für mehrere Datenbanken.

// 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

// 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

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

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

// 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 das Testen von Cloud Functions die durch Firestore-Ereignisse ausgelöst werden ist keine zusätzliche Einrichtung erforderlich. Wenn der Firestore- und der Cloud Functions-Emulator ausgeführt werden, arbeiten sie automatisch zusammen.

Admin SDKs

Die Firebase Admin SDKs stellen automatisch eine Verbindung zum Cloud Firestore Emulator her, wenn die FIRESTORE_EMULATOR_HOST Umgebungsvariable 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 Konfigurationen automatisch festgelegt, wenn Sie initializeApp aufrufen.

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 Umgebungsvariable festlegen.

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

Cloud Firestore REST API

Der Cloud Firestore-Emulator bietet einen REST-Endpunkt für die Interaktion mit Ihrer Datenbank. Alle REST API-Aufrufe sollten an den http://localhost:8080/v1 Endpunkt gesendet werden.

Der vollständige Pfad für einen REST-Aufruf folgt diesem Muster:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

Wenn Sie beispielsweise alle Dokumente in der users Sammlung für das Projekt my-project-id auflisten möchten, können Sie curl verwenden:

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

Datenbank zwischen Tests löschen

Production Firestore bietet keine Plattform-SDK-Methode zum Leeren der Datenbank. Der Firestore-Emulator bietet jedoch einen REST-Endpunkt speziell für diesen Zweck, der vor dem Starten eines Tests über einen Schritt zum Einrichten/Beenden des Testframeworks, über eine Testklasse oder über die Shell (z. B. mit curl) aufgerufen werden kann. Sie können diesen Ansatz als Alternative zum einfachen Herunterfahren des Emulatorprozesses verwenden.

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

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

Ihr Code sollte natürlich auf eine REST-Bestätigung warten, dass das Leeren 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"

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 Testkonfiguration verwenden.

Daten importieren und exportieren

Mit den Datenbank- und Cloud Storage for Firebase Emulatoren können Sie Daten aus einer ausgeführten Emulatorinstanz exportieren. Definieren Sie eine Baseline-Menge von Daten, die in Ihren Unit-Tests oder Continuous Integration-Workflows verwendet werden sollen, und exportieren Sie sie dann, damit sie für das Team freigegeben werden können.

firebase emulators:export ./dir

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

firebase emulators:start --import=./dir

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

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

Diese Optionen für den Datenimport und -export funktionieren auch mit dem firebase emulators:exec Befehl. Weitere Informationen finden Sie in der Referenz zu Emulatorbefehlen.

Aktivität der Sicherheitsregeln visualisieren

Während Sie Prototypen erstellen und Tests durchführen, können Sie Visualisierungstools und Berichte verwenden, die von der Local Emulator Suite bereitgestellt werden.

Anfragenmonitor verwenden

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

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

Berichte zu Evaluierungen von Regeln visualisieren

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

Nachdem Sie eine Reihe von Tests ausgeführt haben, können Sie auf Test abdeckungsberichte 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 Evaluierungen hervorgehoben, die Fehler mit undefinierten und Null-Werten auslösen:

Unterschiede zwischen dem Cloud Firestore Emulator und der Produktion

Der Cloud Firestore Emulator versucht, das Verhalten des Produktionsdienstes möglichst genau nachzubilden, es gibt jedoch einige bemerkenswerte Einschränkungen.

Unterstützung mehrerer Datenbanken für Cloud Firestore

Derzeit unterstützt die Emulator Suite UI die interaktive Erstellung, Bearbeitung, Löschung, Anfragenüberwachung und Sicherheitsvisualisierung für eine Standarddatenbank, aber nicht für zusätzliche benannte 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 beobachten ist. Wenn Sie Funktionen testen, die mehrere gleichzeitige Schreibvorgänge in ein Dokument umfassen, kann es lange dauern, bis der Emulator Schreib anfragen abschließt. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis Sperren freigegeben werden. Passen Sie die Testtimeouts bei Bedarf entsprechend an.

Indexe

Der Emulator verfolgt keine zusammengesetzten Indexe und führt stattdessen jede gültige Abfrage aus. Testen Sie Ihre App mit einer echten Cloud Firestore Instanz, um zu ermitteln, welche Indexe Sie benötigen.

Limits

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

Und jetzt?

• Eine Auswahl an Videos und detaillierten Beispielen finden Sie in der Playlist zum Training von Firebase Emulators.
• Weitere Informationen zu erweiterten Anwendungsfällen für das Testen von Sicherheitsregeln und das Firebase Test SDK finden Sie unter Sicherheitsregeln testen (Firestore).
• Da ausgelöste Funktionen eine typische Integration mit Cloud Firestore sind, finden Sie weitere Informationen zum Cloud Functions for Firebase Emulator unter Funktionen lokal ausführen.