Utiliser le serveur de développement local

Ce serveur émule l'environnement d'exécution Java d'App Engine et tous ses services, y compris Datastore.

Avant de commencer

Java 8 ayant atteint la fin de la période de compatibilité, vous ne pouvez plus utiliser la dernière version de dev_appserver.py pour exécuter localement vos applications. Pour télécharger une version archivée de devapp_server.py, procédez comme suit :

  1. À partir des archives, téléchargez le dossier compressé contenant le serveur dev_appserver.py pour les environnements d'exécution qui ne sont plus compatibles.

  2. Extrayez le contenu du répertoire vers votre système de fichiers local, par exemple vers votre répertoire /home. Vous trouverez dev_appserver.py dans le répertoire google_appengine/google/appengine/tools/java/bin.

Exécuter le serveur Web de développement

Pour en savoir plus sur la définition des propriétés système et des variables d'environnement de votre application, consultez la page Mode de traitement des requêtes.

Vous pouvez également exécuter le serveur Web de développement à partir d'une invite de commande. La commande à exécuter se trouve dans le répertoire du SDK avec le chemin relatif google_appengine/google/appengine/tools/java/bin.

Syntaxe de la commande Windows :

google_appengine\google\appengine\tools\java\bin\java_dev_appserver.cmd [options] [WAR_DIRECTORY_LOCATION]

Syntaxe de la commande Linux ou macOS :

google_appengine/google/appengine/tools/java/bin/java_dev_appserver.sh [options] [WAR_DIRECTORY_LOCATION]

Cette commande utilise l'emplacement du répertoire WAR de votre application en tant qu'argument.

Arrêter le serveur de développement

Pour arrêter le serveur Web, appuyez sur les touches Ctrl-C.

Détecter l'environnement d'exécution de l'application

Pour déterminer si votre code est en cours d'exécution en production ou sur le serveur de développement local, vous pouvez vérifier la valeur de la méthode SystemProperty.environment.value(). Exemple :

if (SystemProperty.environment.value() == SystemProperty.Environment.Value.Production) {
   // Production
 } else {
  // Local development server
  // which is: SystemProperty.Environment.Value.Development
}

Utiliser l'émulateur Datastore local

Le serveur Web de développement simule Datastore à l'aide d'un datastore local sauvegardé sur fichier sur votre ordinateur. Le datastore est nommé local_db.bin. Il est créé dans le répertoire WAR de votre application, sous WEB-INF /appengine-generated/. (il n'est pas transféré avec l'application).

Ce datastore persiste entre les appels du serveur Web. Les données que vous stockez seront donc toujours disponibles lors de la prochaine exécution du serveur Web. Pour effacer le contenu du datastore, arrêtez le serveur, puis supprimez ce fichier.

Comme décrit dans la section Configurer les index Datastore, le serveur de développement peut générer une configuration pour les index Datastore nécessaires à votre application, déterminée à partir des requêtes effectuées lors du test. Un fichier nommé datastore-indexes-auto.xml est alors généré dans le répertoire WEB-INF/appengine-generated/ du fichier d'archives WAR. Pour désactiver la configuration automatique des index, créez ou modifiez le fichier datastore-indexes.xml dans le répertoire WEB-INF/ à l'aide de l'attribut autoGenerate="false" pour l'élément <datastore-indexes>.

Parcourir Datastore dans le serveur de développement

Pour parcourir votre datastore local à l'aide du serveur Web de développement, procédez comme suit :

  1. Démarrez le serveur de développement comme indiqué précédemment.
  2. Accédez à la console de développement.
  3. Cliquez sur Lecteur Datastore dans le volet de navigation de gauche pour afficher les contenus de votre datastore local.

Modèle de cohérence Datastore

Par défaut, le datastore local est configuré de sorte que le pourcentage d'écritures Datastore qui ne sont pas immédiatement visibles dans les requêtes globales soit défini sur 10 %.

Pour ajuster ce niveau de cohérence, définissez la propriété système datastore.default_high_rep_job_policy_unapplied_job_pct sur une valeur correspondant au degré de cohérence à terme que vous souhaitez pour votre application.

-Ddatastore.default_high_rep_job_policy_unapplied_job_pct=20

