L'émulateur Datastore fournit une émulation locale de l'environnement de production Datastore. L'émulateur peut vous servir à développer et tester votre application en local. En outre, l'émulateur peut vous aider à générer des index pour votre instance de production Cloud Datastore et à supprimer des index inutiles. Cette page vous guide tout au long de l'installation de l'émulateur, de son démarrage et de la configuration des variables d'environnement permettant de connecter votre application à l'émulateur.
Problèmes connus
Par défaut, l'émulateur Datastore n'émule pas les fonctionnalités introduites par Firestore en mode Datastore. Les comportements par défaut de l'émulateur suivants ne correspondent pas au mode Datastore:
- L'émulateur simule la cohérence à terme par défaut. Firestore en mode Datastore est fortement cohérent.
- L'émulateur n'autorise pas les requêtes non ascendantes dans les transactions. Firestore en mode Datastore ne présente plus cette limitation.
- L'émulateur n'est pas compatible avec les requêtes
IN,!=etNOT-IN. - L'émulateur n'est pas compatible avec les requêtes d'agrégation telles que
COUNT(*).
Cependant, l'indicateur --use-firestore-in-datastore-mode permet d'assouplir certaines des restrictions ci-dessus pour Firestore en mode Datastore.
- L'émulateur simule des requêtes non ascendantes fortement cohérentes.
- L'émulateur autorise les requêtes non ascendantes dans les transactions.
- L'émulateur supprime la limite de 25 groupes d'entités dans une transaction.
Pour émuler Firestore en mode Datastore, utilisez plutôt gcloud emulators firestore start --database-mode=datastore-mode.
Avant de commencer
Pour utiliser l'émulateur Datastore, vous avez besoin des éléments suivants :
- Un JRE Java (version 11 ou ultérieure)
- Google Cloud CLI
- Une application créée à l'aide des bibliothèques clientes Google Cloud
Installer l'émulateur
L'émulateur Datastore est un composant de la gcloud CLI.
Exécutez la commande gcloud components install pour installer l'émulateur Datastore:
gcloud components install cloud-datastore-emulator
Répertoires de données de l'émulateur
L'émulateur simule Datastore en créant le fichier /WEB-INF/appengine-generated/local_db.bin dans un répertoire de données spécifié et en stockant des données dans local_db.bin. Par défaut, l'émulateur utilise le répertoire de données ~/.config/gcloud/emulators/datastore/.
Le fichier local_db.bin persiste entre les sessions de l'émulateur. Vous pouvez configurer plusieurs répertoires de données et les considérer comme une instance en mode Datastore locale et distincte. Pour effacer le contenu d'un fichier local_db.bin, arrêtez l'émulateur et supprimez-manuellement ce fichier.
Démarrer l'émulateur
Pour démarrer l'émulateur, exécutez la commande datastore start à partir d'une invite de commande :
gcloud emulators datastore start [flags]
où [flags] correspond aux arguments facultatifs de ligne de commande fournis à la gcloud CLI. Exemple :
--data-dir=[DATA_DIR]modifie le répertoire de données de l'émulateur. L'émulateur crée le fichier/WEB-INF/appengine-generated/local_db.bindans[DATA_DIR]ou, le cas échéant, utilise un fichier existant.--no-store-on-diskconfigure l'émulateur pour qu'il ne conserve aucune donnée concernant la session de l'émulateur sur le disque.
Consultez la documentation de référence sur gcloud beta emulators datastore start pour obtenir la liste complète des options facultatives.
Une fois l'émulateur démarré, un message semblable aux lignes suivantes doit s'afficher :
...
[datastore] Dev App Server is now running.
Pour arrêter l'émulateur, appuyez sur les touches CTRL+C à l'invite de commande.
Définir des variables d'environnement
Après avoir démarré l'émulateur, vous devez définir des variables d'environnement pour que votre application se connecte à l'émulateur et non à votre base de données de production en mode Datastore. Définissez ces variables d'environnement sur la même machine que celle utilisée pour exécuter votre application.
Les variables d'environnement doivent être définies chaque fois que vous démarrez l'émulateur. Elles dépendent des numéros de port attribués de manière dynamique, qui sont susceptibles d'être modifiés lorsque vous redémarrez l'émulateur.
Définir les variables automatiquement
Si votre application et l'émulateur s'exécutent sur la même machine, vous pouvez définir les variables d'environnement automatiquement comme suit :
Linux/macOS
Exécutez env-init à l'aide de la substitution de commande :
$(gcloud beta emulators datastore env-init)
Windows
Créez et exécutez un fichier batch à l'aide du résultat de la commande env-init :
gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd
Votre application se connecte alors à l'émulateur Datastore.
Définir les variables manuellement
Si votre application et l'émulateur s'exécutent sur des machines différentes, définissez les variables d'environnement manuellement :
Exécutez la commande
env-init:gcloud beta emulators datastore env-init
Sur la machine qui exécute votre application, définissez les variables d'environnement, ainsi que ses valeurs, comme indiqué par le résultat de la commande
env-init. Exemple :Linux/macOS export DATASTORE_DATASET=my-project-id export DATASTORE_EMULATOR_HOST=::1:8432 export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore export DATASTORE_HOST=http://::1:8432 export DATASTORE_PROJECT_ID=my-project-id
Windows set DATASTORE_DATASET=my-project-id set DATASTORE_EMULATOR_HOST=::1:8432 set DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore set DATASTORE_HOST=http://::1:8432 set DATASTORE_PROJECT_ID=my-project-id
Votre application se connecte alors à l'émulateur Datastore. Notez que l'ID de projet et le port fournis par la commande diffèrent de l'exemple ci-dessus.
Mettre à jour et supprimer des index
En exécutant votre application à l'aide de l'émulateur, vous pouvez générer des index pour votre base de données de production en mode Datastore et supprimer des index inutiles. Pour en savoir plus, consultez Utiliser la gcloud CLI.
Supprimer des variables d'environnement
Après avoir terminé d'utiliser l'émulateur, arrêtez-le (Control-C) et supprimez les variables d'environnement afin que votre application se connecte à votre base de données de production en mode Datastore.
Supprimer les variables automatiquement
Si votre application et l'émulateur s'exécutent sur la même machine, vous pouvez supprimer les variables d'environnement automatiquement :
Linux/macOS
Exécutez env-unset à l'aide de la substitution de commande :
$(gcloud beta emulators datastore env-unset)
Windows
Créez et exécutez un fichier batch à l'aide du résultat de la commande env-unset :
gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd
Votre application se connecte alors à votre base de données de production en mode Datastore.
Supprimer les variables manuellement
Si votre application et l'émulateur s'exécutent sur des machines différentes, supprimez les variables d'environnement manuellement :
Exécutez la commande
env-unset:gcloud beta emulators datastore env-unset
Sur la machine qui exécute votre application, supprimez les variables d'environnement comme indiqué par le résultat de la commande
env-unset. Exemple :Linux/macOS unset DATASTORE_DATASET unset DATASTORE_EMULATOR_HOST unset DATASTORE_EMULATOR_HOST_PATH unset DATASTORE_HOST unset DATASTORE_PROJECT_ID
Windows set DATASTORE_DATASET= set DATASTORE_EMULATOR_HOST= set DATASTORE_EMULATOR_HOST_PATH= set DATASTORE_HOST= set DATASTORE_PROJECT_ID=
Votre application se connecte alors à votre base de données de production en mode Datastore.