Documentation de référence sur appengine-web.xml

En plus du descripteur de déploiement web.xml, les applications Java d'App Engine utilisent un fichier de configuration nommé appengine-web.xml, pour spécifier les informations relatives à votre application et identifier les fichiers statiques (tels que les images) et les fichiers de ressources utilisés par l'application.

Exemple

L'exemple suivant est un fichier minimal spécifiant l'ID de l'application, un identificateur de la version, et aucun fichier statique ni fichier de ressource :

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>_your_app_id_</application><!-- unused for Cloud SDK based tooling -->
  <version>alpha-001</version><!-- unused for Cloud SDK based tooling -->
  <threadsafe>true</threadsafe>
</appengine-web-app>

Syntaxe

Une application App Engine Java doit posséder un fichier nommé appengine-web.xml dans son fichier d'archives WAR, au sein du répertoire WEB-INF/. Il s'agit d'un fichier XML dont l'élément racine est <appengine-web-app>.

Vous pouvez trouver la définition du type de document (DTD) et les spécifications de schéma du appengine-web.xml dans le répertoire docs/ du SDK.

Élément Description
<application>

Non obligatoire si vous déployez votre application à l'aide d'outils basés sur le SDK Cloud, tel que la commande gcloud app deploy, les plug-ins IntelliJ ou Eclipse, et les plug-ins Maven ou Gradle. Les outils basés sur le SDK Cloud ignorent cet élément et extraient l'ID de projet de la propriété gcloud "config projet". Notez que, bien que l'ID de projet soit remplaçable à l'aide de l'outil de ligne de commande gcloud, ce remplacement définit un ID de projet à l'échelle de la machine, pouvant entraîner une confusion si vous développez plusieurs projets. L'élément <application> contient l'ID de projet de l'application. Il s'agit de l'ID de projet que vous avez enregistré lors de la création de votre projet dans la console Google Cloud Platform. Lorsque vous téléchargez votre application, appcfg obtient l'ID de projet à partir de ce fichier.

<async-session-persistence>

Facultatif. Il est possible de réduire la latence de la requête en configurant votre application pour une écriture asynchrone des données de session HTTP dans le datastore :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->
</appengine-web-app>

Avec la persistance de session asynchrone activée, App Engine soumet une tâche de file d'attente de tâches pour écrire des données de session dans le datastore avant de les écrire dans le memcache. Par défaut, la tâche sera soumise à la file d'attente "default" (par défaut). Si vous souhaitez utiliser une autre file d'attente, ajoutez l'attribut "queue-name" comme suit :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->
</appengine-web-app>

Les données de session sont toujours écrites de manière synchrone dans le memcache. Si une requête essaie de lire les données de session alors que le memcache n'est pas disponible (ou que les données de session ont été vidées), elle basculera sur Datastore, qui ne dispose peut-être pas encore des données de session les plus récentes. Cela signifie que la persistance de session asynchrone peut amener votre application à afficher des données de session obsolètes. Cependant, pour la plupart des applications, l'avantage du temps de latence compense largement le risque encouru.

<auto-id-policy> Facultatif. Si vous configurez automatiquement des identifiants d'entité, vous pouvez modifier la méthode employée en définissant une règle d'ID automatique. Les options suivantes sont valides :
default
Valeur par défaut. Utilise des ID automatiques distribués qui sont de grands entiers bien répartis, suffisamment petits pour être représentés par des nombres à virgule flottante de 64 bits.
legacy
L'option "legacy" sera obsolète dans une version ultérieure, et sera potentiellement supprimée. Pour en savoir plus, consultez l'article de blog annonçant cette modification.
<automatic-scaling>

Facultatif. Pour une explication complète, consultez la section Mise à l'échelle automatique.

<basic-scaling>

Facultatif. Pour une explication complète, consultez la section relative au scaling de base.

<env-variables>

Facultatif. Le fichier appengine-web.xml peut préciser des variables d'environnement définies lors de l'exécution de l'application.


<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

Pour éviter les conflits avec votre environnement local, le serveur de développement ne définit pas de variables d'environnement basées sur ce fichier et requiert que ces variables soient déjà définies dans l'environnement local avec des valeurs correspondantes.


export DEFAULT_ENCODING="UTF-8"
dev_appserver war

Lorsqu'il est déployé dans App Engine, l'environnement est créé avec ces variables déjà définies.

