La Google Cloud CLI fournit un émulateur local en mémoire pour Firestore, que vous pouvez utiliser pour tester votre application Firestore en mode Datastore. Vous pouvez utiliser l'émulateur avec toutes les bibliothèques clientes en mode Datastore. Vous ne devez utiliser l'émulateur que pour les tests locaux.
Utiliser gcloud emulators firestore
avec --database-mode=datastore-mode
pour tester le comportement de Firestore en mode Datastore.
N'utilisez pas l'émulateur pour les déploiements de production. Comme l'émulateur stocke les données uniquement en mémoire, les données ne sont pas conservées d'une exécution à l'autre.
Installer l'émulateur
Pour installer l'émulateur Firestore, installez et mettez à jour le fichier gcloud CLI:
Mettez à jour votre installation gcloud CLI pour obtenir les dernières fonctionnalités:
gcloud components update
Exécuter l'émulateur
Exécutez la commande suivante pour démarrer l'émulateur :
gcloud emulators firestore start --database-mode=datastore-mode
L'émulateur imprime l'hôte et le numéro de port sur lequel il s'exécute.
Par défaut, l'émulateur tente d'utiliser
127.0.0.1:8080
. Pour lier le vers un hôte et un port spécifiques, utilisez l'option facultative--host-port
. en remplaçant HOST et PORT:gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT
Utilisez le raccourci clavier
Control + C
pour arrêter l'émulateur.
Se connecter à l'émulateur
Pour connecter une bibliothèque cliente et une application à l'émulateur, procédez comme suit :
définissez la variable d'environnement DATASTORE_EMULATOR_HOST
. Lorsque cet environnement
est définie, les bibliothèques clientes se connectent automatiquement à l'émulateur.
export DATASTORE_EMULATOR_HOST="HOST:PORT"
Importer des entités dans l'émulateur
La fonctionnalité d'importation de l'émulateur vous permet de charger des entités dans l'émulateur à partir d'un ensemble de fichiers d'exportation d'entités. Les fichiers d'exportation des entités peuvent provenir d'une exportation votre base de données en mode Datastore ou d'une instance d'émulateur.
Vous pouvez importer des entités dans l'émulateur de deux manières. La première consiste à ajouter
Ajoutez import-data
à la commande de démarrage de l'émulateur. La deuxième méthode consiste à
envoyez une requête d'importation POST à l'émulateur. Vous pouvez utiliser
curl ou un outil similaire. Reportez-vous aux
exemples.
Protocole
curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \ -H 'Content-Type: application/json' \ -d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'Modifiez
localhost:8080
si l'émulateur utilise un autre port.Option CLI
gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY
où :
[PROJECT_ID]
est l'ID de votre projet.[DATABASE]
est le chemin d'accès de la base de données. Par exemple, un projet avec une base de données par défaut ressemblerait à ceci:{"database":"projects/myProject/databases/"}
[EXPORT_DIRECTORY]
est le chemin d'accès au fichieroverall_export_metadata
des fichiers d'exportation de votre entité. Exemple :{"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}
Exporter des entités dans l'émulateur
La fonctionnalité d'exportation de l'émulateur vous permet d'enregistrer des entités dans l'émulateur au sein d'un ensemble de fichiers d'exportation d'entités. Vous pouvez alors utiliser une opération d'importation pour charger, dans votre base de données en mode Datastore ou dans une instance d'émulateur, les entités contenues dans les fichiers d'exportation d'entités.
Vous pouvez exporter des entités depuis l'émulateur de deux manières. La première consiste à ajouter
Ajoutez export-on-exit
à la commande de démarrage de l'émulateur. La deuxième méthode consiste à
envoyez une requête d'exportation POST
à l'émulateur. Vous pouvez utiliser
curl ou un outil similaire. Reportez-vous aux
exemples.
Protocole
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"}'Modifiez
localhost:8080
si l'émulateur utilise un autre port.Indicateur de la CLI
gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY
où :
[PROJECT_ID]
est l'ID de votre projet.[DATABASE_PATH]
est le chemin d'accès de la base de données. Par exemple, un projet avec une base de données par défaut ressemblerait à ceci:{"database":"projects/myProject/databases/"}
[EXPORT_DIRECTORY]
spécifie le répertoire dans lequel l'émulateur enregistre les fichiers d'exportation d'entités. Ce répertoire ne doit pas déjà contenir un ensemble de fichiers d'exportation d'entités. Exemple :{"export_directory":"/home/user/myexports/2024-03-26/"}
Conserver les données dans l'émulateur
Par défaut, l'émulateur Firestore ne conserve pas les données sur le disque. Pour conserver les données de l'émulateur, exécutez la commande suivante afin d'utiliser l'importation et l'exportation pour charger et enregistrer les données entre les instances d'émulateur:
gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY
Réinitialiser les données de l'émulateur
L'émulateur Firestore inclut un point de terminaison REST permettant de tout réinitialiser les données dans l'émulateur. Vous pouvez utiliser ce point de terminaison pour effacer des données entre les tests sans arrêter l'émulateur.
Pour réinitialiser toutes les données dans l'émulateur, effectuez une opération HTTP POST
sur
le point de terminaison suivant, en remplaçant HOST et PORT par
hôte et le port que vous avez sélectionnés, en remplaçant PROJECT_ID par votre
ID de votre propre projet:
http://HOST:PORT/reset
Ajustez l'hôte et le port si l'émulateur n'utilise pas 127.0.0.1:8080
.
Votre code doit attendre la confirmation REST indiquant que la réinitialisation s'est terminée ou a échoué.
Vous pouvez effectuer cette opération à partir du shell à l'aide de curl
:
$ curl -X POST "http://HOST:PORT/reset"
Différences entre l'émulateur et la production
L'émulateur tente de reproduire fidèlement le le comportement du service de production avec quelques limitations notables.
Simultanéité et cohérence
L'émulateur n'accepte que la simultanéité pessimiste et la cohérence forte. L'émulateur n'est pas compatible avec la simultanéité optimiste et une cohérence à terme paramètres.
Transactions
L'émulateur n'implémente pas tous les comportements de transaction observées en production. Lorsque vous testez des fonctionnalités qui impliquent plusieurs écritures simultanées dans un document, l'émulateur peut mettre du temps à terminer l'écriture requêtes. Dans certains cas, le déverrouillage peut prendre jusqu'à 30 secondes. Envisagez d'ajuster les délais avant expiration des tests en conséquence, si nécessaire.
Index
L'émulateur n'effectue pas le suivi des index composites et exécute à la place requête valide. Veillez à tester votre application par rapport à un mode Datastore réel. pour déterminer les index dont vous avez besoin.
Limites
L'émulateur n'applique pas toutes les limites appliquées en production. Par exemple, l'émulateur peut autoriser des transactions qui seraient rejetées car trop volumineuses par le de production. Veillez à bien connaître les limites documentées et que vous concevez votre application pour les éviter de manière proactive.
Étape suivante
- Découvrez comment utiliser les entités, propriétés et clés.
- En savoir plus sur les requêtes