Anwendung mit dem Cloud Firestore-Emulator verbinden

Bevor Sie Ihre Anwendung mit dem Cloud Firestore-Emulator verbinden, sollten Sie sich mit dem allgemeinen Firebase Local Emulator Suite-Workflow vertraut machen. Außerdem müssen Sie die Local Emulator Suite installieren und konfigurieren und sich die CLI-Befehle ansehen.

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.

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änderung, Nutzung und Abrechnung möglich ist.
• Bessere Offline-Unterstützung, da kein Internetzugriff erforderlich ist, um Ihre SDK-Konfiguration herunterzuladen.

Anwendung für die Kommunikation mit den Emulatoren instrumentieren

Beim Start 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 Antwort 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 Standard- und benannten Datenbanken in der Emulator Suite UI 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 auf localhost:4000/firestore/ecommerce/data.

Emulator in einer bestimmten Version starten

Der Emulator wird in der Version gestartet, die im Abschnitt firestore.edition Ihrer firebase.json-Datei angegeben ist. Sie können auch im Abschnitt emulators.firestore.edition Ihrer firebase.json eine Version angeben. Gültige Werte für die Version sind standard und enterprise. Wenn Sie edition in beiden Konfigurationen angeben, hat emulators.firestore.edition Vorrang.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

Android-, Apple- 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 Anwendungscode eine Verbindung zur Standardprojektdatenbank her. Beispiele mit zusätzlichen Cloud Firestore-Datenbanken neben der Standarddatenbank 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

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

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

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

Admin SDK Sek.

Die Firebase Admin SDKs 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 Konfigurationen automatisch festgelegt, wenn Sie initializeApp aufrufen.

Wenn Sie Ihren Admin SDK-Code mit einem freigegebenen Emulator verbinden möchten, 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.

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 Endpunkt http://localhost:8080/v1 erfolgen.

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

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

Wenn Sie beispielsweise alle Dokumente in der Sammlung users 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

In der Produktionsversion von Firestore gibt es keine Plattform-SDK-Methode zum Leeren der Datenbank. Der Firestore-Emulator bietet jedoch einen REST-Endpunkt speziell für diesen Zweck, der vor dem Start eines Tests über einen Setup-/TearDown-Schritt des Test-Frameworks, ü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, z. B. firestore-emulator-example, für den folgenden Endpunkt an:

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

Natürlich sollte Ihr Code auf die REST-Bestätigung warten, dass die Leerung abgeschlossen wurde 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"

Wenn Sie einen solchen Schritt implementiert haben, können Sie Ihre Tests sequenzieren und Ihre Funktionen auslösen. Sie können sich darauf verlassen, 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. Definieren Sie einen Baseline-Datensatz, der in Ihren Unit-Tests oder Continuous Integration-Workflows verwendet werden soll, und exportieren Sie ihn, um ihn im Team freizugeben.

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, Daten beim Herunterfahren zu exportieren. Geben Sie dazu entweder einen Exportpfad an oder verwenden Sie einfach den Pfad, der an das Flag --import übergeben wurde.

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

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

Aktivitäten im Zusammenhang mit Sicherheitsregeln visualisieren

Während Sie Prototypen erstellen und testen, können Sie die Visualisierungstools und Berichte der 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-Tracing für Firebase Security Rules.

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

Berichte zu Regelauswertungen visualisieren

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

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 Auswertungen hervorgehoben, die Fehler vom Typ „undefined“ und „null“ ausgeben:

Unterschiede zwischen dem Cloud Firestore-Emulator und der Produktion

Der Cloud Firestore-Emulator versucht, das Verhalten des Produktionsdienstes mit einigen bemerkenswerten Einschränkungen genau zu replizieren.

Unterstützung mehrerer Datenbanken für Cloud Firestore

Derzeit unterstützt die Emulator Suite UI das interaktive Erstellen, Bearbeiten, Löschen, Monitoring von Anfragen und die 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 Antwort 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, kann es sein, dass der Emulator Schreibanfragen nur langsam abschließt. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis Sperren aufgehoben werden. Passen Sie die Testzeitlimits bei Bedarf entsprechend an.

Indexe

Der Emulator verfolgt keine zusammengesetzten Indexe, sondern führt jede gültige Abfrage aus. Testen Sie Ihre Anwendung mit einer echten Cloud Firestore-Instanz, um festzustellen, welche Indexe Sie benötigen.

Limits

Der Emulator erzwingt nicht alle Limits, die in der Produktion erzwungen werden. Der Emulator kann beispielsweise Transaktionen zulassen, die vom Produktionsdienst als zu groß abgelehnt werden würden. Machen Sie sich mit den dokumentierten Limits vertraut und entwerfen Sie Ihre Anwendung so, dass sie proaktiv vermieden werden.

Nächste Schritte

• Eine Auswahl an Videos und detaillierte Anleitungen finden Sie in der Playlist mit Schulungen zu Firebase-Emulatoren.
• Erweiterte Anwendungsfälle mit Tests von Sicherheitsregeln und dem Firebase Test SDK untersuchen: Sicherheitsregeln testen (Firestore)
• Da ausgelöste Funktionen eine typische Integration in Cloud Firestore sind, finden Sie weitere Informationen zum Cloud Functions for Firebase-Emulator unter Funktionen lokal ausführen.