Firestore-Emulator lokal verwenden

Die Google Cloud CLI stellt einen lokalen Emulator im Speicher für Firestore zur Verfügung. Mit ihm können Sie Ihre Anwendung testen. Sie können den Emulator mit allen Firestore-Clientbibliotheken verwenden. Sie sollten den Emulator nur für lokale Tests verwenden.

Verwenden Sie den Emulator nicht für Produktionsbereitstellungen. Da der Emulator die Daten nur zwischenspeichert, behält er keine Daten über die verschiedenen Testläufe bei.

Emulator installieren

So installieren Sie den Firestore-Emulator: Installieren und aktualisieren Sie die gcloud CLI:

  1. Installieren Sie das gcloud-CLI.

  2. Aktualisieren Sie Ihre gcloud CLI-Installation, um die neuesten Funktionen zu erhalten:

    gcloud components update

Emulator starten

  1. Verwenden Sie den folgenden Befehl, um den Emulator zu starten:

    gcloud emulators firestore start

    Der Emulator gibt den Host und die Portnummer aus, wenn er ausgeführt wird.

    Standardmäßig versucht der Emulator, 127.0.0.1:8080 zu verwenden. Binden Sie den Emulator mit dem optionalen Flag --host-port an einen bestimmten Host und Port. Ersetzen Sie dabei HOST und PORT:

    gcloud emulators firestore start --host-port=HOST:PORT

  2. Drücken Sie Control + C, um den Emulator zu beenden. Der Emulator kann auch mit einer POST-Anfrage an /shutdown beendet werden. Beispiel:

    curl -d '' HOST:PORT/shutdown

Emulator in einer bestimmten Version starten

Verwenden Sie das optionale --edition Flag, um den Emulator in der Enterprise-Version zu starten. Gültige Werte sind standard und enterprise. Standardmäßig wird der Emulator in der Standard-Version gestartet, wenn das Flag nicht angegeben ist.

    gcloud emulators firestore start --edition=enterprise

Verbindung zum Emulator herstellen

Wie Sie eine Verbindung zum Emulator herstellen, hängt vom Typ der Clientbibliothek, der Server-Clientbibliothek oder des mobilen/Web-SDK ab.

Server-Clientbibliotheken

Wenn Sie eine Verbindung zu einer Firestore-Server-Clientbibliothek (C#, Go, Java, Node.js, PHP, Python und Ruby) herstellen möchten, legen Sie die Umgebungsvariable FIRESTORE_EMULATOR_HOST fest. Wenn diese Umgebungsvariable festgelegt ist, stellen die Server-Clientbibliotheken automatisch eine Verbindung zum Emulator her.

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

Android-, Apple-Plattformen- und Web-SDKs

In den folgenden Beispielen wird gezeigt, wie Sie die Android-, Apple-Plattformen- und Web-SDKs mit dem Firestore-Emulator verbinden:

Android
// 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 version 9

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 version 8

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

Der Emulator für Firestore im nativen Modus löscht die Datenbankinhalte beim Herunterfahren. Da der Offlinecache des Firestore SDK nicht automatisch gelöscht wird, sollten Sie die lokale Persistenz in der Emulatorkonfiguration deaktivieren, um Abweichungen zwischen der emulierten Datenbank und den lokalen Caches zu vermeiden. Im Web SDK ist die Persistenz standardmäßig deaktiviert.

Emulator-Daten löschen

Der Firestore-Emulator enthält einen REST-Endpunkt zum Löschen aller Daten, die sich derzeit im Emulator befinden. Mit diesem Endpunkt können Sie Daten zwischen Tests löschen, ohne den Emulator herunterzufahren.

Wenn Sie alle Daten im Emulator löschen möchten, führen Sie einen HTTP-DELETE-Vorgang für den folgenden Endpunkt aus. Ersetzen Sie dabei HOST und PORT durch den ausgewählten Host und Port und PROJECT_ID durch Ihre eigene Projekt-ID:

http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents

Passen Sie Host und Port an, wenn der Emulator nicht 127.0.0.1:8080 verwendet. Ihr Code sollte auf eine REST-Bestätigung warten, dass das Löschen abgeschlossen oder fehlgeschlagen ist.

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

$ curl -v -X DELETE "http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents"

Unterschiede zwischen dem Firestore-Emulator und der Produktion

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

Transaktionen

Der Emulator versucht nicht, das Transaktionsverhalten nachzubilden, das in der Produktion zu beobachten ist. Er verwendet einen einfachen Sperransatz und versucht nicht, die verschiedenen Parallelitätsmodi nachzubilden, die in der Produktionsumgebung angeboten werden.

Wenn Sie Funktionen testen, bei denen mehrere gleichzeitige Schreibvorgänge in ein Dokument ausgeführt werden, kann es lange dauern, bis der Emulator Schreibanfragen abschließt. Es kann bis zu 30 Sekunden dauern, bis der Emulator die Sperren freigibt. Passen Sie die Test-Timeout-Intervalle bei Bedarf an.

Der Emulator versucht auch nicht, alle Produktionslimits nachzubilden, z. B. Timeouts und Größenlimits, die Transaktionen betreffen. Wenn Sie Funktionen testen, die von diesen Produktionslimits abhängen, empfehlen wir, anstelle eines Emulators eine Produktionsumgebung zu verwenden.

Indexe

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

Limits

Der Emulator erzwingt nicht alle Limits, die in der Produktion erzwungen werden. 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 Limits proaktiv vermeidet.