Datastore-Modus mit dem Firestore-Emulator testen

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

Verwenden Sie gcloud emulators firestore mit --database-mode=datastore-mode, um das Verhalten von Firestore im Datastore-Modus zu testen.

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

Installieren und aktualisieren Sie die gcloud CLI, um den Firestore-Emulator zu installieren:

  1. Installieren Sie das gcloud-CLI.

  2. Aktualisieren Sie die Installation der gcloud CLI, um die neuesten Features zu erhalten:

    gcloud components update

Emulator starten

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

    gcloud emulators firestore start --database-mode=datastore-mode

    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 --database-mode=datastore-mode --host-port=HOST:PORT

  2. Verwenden Sie die Tastenkombination Control + C, um den Emulator zu beenden.

Verbindung zum Emulator herstellen

Wenn Sie eine Clientbibliothek und eine App mit dem Emulator verbinden möchten, legen Sie die Umgebungsvariable DATASTORE_EMULATOR_HOST fest. Wenn diese Umgebungsvariable festgelegt ist, stellen die Clientbibliotheken automatisch eine Verbindung zum Emulator her.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Entitäten in den Emulator importieren

Mit der Importfunktion des Emulators können Sie Entitäten aus einer Reihe von Entitätsexportdateien in den Emulator laden. Die Entitätsexportdateien können aus einem Export der Datenbank im Datastore-Modus oder aus einer Emulatorinstanz stammen.

Sie haben zwei Möglichkeiten, Entitäten in den Emulator zu importieren. Fügen Sie zuerst das Flag import-data zum Startbefehl des Emulators hinzu. Die zweite Methode besteht darin, eine POST-Importanfrage an den Emulator zu senden. Dazu können Sie curl oder ein ähnliches Tool verwenden. Weitere Informationen finden Sie in den folgenden Beispielen.

Protokoll

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'
Ändern Sie localhost:8080, wenn vom Emulator ein anderer Port verwendet wird.

Befehlszeilen-Flag

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY

Dabei gilt:

  • [PROJECT_ID] ist die ID des Projekts.

  • [DATABASE] ist der Datenbankpfad. Ein Projekt mit der Standarddatenbank sieht beispielsweise so aus:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] ist der Pfad zur Datei overall_export_metadata Ihrer Entitätsexportdateien. Beispiel:

    {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

Entitäten im Emulator exportieren

Mit der Exportfunktion des Emulators können Sie Entitäten im Emulator in einer Reihe von Entitätsexportdateien speichern. Danach können Sie die Entitäten in den Entitätsexportdateien über einen Importvorgang in die Datenbank im Datastore-Modus oder in eine Emulatorinstanz laden.

Sie haben zwei Möglichkeiten, Entitäten aus dem Emulator zu exportieren. Fügen Sie zuerst das Flag export-on-exit zum Startbefehl des Emulators hinzu. Die zweite Methode besteht darin, eine POST-Exportanfrage an den Emulator zu senden. Dazu können Sie curl oder ein ähnliches Tool verwenden. Weitere Informationen finden Sie in den folgenden Beispielen.

Protokoll

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:export \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE_PATH", "export_directory":"EXPORT_DIRECTORY"}'
Ändern Sie localhost:8080, wenn vom Emulator ein anderer Port verwendet wird.

Befehlszeilen-Flag

gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY

Dabei gilt:

  • [PROJECT_ID] ist die ID des Projekts.

  • [DATABASE_PATH] ist der Datenbankpfad. Ein Projekt mit der Standarddatenbank sieht beispielsweise so aus:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] gibt das Verzeichnis an, in dem die Entitätsexportdateien vom Emulator gespeichert werden. Dieses Verzeichnis darf noch keine Entitätsexportdateien enthalten. Beispiel:

    {"export_directory":"/home/user/myexports/2024-03-26/"}

Daten im Emulator beibehalten

Standardmäßig werden Daten vom Firestore-Emulator nicht auf dem Laufwerk gespeichert. Wenn Sie Emulatordaten beibehalten möchten, führen Sie den folgenden Befehl aus, um Import- und Export-Flags zu verwenden, um die Daten über Emulatorinstanzen hinweg zu laden und zu speichern:

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY

Emulatordaten zurücksetzen

Der Firestore-Emulator enthält einen REST-Endpunkt zum Zurücksetzen aller Daten im Emulator. Mit diesem Endpunkt können Sie Daten zwischen Tests löschen, ohne den Emulator herunterzufahren.

Wenn Sie alle Daten im Emulator zurücksetzen möchten, führen Sie einen HTTP-POST-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 Projekt-ID:

http://HOST:PORT/reset

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 Zurücksetzen abgeschlossen oder fehlgeschlagen ist.

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

$ curl -X POST "http://HOST:PORT/reset"

Unterschiede zwischen Emulator und Produktion

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

Nebenläufigkeit und Konsistenz

Der Emulator unterstützt nur pessimistische Nebenläufigkeit und strikte Konsistenz. Der Emulator unterstützt keine optimistische Nebenläufigkeit und keine Einstellungen für Eventual Consistency.

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

Standardmäßig werden vom Emulator keine zusammengesetzten Indexe verfolgt. Stattdessen wird jede gültige Abfrage ausgeführt.

Wenn Sie testen möchten, ob die Anforderungen an zusammengesetzte Indexe erfüllt sind, starten Sie den Emulator mit den Flags --require-indexes und --index-file. Wenn Sie den Emulator mit diesen Flags starten, werden Abfragen, für die ein zusammengesetzter Index erforderlich ist, der nicht in der angegebenen Indexdatei definiert ist, geprüft und abgelehnt.

gcloud emulators firestore start --database-mode=datastore-mode --require-indexes --index-file=./index.yaml

Weitere Informationen zum index-file Format finden Sie unter Datastore-Indexe mit index.yaml konfigurieren.

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.

Nächste Schritte