<inbound-services>

Facultatif. Avant qu'une application puisse recevoir un e-mail, elle doit être configurée pour activer le service. Afin d'activer le service pour une application Java, vous devez inclure une section <inbound-services> dans le fichier appengine-web.xml.

Le service entrant suivant est disponible :

mail
Permet à votre application de recevoir des messages.
<instance-class>

Facultatif. Taille de la classe d'instance pour ce module.

Les classes d'instance suivantes sont disponibles lorsque vous spécifiez différentes options de scaling :

automatic_scaling
Si vous utilisez le scaling automatique, les classes d'instance F1, F2, F4 et F4_1G sont disponibles.
Par défaut : la classe F1 est affectée si vous ne spécifiez pas de classe d'instance à l'aide de l'élément automatic_scaling.
basic_scaling
Si vous utilisez le scaling de base, les classes d'instance B1, B2, B4, B4_1G et B8 sont disponibles.
Par défaut : la classe B2 est affectée si vous ne spécifiez pas de classe d'instance à l'aide de l'élément basic_scaling.
manual_scaling
Si vous utilisez le scaling manuel, les classes d'instance B1, B2, B4, B4_1G et B8 sont disponibles.
Par défaut : la classe B2 est affectée si vous ne spécifiez pas de classe d'instance à l'aide de l'élément manual_scaling.

Remarque : Si instance-class est définie sur F2 ou une version supérieure, vous pouvez optimiser vos instances en définissant max-concurrent-requests sur une valeur supérieure à 10, qui est la valeur par défaut. Pour trouver la valeur optimale, augmentez-la progressivement et surveillez les performances de votre application.

<manual-scaling>

Facultatif. Pour une explication complète, consultez la section relative au scaling manuel.

<precompilation-enabled>

Facultatif. App Engine utilise un processus de "précompilation" avec le bytecode Java d'une application pour améliorer les performances de l'application au sein de l'environnement d'exécution Java. Le code précompilé fonctionne de la même manière que le bytecode d'origine.

Si vous préférez que votre application n'utilise pas la précompilation pour quelque raison que ce soit, vous pouvez la désactiver en ajoutant les lignes suivantes à votre fichier appengine-web.xml :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <precompilation-enabled>false</precompilation-enabled>
  <!-- ... -->
</appengine-web-app>
module

Remarque : Les modules s'appellent à présent services. Toutefois, les services sont toujours déclarés dans les fichiers appengine-web.xml en tant que modules, par exemple : <module>service_name</module>.

Obligatoire si vous créez un service. Facultatif pour le service par défaut. Un nom doit avoir été attribué à chaque service et à chaque version. Il peut contenir des chiffres, des lettres et des traits d'union. Il ne peut pas comporter plus de 63 caractères, et ne peut pas commencer ou se terminer par un trait d'union. Choisissez un nom unique pour chaque service et chaque version. Ne réutilisez pas le même nom pour plusieurs services et versions.

Consultez également l'élément service.

<public-root>

Facultatif. <public-root> est un répertoire de votre application contenant les fichiers statiques de l'application. Lorsqu'une requête visant un fichier statique est envoyée, l'élément <public-root> de votre application est ajouté en préfixe au chemin d'accès de la requête. Cela permet de fournir le chemin d'accès d'un dossier d'application comportant le contenu demandé.

Par défaut, l'élément <public-root> est /.

L'exemple suivant permet de mapper le chemin d'URL /index.html sur le chemin du fichier /static/index.html de l'application :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <public-root>/static</public-root>
  <!-- ... -->
</appengine-web-app>
<resource-files>

Facultatif. Les fichiers répertoriés dans l'élément <resource-files> sont accessibles par le code de l'application à l'aide du système de fichiers. Ces fichiers sont stockés sur les serveurs d'applications avec l'application, contrairement au cas des fichiers statiques concernant leur stockage et leur diffusion.

L'élément <resource-files> peut contenir les éléments suivant :

<include>
Un élément <include> désigne les fichiers en tant que fichiers de ressources et disponibles pour le code de votre application. Ces fichiers ne sont disponibles pour votre code qu'en lecture seule, et non pour la diffusion du trafic. Pour en savoir plus, consultez la section relative à l'inclusion et l'exclusion de fichiers.
<exclude>

