Tester le mode Datastore à l'aide de l'émulateur Firestore

Le Google Cloud CLI fournit un émulateur local en mémoire pour Firestore, utilisable 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.

Utilisez 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 en production. Étant donné que l'émulateur stocke les données uniquement en mémoire, il ne les conserve pas lors des exécutions.

Installer l'émulateur

Pour installer l'émulateur Firestore, installez et mettez à jour le gcloud CLI :

  1. Installer gcloud CLI.

  2. Mettez à jour votre installation de gcloud CLI pour bénéficier des dernières fonctionnalités :

    gcloud components update

Exécuter l'émulateur

  1. 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 l' émulateur à 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

  2. 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, définissez la variable d'environnement DATASTORE_EMULATOR_HOST. Lorsque cette variable d'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 d'entités peuvent provenir d'une exportation de 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 l'option import-data à votre commande de démarrage de l'émulateur. La deuxième méthode consiste à envoyer une requête d'importation POST à l'émulateur. Vous pouvez utiliser curl ou un outil similaire. Consultez les exemples suivants.

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 de la 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 à la base de données. Par exemple, un projet avec une base de données par défaut se présente comme suit :

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

  • [EXPORT_DIRECTORY] est le chemin d'accès au fichier overall_export_metadata de vos fichiers d'exportation d'entités. 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 à partir de l'émulateur de deux manières. La première consiste à ajouter l'option export-on-exit à votre commande de démarrage de l'émulateur. La deuxième méthode consiste à envoyer une requête d'exportation POST à l'émulateur. Vous pouvez utiliser curl ou un outil similaire. Consultez les exemples suivants.

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.

Option 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 à la base de données. Par exemple, un projet avec une base de données par défaut se présente comme suit :

    {"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 les options d'importation et d'exportation pour charger et enregistrer les données dans les instances de l'é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 réinitialiser toutes les données de l'émulateur. Vous pouvez utiliser ce point de terminaison pour effacer les données entre les tests sans arrêter l'émulateur.

Pour réinitialiser toutes les données de l'émulateur, effectuez une opération HTTP POST sur le point de terminaison suivant, en remplaçant HOST et PORT par l'hôte et le port que vous avez sélectionnés, et PROJECT_ID par votre propre ID de 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 a réussi ou é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 comportement du service de production, avec quelques limites notables.

Concurrence et cohérence

L'émulateur n'est compatible qu'avec la concurrence pessimiste et la cohérence forte. Il n'est pas compatible avec la concurrence optimiste ni les paramètres de cohérence à terme.

Transactions

L'émulateur ne tente pas d'imiter le comportement des transactions observé en production. Il utilise une approche de verrouillage simple et ne tente pas de refléter les différents modes de simultanéité proposés dans l'environnement de production.

Lorsque vous testez des fonctionnalités impliquant plusieurs écritures simultanées dans un même document, l'émulateur peut mettre du temps à traiter les requêtes d'écriture. L'émulateur peut mettre jusqu'à 30 secondes pour libérer les verrous. Si vous devez ajuster les intervalles de délai avant expiration des tests, faites-le.

L'émulateur ne tente pas non plus d'imiter toutes les limites de production, telles que les délais avant expiration et les limites de taille, qui impliquent des transactions. Si vous testez des fonctionnalités qui dépendent de ces limites de production, nous vous recommandons d'utiliser un environnement de production plutôt qu'un émulateur.

Index

Par défaut, l'émulateur ne suit pas les index composites et exécute à la place toute requête valide.

Pour vérifier si les exigences relatives aux index composites sont remplies, démarrez l'émulateur avec les options --require-indexes et --index-file. Lorsque vous démarrez l'émulateur avec ces options, il recherche et rejette les requêtes qui nécessitent un index composite non défini dans le fichier d'index spécifié.

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

Pour en savoir plus sur le format index-file, consultez Configurer les index Datastore avec index.yaml.

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 comme étant trop volumineuses par le service de production. Assurez-vous de connaître les limites documentées et de concevoir votre application de manière à les éviter de manière proactive.

Étape suivante