Exécuter l'émulateur Datastore

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 de l'émulateur par défaut 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, != et NOT-IN.
• L'émulateur n'est pas compatible avec les requêtes d'agrégation telles que COUNT(*).

Toutefois, l'indicateur --use-firestore-in-datastore-mode permet d'assouplir certaines des restrictions ci-dessus pour Firestore en mode Datastore.

• L'émulateur simule les 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 par transaction.

Pour émuler Firestore en mode Datastore, utilisez gcloud emulators firestore start --database-mode=datastore-mode à la place.

Avant de commencer

Pour utiliser l'émulateur Datastore, vous avez besoin des éléments suivants :

• Java JRE (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.bin dans [DATA_DIR] ou, le cas échéant, utilise un fichier existant.

• --no-store-on-disk configure 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 :

$(gcloud beta emulators datastore 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 :

1. Exécutez la commande env-init :

   gcloud beta emulators datastore env-init

2. 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 :

$(gcloud beta emulators datastore 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 :

1. Exécutez la commande env-unset :

   gcloud beta emulators datastore env-unset

2. 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.