Les fichiers et répertoires correspondant aux modèles <exclude> ne seront pas importés ni disponibles dans votre code d'application. Toutefois, ces fichiers et répertoires resteront accessibles à votre application lors de l'exécution sur le serveur de développement local. Pour en savoir plus, consultez la section relative à l'inclusion et l'exclusion de fichiers.

Exemple :

<resource-files>
  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />
</resource-files>

Cet exemple montre comment désigner tous les fichiers .xml en tant que fichiers de ressources, à l'exception de ceux du répertoire feeds/ et de tous ses sous-répertoires.

Les fichiers de ressources App Engine sont lus à l'aide de java.io.File ou de javax.servlet.ServletContext.getResource/getResourceAsStream. Ils ne sont pas accessibles via Class.getResourceAsStream().

runtime

Pour utiliser l'environnement d'exécution Java 8, vous devez spécifier la valeur java8 pour cette entrée. Pour utiliser l'environnement d'exécution Java 7, omettez cette entrée ou spécifiez la valeur java7. Notez que les environnements d'exécution Java pour App Engine sont basés sur OpenJDK.

Exemple :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <runtime>java8</runtime>
  <!-- ... -->
</appengine-web-app>
service

Les services étaient anciennement appelés modules.

Actuellement, seules les commandes gcloud app sont compatibles avec la définition d'un service comme suit : <service>service_name</service >.

<sessions-enabled>

Facultatif. App Engine comprend une mise en œuvre de sessions, à l'aide de l'interface de session du servlet. La mise en œuvre stocke les données de session dans Datastore pour la persistance, et utilise également le memcache pour la rapidité. Au même titre que la plupart des autres conteneurs du servlet, les attributs de session définis à l'aide de "session.setAttribute()" pendant la requête sont conservés à l'issue de cette requête.

Cette fonctionnalité est désactivée par défaut. Pour l'activer, ajoutez ce qui suit à appengine-web.xml :

Exemple :

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <sessions-enabled>true</sessions-enabled>
  <!-- ... -->
</appengine-web-app>

La mise en œuvre crée des entités Datastore de type _ah_SESSION, et des entrées de memcache à l'aide des touches avec le préfixe _ahs. Vous pouvez supprimer ces entités à l'aide du modèle Datastore.

Remarque : App Engine stocke les données de session dans Datastore et le memcache. Toutes les valeurs stockées dans la session doivent donc mettre en œuvre l'interface java.io.Serializable.

Consultez l'élément async-session-persistence pour réduire la latence du stockage des données de session.

<ssl-enabled>

Facultatif. Par défaut, tout utilisateur peut accéder à n'importe quelle URL en utilisant les protocoles HTTP ou HTTPS. Vous pouvez configurer une application de sorte qu'elle exige l'utilisation du protocole HTTPS pour certaines URL dans le descripteur de déploiement. Consultez la section Descripteur de déploiement : URL sécurisées.

Si vous voulez interdire l'utilisation du protocole HTTPS pour l'application, saisissez les lignes suivantes dans le fichier appengine-web.xml :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <ssl-enabled>false</ssl-enabled>
  <!-- ... -->
</appengine-web-app>

Toutefois, dans l'environnement d'exécution Java, il n'est pas possible d'interdire le protocole HTTPS pour certains chemins d'URL seulement.

<static-error-handlers>

Facultatif. Lorsque certaines erreurs se produisent, App Engine diffuse une page d'erreur générique. Vous pouvez configurer votre application de sorte qu'elle diffuse un fichier statique personnalisé au lieu de ces pages d'erreur génériques, tant que les données d'erreur personnalisées sont inférieures à 10 kilo-octets. Vous pouvez configurer différents fichiers statiques à diffuser pour chaque code d'erreur compatible en spécifiant les fichiers dans le fichier appengine-web.xml de votre application. Pour diffuser des pages d'erreur personnalisées, ajoutez une section <static-error-handlers> à votre appengine-web.xml, comme dans l'exemple suivant :


<static-error-handlers>
  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />
</static-error-handlers>

Avertissement : Veillez à ce que le chemin du fichier à diffuser en cas d'erreur ne chevauche pas les chemins vers le gestionnaire de fichiers statiques.

Chaque entrée file indique un fichier statique qui doit être diffusé à la place du message d'erreur générique. L'attribut error-code indique le code d'erreur qui doit entraîner la diffusion du fichier associé. Les codes d'erreur compatibles sont les suivants :