Si vous définissez cette propriété à l'aide de l'invite de commande java_dev_appserver.sh, vous devez utiliser --jvm_flag=... pour définir la propriété :

google_appengine/google/appengine/tools/java/bin/java-dev_appserver.sh  --jvm_flag=-Ddatastore.default_high_rep_job_policy_unapplied_job_pct=20

La plage valide pour datastore.default_high_rep_job_policy_unapplied_job_pct est comprise entre 0 et 100. Si vous utilisez des nombres situés en dehors de cette plage, vous recevrez un message d'erreur.

Spécifier la stratégie d'allocation automatique d'ID

Vous pouvez configurer la manière dont le datastore local attribue les ID automatiques d'entités.

Les stratégies suivantes d'allocation automatique d'ID sont disponibles sur le serveur de développement :

sequential
Les ID sont attribués à partir de la séquence d'entiers consécutifs.
scattered
Les ID sont attribués à partir d'une séquence non répétitive d'entiers distribués de manière quasiment uniforme.

La règle par défaut dans le datastore local est scattered.

Pour spécifier la règle d'identification automatique, définissez la propriété système datastore.auto_id_allocation_policy sur sequential ou scattered.

-Ddatastore.auto_id_allocation_policy=scattered

Pour définir cette propriété système via un indicateur transmis à la macro dev_appserver, procédez comme suit :

java_dev_appserver --jvm_flag=-Ddatastore.auto_id_allocation_policy=scattered

Simuler des comptes utilisateur

Le serveur Web de développement simule le service Google Accounts à l'aide de ses propres pages de connexion et de déconnexion. Lorsqu'elles s'exécutent sur le serveur Web de développement, les méthodes générant des URL de connexion et de déconnexion renvoient des URL pour /_ah/login et /_ah/logout sur le serveur local.

La page de connexion de développement contient un formulaire dans lequel vous pouvez entrer une adresse e-mail. Au cours de la session, l'adresse que vous avez entrée en tant qu'utilisateur actif est utilisée.

Pour que l'application considère que l'utilisateur connecté est un administrateur, cochez la case "Se connecter en tant qu'administrateur" du formulaire.

Utiliser le service de récupération d'URL

Lorsque l'application utilise l'API URL Fetch pour exécuter une requête HTTP, le serveur Web de développement exécute cette requête directement à partir de votre ordinateur. Lorsque l'application s'exécute sous App Engine et si vous utilisez un serveur proxy pour accéder aux sites Web, le comportement de ce serveur peut être différent.

Console de développement

Le serveur Web de développement contient une application de console Web. Elle vous permet de parcourir le datastore local.

Pour accéder à la console, utilisez l'URL /_ah/admin sur votre serveur : http://localhost:8080/_ah/admin.

Arguments de ligne de commande

Les arguments de ligne de commande suivants sont pris en charge par le serveur de développement :

--address=...

Adresse hôte à utiliser pour le serveur. Vous aurez peut-être besoin de définir cette option pour pouvoir accéder au serveur de développement à partir d'un autre ordinateur de votre réseau. L'adresse 0.0.0.0 autorise les accès à partir d'un hôte local (localhost) et à partir d'un nom d'hôte (hostname). Valeur par défaut : localhost.

--default_gcs_bucket=...

Définit le nom du bucket Google Cloud Storage par défaut.

--disable_update_check

Si cet argument est défini, le serveur de développement ne contacte pas App Engine pour vérifier la disponibilité d'une nouvelle version du SDK. Par défaut, le serveur recherche une nouvelle version au démarrage et affiche un message s'il en existe une.

--generated_dir=...

Définit le répertoire dans lequel les fichiers générés sont créés.

--help

Affiche un message utile, puis la fenêtre se ferme.

--jvm_flag=...

Transmet l'indicateur donné en tant qu'argument JVM. Peut être répété pour fournir plusieurs indicateurs.

--port=...

Numéro de port à utiliser pour le serveur. La valeur par défaut est 8080.

--sdk_root=...

Chemin d'accès à gcloud CLI, s'il est différent de l'emplacement de l'outil.

--server=...

Serveur à utiliser pour déterminer la dernière version du SDK.