Die Google Cloud CLI bietet einen lokalen Emulator im Speicher für Firestore, mit dem Sie Ihre Anwendung in Firestore 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 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:
Aktualisieren Sie die Installation der 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 durch Ihre Werte:gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT
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.
Es gibt zwei Möglichkeiten, Entitäten in den Emulator zu importieren. Fügen Sie dazu dem Befehl zum Starten 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"}'
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 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. Fügen Sie dazu dem Befehl zum Starten 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"}'
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 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/"}
Daten im Emulator speichern
Standardmäßig speichert der Firestore-Emulator keine Daten auf dem Laufwerk. Wenn Sie Emulatordaten dauerhaft speichern möchten, führen Sie den folgenden Befehl aus, um die Daten mithilfe von Import- und Export-Flags in Emulatorinstanzen 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 von Ihnen ausgewählten Host und Port und PROJECT_ID durch Ihre eigene Projekt-ID:
http://HOST:PORT/reset
Passen Sie den Host und den Port an, wenn der Emulator nicht 127.0.0.1:8080
verwendet.
Dein 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 mit einigen erheblichen Einschränkungen originalgetreu nachzubilden.
Gleichzeitigkeit und Konsistenz
Der Emulator unterstützt nur pessimistische Parallelität und starke Konsistenz. Der Emulator unterstützt keine Einstellungen für optimistische Datenbankübereinstimmung und Eventual Consistency.
Transaktionen
Der Emulator implementiert nicht das gesamte Transaktionsverhalten, das in der Produktion zu sehen ist. Wenn Sie Funktionen testen, die mehrere gleichzeitige Schreibvorgänge in ein Dokument umfassen, dauert es möglicherweise etwas länger, bis der Emulator Schreibanfragen abschließt. In einigen Fällen kann es bis zu 30 Sekunden dauern, bis die Sperre aufgehoben wird. Passen Sie bei Bedarf die Zeitlimits für Tests entsprechend an.
Indexe
Der Emulator überwacht keine zusammengesetzten Indexe und führt stattdessen jede gültige Abfrage aus. Testen Sie Ihre App mit einer echten Datastore-Modus-Instanz, um festzustellen, welche Indexe Sie benötigen.
Limits
Im Emulator werden nicht alle in der Produktion erzwungenen Limits erzwungen. Beispielsweise kann der Emulator Transaktionen zulassen, die vom Produktionsdienst als zu groß abgelehnt würden. Machen Sie sich mit den dokumentierten Limits vertraut und entwerfen Sie Ihre App so, dass sie diese proaktiv vermeidet.
Nächste Schritte
- Weitere Informationen zum Arbeiten mit Entitäten, Properties und Schlüsseln
- Weitere Informationen zu Abfragen