over_quota
Indique que l'application a dépassé un quota de ressources.
dos_api_denial
Cette option diffuse cette page d'erreur à tout client bloqué par la configuration de la protection DoS de votre application.
timeout
Élément diffusé si un délai arrive à expiration avant que votre application ne réponde.

L'attribut error-code est facultatif. S'il n'est pas spécifié, le fichier fourni constitue le message d'erreur par défaut de votre application.

Vous pouvez éventuellement spécifier un élément mime-type à utiliser lors de la diffusion du message d'erreur personnalisé. Consultez la liste complète des types MIME.

<static-files>

Facultatif. L'élément <static-files> spécifie des modèles qui correspondent à des chemins de fichiers à inclure ou exclure de la liste des fichiers statiques, en remplaçant ou modifiant le comportement par défaut. Les fichiers statiques sont diffusés à partir de serveurs et de caches dédiés, distincts des serveurs d'applications, et utiles pour diffuser du contenu statique tel que des images, des feuilles de style CSS ou des fichiers JavaScript.

L'élément <static-files> peut contenir les éléments suivant :

<include>

Un élément <include> remplace le comportement par défaut consistant à inclure tous les fichiers non JSP. L'élément <include> peut spécifier les en-têtes HTTP à utiliser pour répondre à une requête des ressources spécifiées. Pour en savoir plus, consultez la section relative à l'inclusion et l'exclusion de fichiers.

Vous pouvez spécifier le délai d'expiration du cache statique en spécifiant l'attribut expiration sur l'élément "include". La valeur de cet attribut est une chaîne comprenant des paires composées d'un nombre et d'une unité, et séparées par un espace, où l'unité peut être d pour les jours, h pour les heures, m pour les minutes et s pour les secondes. Par exemple, "4d 5h" définit l'expiration du cache 4 jours et 5 heures après la première requête du fichier. Si la valeur d'expiration est omise, elle est définie par défaut sur 10 minutes par le serveur de production. Pour en savoir plus, consultez la section Expiration du cache statique.

<exclude>
Les fichiers et répertoires correspondant aux modèles <exclude> ne sont pas importés lorsque vous déployez votre application vers App Engine. Toutefois, ces fichiers et répertoires resteront accessibles à votre application lors de son exécution sur le serveur de développement local. Pour en savoir plus, consultez la section relative à l'inclusion et l'exclusion de fichiers.
Exemple

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

Facultatif. Le fichier appengine-web.xml peut définir les propriétés système et variables d'environnement qui sont définies lorsque l'application s'exécute.


<system-properties>
  <property name="myapp.maximum-message-length" value="140" />
  <property name="myapp.notify-every-n-signups" value="1000" />
  <property name="myapp.notify-url"
            value="http://www.example.com/signupnotify" />
</system-properties>

<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>
<threadsafe>

Obligatoire. Lorsque l'élément threadsafe dans appengine-web.xml a une valeur false, App Engine envoie des requêtes en série à un serveur Web donné. Lorsque la valeur est true, App Engine peut envoyer plusieurs requêtes en parallèle :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <threadsafe>true</threadsafe>
  <!-- ... -->
</appengine-web-app>

Si vous voulez utiliser des requêtes simultanées, votre code d'application doit utiliser une synchronisation de threads appropriée avant d'activer threadsafe.

<url-stream-handler>

Facultatif. Valeurs possibles, native ou urlfetch. La valeur par défaut et le rôle de ce paramètre varient selon s'il est utilisé avec l'environnement d'exécution Java 8 ou Java 7.

Pour l'environnement d'exécution Java 8, la valeur par défaut est native. Cela signifie que les classes réseau Java standard utilisent le transport HTTP(S) standard pour Java, comme décrit sur la page Comparaison des comportements des environnements Java 8 / Java 7. Ce paramètre nécessite que la facturation soit activée dans l'application. Dans le cas contraire, les requêtes peuvent entraîner les erreurs d'exécution suivantes :

Dans l'environnement d'exécution Java 8, la définition de l'élément url-stream-handler sur urlfetch permet à App Engine d'installer un élément URLStreamHandlerFactory, qui oblige une instance URL.openConnection et les méthodes associées à utiliser le transport de récupération d'URL pour les URL http et https.

