Die Google Cloud CLI stellt einen lokalen Emulator im Speicher für Firestore zur Verfügung, mit dem Sie Ihre Firestore-Anwendung im Datastore-Modus testen können. Sie können den Emulator mit allen Clientbibliotheken im 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 die Daten vom Emulator nur im Arbeitsspeicher gespeichert werden, bleiben die Daten nicht über mehrere Durchläufe hinweg erhalten.
Emulator installieren
Zum Installieren des Firestore-Emulators installieren und aktualisieren Sie die gcloud CLI:
Aktualisieren Sie Ihre gcloud CLI, um die neuesten Features zu erhalten:
gcloud components update
Emulator starten
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
Verwende die Tastenkombination
Control + C
, um den Emulator zu beenden.
Mit dem Emulator verbinden
Legen Sie die Umgebungsvariable DATASTORE_EMULATOR_HOST
fest, um eine Clientbibliothek und eine Anwendung mit dem Emulator zu verbinden. 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 können Entitäten auf zwei Arten in den Emulator importieren. Im ersten Schritt fügen Sie dem Startbefehl des Emulators das Flag import-data
hinzu. Die zweite Methode besteht darin, eine POST-Importanfrage an den Emulator zu senden. Dazu können Sie curl oder ein ähnliches Tool verwenden. Sehen Sie sich die folgenden Beispiele an.
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 der Emulator einen anderen Port verwendet.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 einer Standarddatenbank würde beispielsweise so aussehen:{"database":"projects/myProject/databases/"}
[EXPORT_DIRECTORY]
ist der Pfad zuroverall_export_metadata
-Datei 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.
Es gibt zwei Möglichkeiten, Entitäten aus dem Emulator zu exportieren. Im ersten Schritt fügen Sie dem Startbefehl des Emulators das Flag export-on-exit
hinzu. Die zweite Methode besteht darin, eine POST
-Exportanfrage an den Emulator zu senden. Dazu können Sie curl oder ein ähnliches Tool verwenden. Sehen Sie sich die folgenden Beispiele an.
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 der Emulator einen anderen Port verwendet.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 einer Standarddatenbank würde beispielsweise so aussehen:{"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/"}
Emulatordaten zurücksetzen
Der Firestore-Emulator enthält einen REST-Endpunkt zum Zurücksetzen aller Daten im Emulator. Sie können diesen Endpunkt verwenden, um Daten zwischen Tests zu löschen, ohne den Emulator herunterzufahren.
Führen Sie zum Zurücksetzen aller Daten im Emulator einen HTTP-POST
-Vorgang für den folgenden Endpunkt aus. Ersetzen Sie dabei HOST und PORT durch den ausgewählten Host und Port und ersetzen Sie PROJECT_ID durch Ihre eigene Projekt-ID:
http://HOST:PORT/reset
Passen Sie den Host und den Port an, wenn der Emulator 127.0.0.1:8080
nicht verwendet.
Ihr Code sollte auf die REST-Bestätigung warten, dass das Zurücksetzen abgeschlossen wurde oder fehlgeschlagen ist.
Sie können diesen Vorgang über die Shell mit curl
ausführen:
$ curl -X POST "http://HOST:PORT/reset"
Unterschied zwischen Emulator und Produktionsversion
Der Emulator versucht, das Verhalten des Produktionsdienstes originalgetreu zu replizieren. Es gibt jedoch einige wesentliche Einschränkungen.
Nebenläufigkeit und Konsistenz
Der Emulator unterstützt nur pessimistische Nebenläufigkeit und Strong Consistency. Der Emulator unterstützt keine Einstellungen für optimistische Nebenläufigkeit und Eventual Consistency.
Transaktionen
Der Emulator implementiert nicht das gesamte in der Produktion beobachtete Transaktionsverhalten. Wenn Sie Features testen, die mehrere gleichzeitige Schreibvorgänge in einem Dokument beinhalten, führt der Emulator möglicherweise dazu, dass Schreibanfragen langsam ausgeführt werden. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis Sperren aufgehoben werden. Passen Sie die Zeitüberschreitungen bei den Tests bei Bedarf entsprechend an.
Indexe
Der Emulator verfolgt keine zusammengesetzten Indexe, sondern führt stattdessen eine gültige Abfrage aus. Testen Sie Ihre Anwendung unbedingt an einer echten Instanz im Datastore-Modus, um festzustellen, welche Indexe Sie benötigen.
Limits
Der Emulator erzwingt nicht alle Beschränkungen, die in der Produktion erzwungen werden. Der Emulator kann beispielsweise Transaktionen zulassen, die vom Produktionsdienst als zu groß abgelehnt würden. Machen Sie sich daher mit den dokumentierten Beschränkungen vertraut und entwickeln Sie Ihre Anwendung so, dass diese proaktiv vermieden werden.
Nächste Schritte
- Informationen zur Arbeit mit Entitäten, Attributen und Schlüsseln
- Weitere Informationen zu Abfragen