Pour l'environnement d'exécution Java 7, la valeur par défaut est urlfetch. Cela signifie que les classes réseau standard pour Java utilisent le service de récupération d'URL, comme décrit sur la page Comparaison des comportements des environnements Java 8 / Java 7.

Dans l'environnement d'exécution Java 7, la définition de la valeur sur native signifie qu'App Engine utilise l'API Sockets pour java.net.HttpURLConnection au lieu de la récupération d'URL. Ce paramètre nécessite que la facturation soit activée dans l'application. Dans le cas contraire, les requêtes peuvent entraîner les erreurs d'exécution suivantes :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>
<version>

L'élément <version> contient l'identifiant de la dernière version du code de l'application. L'identifiant de la version peut contenir des lettres minuscules, des chiffres et des traits d'union. Il ne peut pas commencer par le préfixe "ah-". Les noms "default" et "latest" sont réservés et ne peuvent pas être utilisés.

Les noms des versions doivent commencer par une lettre pour les distinguer des instances numériques qui sont toujours spécifiées par un nombre. Cela évite toute ambiguïté avec les URL comme 123.my-module.appspot.com, qui peuvent être interprétées de deux manières : si la version "123" existe, la cible sera la version "123" du service donné. Si cette version n'existe pas, la cible est le numéro d'instance 123 de la version par défaut du service.

La commande appcfg utilise cet identifiant de version lors de l'importation de l'application, en demandant à App Engine de créer une nouvelle version de l'application avec l'identifiant concerné, ou de remplacer la version de l'application par l'identifiant s'il en existe déjà une. Vous pouvez tester les nouvelles versions de votre application avec une URL en utilisant "-dot-" comme séparateur de sous-domaine dans l'URL, tel que https://_version_id_-dot-_your_app_id_.appspot.com. À l'aide de la console Google Cloud Platform, vous pouvez sélectionner la version par défaut de votre application. La version par défaut est chargée si aucune version n'est spécifiée, ou que la version spécifiée n'est pas valide.

<warmup-requests-enabled>

Facultatif. Valeur par défaut : "true". Les requêtes de préchauffage sont activées par défaut pour les applications Java.

Lorsque les requêtes de préchauffage sont activées, App Engine émet des requêtes GET auprès de /_ah/warmup, initialisant ainsi les servlets <load-on-startup>, le servlet ServletContextListeners, ainsi que les servlets de préchauffage personnalisés. Cela vous permet d'initialiser le code de votre application de la façon requise. Vous devrez peut-être mettre en œuvre votre propre gestionnaire pour /_ah/warmup en fonction de la méthode choisie.

Pour désactiver les requêtes de préchauffage, spécifiez la valeur false pour cet élément, comme suit :


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <warmup-requests-enabled>false</warmup-requests-enabled>
  <!-- ... -->
</appengine-web-app>

Éléments de scaling

Le tableau suivant répertorie les options permettant de définir le type de scaling utilisé pour votre application.

Pour comparer les fonctionnalités de performances des types de scaling, consultez la section Scaling des instances dynamiques.

Élément Description
<automatic-scaling>

Facultatif. Le scaling automatique est défini avec une classe d'instance F1 par défaut, sauf indication contraire.

L'élément automatic_scaling définit des niveaux minimum et maximum pour le nombre d'instances, la latence et les connexions simultanées pour un service.

Cet élément peut contenir les éléments suivants :

<target-cpu-utilization>
Facultatif. Définissez une valeur comprise entre 0,5 et 0,95.

Ce paramètre spécifie le seuil d'utilisation du processeur à partir duquel de nouvelles instances seront démarrées pour gérer le trafic. Vous pourrez ainsi trouver un bon équilibre entre les performances et les coûts. Des valeurs inférieures augmentent les performances et les coûts, et les valeurs supérieures diminuent les performances, mais également les coûts. Par exemple, une valeur de 0,7 signifie que de nouvelles instances sont démarrées après que l'utilisation du processeur a atteint 70 %.

Important : Si vous déployez des applications à l'aide de l'outil appcfg à partir du SDK App Engine, vous ne pouvez pas utiliser ce paramètre dans votre fichier appengine-web.xml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres de scaling automatique dans l'API Explorer, ou à l'aide de l'API App Engine Admin.

<target-throughput-utilization>
Facultatif. Définissez une valeur comprise entre 0,5 et 0,95.

Élément utilisé avec max-concurrent-requests pour spécifier le moment où une nouvelle instance est démarrée en raison de requêtes simultanées. Lorsque le nombre de requêtes simultanées atteint une valeur égale à max-concurrent-requests fois le nombre target-throughput-utilization, le programmeur démarre une nouvelle instance.

Important : Si vous déployez des applications à l'aide de l'outil appcfg à partir du SDK App Engine, vous ne pouvez pas utiliser ce paramètre dans votre fichier appengine-web.xml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres de scaling automatique dans l'API Explorer, ou à l'aide de l'API App Engine Admin.

<max-instances>
Facultatif. Nombre maximal d'instances qu'App Engine peut créer pour cette version de l'application. Cette solution permet de limiter les coûts d'un module. Définissez une valeur comprise entre 0 et 2147483647.

Important : Si vous déployez des applications à l'aide de l'outil "appcfg" à partir du SDK App Engine pour Java, vous ne pouvez pas utiliser ce paramètre dans votre fichier appengine-web.xml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres de scaling automatique dans l'API Explorer, ou à l'aide de l'API App Engine Admin.

<min-instances>
Facultatif. Nombre minimal d'instances qu'App Engine doit créer pour cette version de module. Ces instances diffusent le trafic lorsqu'elles reçoivent des requêtes, et continuent même à le diffuser lorsque des instances supplémentaires sont démarrées pour gérer le trafic.

Définissez une valeur comprise entre 0 et 1 000. Vous pouvez définir la valeur de ce paramètre sur 0 pour autoriser un scaling à zéro instance afin de réduire les coûts lorsqu'aucune requête n'est traitée. Notez que le nombre d'instances spécifiées vous est facturé, qu'elles reçoivent ou non du trafic.

Important : Si vous déployez des applications à l'aide de l'outil "appcfg" à partir du SDK App Engine pour Java, vous ne pouvez pas utiliser ce paramètre dans votre fichier appengine-web.xml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres de scaling automatique dans l'API Explorer, ou à l'aide de l'API App Engine Admin.

<max-concurrent-requests>

Facultatif. Nombre de requêtes simultanées qu'une instance de scaling automatique peut accepter, avant que le programmeur ne génère une nouvelle instance (par défaut : 10, maximum : 80).

Vous risquez de rencontrer des taux de latence plus élevés si la valeur de ce paramètre est trop élevée. Notez que le programmeur peut créer une instance avant que le nombre maximal de requêtes effectif soit atteint.

Remarque : Si l'élément instance-class est défini sur F2 ou une version supérieure, vous pouvez optimiser vos instances en définissant max-concurrent-requests sur une valeur supérieure à 10, qui est la valeur par défaut. Pour trouver la valeur optimale, augmentez-la progressivement et surveillez les performances de votre application.

<max-pending-latency>

Durée maximale pendant laquelle App Engine doit autoriser une requête à rester dans la file d'attente avant de démarrer des instances supplémentaires pour gérer les requêtes, et ainsi réduire le temps de latence. La valeur par défaut est "30ms".

  • Une faible valeur maximale signifie qu'App Engine démarre plus rapidement de nouvelles instances pour les requêtes en attente. Cela améliore les performances, mais augmente les coûts d'exploitation.
  • Une valeur maximale élevée signifie que les utilisateurs peuvent attendre plus longtemps pour que l'application diffuse leur requête (s'il y a des requêtes en attente et qu'aucune instance inactive ne les diffuse), mais l'exécution de votre application est moins coûteuse.
<min-idle-instances>

Nombre d'instances qui doivent rester en cours d'exécution et prêtes à diffuser le trafic. Ce paramètre s'applique uniquement à la version qui reçoit la plus grande partie du trafic. Tenez bien compte des éléments suivants :

  • Une faible valeur minimale permet de limiter vos coûts d'exploitation pendant les périodes d'inactivité, mais signifie qu'un nombre réduit d'instances peut être immédiatement disponible en cas de pic de charge soudain.
  • Une valeur minimale élevée vous permet de préparer l'application aux pics rapides de la charge des requêtes. App Engine conserve le nombre minimal d'instances en cours d'exécution pour diffuser les requêtes entrantes. Le nombre d'instances vous est facturé, qu'elles gèrent des requêtes ou non. Pour veiller au bon fonctionnement de cette fonctionnalité, vous devez vous assurer que les requêtes de préchauffage sont activées et que votre application les gère.

    Si vous définissez un nombre minimal d'instances inactives, le temps de latence a moins d'impact sur les performances de votre application. Étant donné qu'App Engine conserve les instances inactives en réserve, il est peu probable que les requêtes entrent dans la file d'attente, sauf en cas de pics de charge exceptionnellement élevés. Vous devez tester votre application et le volume de trafic prévu pour déterminer le nombre idéal d'instances à garder en réserve.

<min-pending-latency>

Durée minimale en secondes pendant laquelle App Engine doit autoriser une requête à rester dans la file d'attente avant de démarrer une nouvelle instance pour la gérer. Définissez une valeur comprise entre 0,01 et 15.

  • Une faible valeur minimale signifie que les requêtes doivent rester moins longtemps dans la file d'attente lorsque toutes les instances existantes sont actives. Cela améliore les performances, mais augmente le coût d'exécution de votre application.
  • Une valeur minimale élevée signifie que les requêtes restent en attente plus longtemps si toutes les instances existantes sont actives. Cela réduit les coûts d'exploitation, mais augmente le temps que les utilisateurs doivent attendre pour que leurs demandes soient traitées.
Exemple

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>F2</instance-class>
  <automatic-scaling>
    <target-cpu-utilization>0.65</target-cpu-utilization>
    <min-instances>5</min-instances>
    <max-instances>100</max-instances>
    <max-concurrent-requests>50</max-concurrent-requests>
  </automatic-scaling>
</appengine-web-app>
<basic-scaling>

Facultatif. L'élément <basic-scaling> définit le nombre d'instances pour un module.

Cet élément peut contenir les éléments suivants :

<idle-timeout>
Facultatif. L'instance est arrêtée pendant cette période après réception de sa dernière requête. La valeur par défaut est 5 minutes.
<max-instances>
Obligatoire. Nombre maximal d'instances qu'App Engine peut créer pour cette version du module. Cette solution permet de limiter les coûts d'un module.
Exemple

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

Facultatif. L'élément <manual-scaling> active le scaling manuel pour un module et en définit le nombre d'instances.

Cet élément peut contenir les éléments suivants :

<instances>
Nombre d'instances à attribuer au module au démarrage.
Exemple

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Éléments de préproduction

Une grande partie du travail effectué lors d'un déploiement est réalisé localement au cours d'une étape de préparation appelée préproduction, où les fichiers JAR sont assemblés, les fichiers JSP compilés, etc. Si nécessaire, vous pouvez configurer certaines parties du comportement de préproduction, à l'aide des éléments de préproduction présents dans le fichier de configuration de l'application. La plupart des applications seront correctement déployées sans configuration manuelle du comportement de préproduction. Si votre application ne se déploie pas, vous devrez peut-être configurer la préproduction à l'aide des options présentées ci-dessous.

Élément Description
<staging>

Facultatif. Pour la plupart des applications, il n'est pas nécessaire de modifier le comportement par défaut.

L'élément "staging" vous permet de spécifier, si nécessaire, une configuration de préproduction particulière pour le déploiement.

Cet élément peut contenir les éléments suivants :

<enable-jar-splitting>

Facultatif. Divise les fichiers JAR volumineux (supérieurs à 10 mégaoctets) en fragments plus petits. Valeur par défaut : "true".

<jar-splitting-excludes>

Répertorie les suffixes à exclure lors de l'utilisation de la division des fichiers JAR.

<disable_jar_jsps>

Désactive la conversion au format JAR des classes générées à partir des fichiers JSP. Valeur par défaut : "false".

<enable-jar-classes>

Convertit le contenu de WEB-INF/classes au format JAR. Valeur par défaut : "true".

<delete-jsps>

Supprime les fichiers JSP sources après la compilation. Valeur par défaut : "true".

<compile-encoding>

Encode les entrées des fichiers source pour la compilation. Valeur par défaut : utf-8.

Options de préproduction par défaut

Les valeurs par défaut des options de préproduction diffèrent selon que vous utilisez des outils basés sur le SDK App Engine, tels que appcfg, ou sur des outils basés sur le SDK Cloud, tels que l'outil de ligne de commande gcloud, ou les plug-ins Maven, Gradle, Eclipse ou IntelliJ basés sur le SDK Cloud.

Élément de préproduction Valeurs par défaut basées sur le SDK App Engine Valeurs par défaut basées sur le SDK Cloud
enable-jar-splitting false true
jar-splitting-excludes N/A N/A
disable-jar-jsps false false
enable-jar-classes false true. Cet élément peut influencer l'ordre de chargement des classes. Si votre application dépend d'un certain ordre utilisant l'ancienne valeur par défaut false, vous pouvez donc définir cet élément sur false.
delete-jsps false true
compile-encoding utf-8 utf-8

Inclure et exclure la syntaxe

Les modèles de chemin d'accès sont spécifiés à l'aide des éléments <include> et <exclude>. Dans un format, '*' représente de zéro à plusieurs caractères dans un nom de fichier ou de répertoire, tandis que ** représente de zéro à plusieurs répertoires dans un chemin d'accès. Les fichiers et répertoires correspondant aux modèles <exclude> ne sont pas importés lorsque vous déployez votre application vers App Engine. Toutefois, ces fichiers et répertoires resteront accessibles à votre application lors de son exécution sur le serveur de développement local.

Un élément <include> remplace le comportement par défaut d'inclusion de tous les fichiers. Un élément <exclude> s'applique après tous les modèles <include> (ainsi que la valeur par défaut si aucun <include> explicite n'est fourni).

L'exemple suivant illustre comment désigner tous les fichiers .png comme des fichiers statiques (sauf ceux dans le répertoire data/ et l'ensemble de ses sous-répertoires) :

<static-files>
  <include path="/**.png" />
  <exclude path="/data/**.png" />
</static-files>

Vous pouvez également définir les en-têtes HTTP à utiliser pour répondre aux requêtes adressées à ces ressources statiques.

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>

Types MIME pour les fichiers statiques

Par défaut, les fichiers statiques sont diffusés à l'aide d'un type MIME sélectionné en fonction de l'extension du nom de fichier. Vous pouvez associer des types MIME personnalisés à des extensions de nom de fichier pour des fichiers statiques, à l'aide d'éléments <mime-mapping> dans web.xml. Pour en savoir plus, consultez le wiki de référence sur Metawerx web.xml.

Expiration du cache statique

Sauf indication contraire, les proxys et navigateurs Web conservent les fichiers qu'ils chargent à partir d'un site Web pendant une durée limitée.

Vous pouvez configurer une durée de cache pour des gestionnaires de fichiers statiques spécifiques en fournissant un attribut expiration à <static-files><include ... >. La valeur de cet attribut est une chaîne comprenant des paires composées d'un nombre et d'une unité, et séparées par un espace, où l'unité peut être d pour les jours, h pour les heures, m pour les minutes et s pour les secondes. Par exemple, "4d 5h" définit l'expiration du cache 4 jours et 5 heures après la première requête du fichier. Si la valeur d'expiration est omise, elle est définie par défaut sur 10 minutes par le serveur de production.

Exemple :

<static-files>
  <include path="/**.png" expiration="4d 5h" />
</static-files>

Le délai d'expiration est envoyé dans les en-têtes de réponse HTTP Cache-Control et Expires. Par conséquent, les fichiers sont susceptibles d'être mis en cache par le navigateur de l'utilisateur, ainsi que par des serveurs proxy de mise en cache intermédiaires, tels que les fournisseurs d'accès à Internet. Une fois un fichier transmis avec un délai d'expiration donné, il n'existe généralement aucun moyen de le supprimer des caches intermédiaires, même si l'utilisateur efface le cache de son propre navigateur. Le redéploiement d'une nouvelle version de l'application ne permet pas de réinitialiser les caches. Par conséquent, si vous avez l'intention de modifier un fichier statique, il doit posséder un délai d'expiration court (moins d'une heure). Le délai d'expiration par défaut de 10 minutes convient dans la plupart des cas.

Délai avant expiration des requêtes URLFetch

Vous pouvez définir une durée maximale pour chaque requête URLFetch. Par défaut, la durée maximale pour une récupération est de 5 secondes. Vous pouvez modifier cette valeur par défaut en incluant le paramètre suivant dans votre fichier de configuration appengine-web.xml. Spécifiez le délai avant expiration en secondes :

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Environnement standard App Engine pour Java