Documentation de référence du fichier appengine-web.xml dans App Engine

ID de la région

Le REGION_ID est un code abrégé que Google attribue en fonction de la région que vous sélectionnez lors de la création de votre application. Le code ne correspond pas à un pays ou une province, même si certains ID de région peuvent ressembler aux codes de pays et de province couramment utilisés. Pour les applications créées après février 2020, REGION_ID.r est inclus dans les URL App Engine. Pour les applications existantes créées avant cette date, l'ID de région est facultatif dans l'URL.

En savoir plus sur les ID de région

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) dans le fichier WAR de l'application ainsi que les fichiers de ressources utilisés par l'application.

Exemple

L'exemple suivant est un fichier minimal spécifiant l'environnement d'exécution Java 8 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">
  <threadsafe>true</threadsafe>
  <runtime>java8</runtime>
</appengine-web-app>

Syntaxe

Toute application Java App Engine doit comporter un fichier appengine-web.xml dans son fichier d'archives WAR, dans le répertoire WEB-INF/. Il s'agit d'un fichier XML dont l'élément racine est <appengine-web-app>.

Vous trouverez la définition du type de document et les spécifications de schéma du fichier appengine-web.xml dans le répertoire docs/ du SDK.

Élément Description
<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 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 à terme 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 8, 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 e-mails.
<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 valeur F1 est affectée si vous ne spécifiez pas de classe d'instance avec 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 l'élément instance-class est défini sur F2 ou une valeur 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, pour une raison quelconque, vous préférez que votre application n'utilise pas la précompilation, il vous est possible de la désactiver en insérant le code suivant dans le 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 sont maintenant appelés services et 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, commencer ou se terminer par un trait d'union ni contenir la chaîne "-dot". Choisissez un nom unique pour chaque service et chaque version. N'utilisez pas le même nom pour plusieurs services ou 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é.

La valeur <public-root> par défaut 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.

Un élément <resource-files> peut contenir les éléments suivants :

<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 sur l'inclusion et l'exclusion de fichiers.
<exclude>

Les fichiers et répertoires correspondant aux formats <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 sur 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 cette entrée avec la valeur java8.

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 >.
service-account

Facultatif. L'élément service-account vous permet de spécifier un compte de service géré par l'utilisateur en tant qu'identité de la version. Le compte de service spécifié sera utilisé pour accéder à d'autres services Google Cloud et pour exécuter des tâches.

Exemple : 
<?xml version="1.0" encoding="utf-8"?>
 <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
   <!-- ... -->
   <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account>
   <!-- ... -->
 </appengine-web-app>
<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, entrez le code suivant dans le fichier 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>

L'implémentation crée des entités Datastore de type _ah_SESSION et des entrées de memcache à l'aide de clés 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 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 savoir comment réduire la latence du stockage des données de session.
<ssl-enabled>

Facultatif. Par défaut, un utilisateur peut accéder à n'importe quelle URL via HTTP ou HTTPS. À l'aide du fichier descripteur de déploiement, vous pouvez configurer une application de manière à forcer l'utilisation du protocole HTTPS pour certaines URL. Consultez la section Descripteur de déploiement : URL sécurisées.

Pour interdire l'utilisation du protocole HTTPS pour l'application, insérez le code suivant 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 la diffusion de fichiers statiques différents pour chaque code d'erreur pris en charge, en les spécifiant dans le fichier appengine-web.xml de votre application. Pour diffuser des pages d'erreur personnalisées, ajoutez une section <static-error-handlers> à votre fichier 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.
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 affiché par 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 formats 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.

Un élément <static-files> peut contenir les éléments suivants :

<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 sur l'inclusion et l'exclusion de fichiers.

Vous pouvez ignorer le délai d'expiration du cache statique par défaut en spécifiant l'attribut expiration sur l'élément d'inclusion ("include"). La valeur correspond à une chaîne de nombres et d'unités, séparés par des espaces, où les unités possibles sont 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 sur une durée de quatre jours et cinq heures après la première requête du fichier. Pour en savoir plus, consultez la section Délai d'expiration du cache.

<exclude>
Les fichiers et répertoires correspondant aux formats <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 sur 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 permet d'indiquer les propriétés système et les variables d'environnement définies lors de l'exécution de l'application. 

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

Cet élément n'est pas compatible dans les environnements d'exécution Java 11 ou ultérieurs.

<url-stream-handler>

Facultatif. Les valeurs possibles sont native ou urlfetch.

La valeur par défaut est native, ce qui signifie que les classes réseau Java standards utilisent le transport HTTP(S) standard pour Java. Pour utiliser ce paramètre, vous devez activer la facturation pour votre application, ou vous obtiendrez des exceptions. Ces exceptions sont décrites sur la page Émettre des requêtes.

Si vous définissez url-stream-handler sur urlfetch, URL.openConnection et les méthodes associées utiliseront la récupération d'URL pour le transport http et https.

<?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 version correspondant à la dernière version du code d'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.uc.r.appspot.com, qui peuvent être interprétées de deux manières : si la version "123" existe, la cible sera la version "123" du module donné. Si cette version n'existe pas, la cible est le numéro d'instance 123 de la version par défaut du service.

App Engine utilise cet identifiant de version pour déterminer s'il convient 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, par exemple https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com. À l'aide de la console Google Cloud, 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 8.

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>, 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 implémenter 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>
<vpc-access-connector>

Facultatif. Configure votre application pour utiliser un connecteur d'accès au VPC sans serveur afin d'envoyer des requêtes à des ressources internes du réseau VPC. Pour en savoir plus, consultez Se connecter à un réseau VPC.

name
Spécifiez le nom complet de votre connecteur d'accès au VPC sans serveur : 
projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME
egress-setting
Facultatif. La valeur par défaut est private-ranges-only. L'élément egress-setting peut avoir l'une des valeurs suivantes :
private-ranges-only
Valeur par défaut. Les requêtes adressées aux adresses IP internes sont envoyées via le connecteur d'accès au VPC sans serveur vers le réseau VPC connecté. Les requêtes adressées à des adresses IP externes sont envoyées à l'Internet public.
all-traffic
Toutes les requêtes sont envoyées via le connecteur d'accès au VPC sans serveur vers le réseau VPC connecté.
Exemple 
<vpc-access-connector>
  <name>projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME</name>
  <egress-setting>all-traffic</egress-setting>
</vpc-access-connector>

Éléments de scaling

Le tableau suivant répertorie les options permettant de définir le type de scaling de 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 module.

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 lorsque l'utilisation du processeur atteint 70 %.

<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 multiplié par target-throughput-utilization, le programmeur démarre une nouvelle instance.

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

Spécifiez une valeur comprise entre 0 et 1 000. Vous pouvez définir le paramètre sur la valeur 0 pour permettre la mise à l'échelle de 0 instances afin de réduire les coûts lorsqu'aucune requête n'est diffusée. Notez que le nombre d'instances spécifié vous est facturé, qu'elles reçoivent ou non du trafic.

<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 valeur 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-idle-instances>

Nombre maximal d'instances inactives qu'App Engine doit gérer pour cette version. La valeur par défaut est définie sur "automatique". Tenez bien compte des éléments suivants :

  • Une valeur maximale élevée réduit le nombre d'instances inactives de manière plus progressive lorsque les niveaux de charge reviennent à la normale après un pic. Votre application peut ainsi maintenir des performances constantes grâce aux fluctuations de la charge des requêtes. En revanche, cela augmente également le nombre d'instances inactives (et les coûts d'exploitation qui en découlent) pendant les périodes de charges importantes.
  • Une valeur maximale faible réduit les coûts d'exploitation, mais peut dégrader les performances en présence de niveaux de charge instables.

Remarque : Lorsque vous revenez à des niveaux normaux après un pic de charge, le nombre d'instances inactives peut temporairement dépasser la valeur maximale spécifiée. Cependant, le nombre d'instances qui vous sera facturé ne pourra pas dépasser le nombre maximal spécifié.

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

  • 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 délai de diffusion des requêtes, et donc le temps d'attente des utilisateurs.
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 de 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>

Spécifie une liste de suffixes de fichiers séparés par une virgule. Si enable-jar-splitting est activé, tous les fichiers qui correspondent aux suffixes sont exclus de tous les 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 : "false".

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

Exemple :

        <staging>
          <delete-jsps>false</delete-jsps>
        </staging>

Options de préproduction par défaut

Les valeurs par défaut des options de préproduction sont les suivantes :

Élément de préproduction Valeur par défaut
enable-jar-splitting true
jar-splitting-excludes NA
disable-jar-jsps false
enable-jar-classes true. Cet élément peut influencer l'ordre de chargement des classes. Si votre application dépend d'un certain ordre, définissez-le sur false.
delete-jsps true
compile-encoding utf-8

Inclure et exclure la syntaxe

Le format des chemins d'accès est défini à 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 formats <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.

L'élément <include> se substitue au comportement par défaut, à savoir l'inclusion de tous les fichiers. L'élément <exclude> s'applique à la fin de tous les formats <include> (ainsi que de la valeur par défaut si aucun élément <include> explicite n'est fourni).

L'exemple ci-dessous montre comment définir l'ensemble des fichiers .png en tant que fichiers statiques (à l'exception de ceux situés dans le répertoire data/ et 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 des éléments <mime-mapping> dans web.xml.

Délai avant expiration des requêtes URLFetch

Vous pouvez définir un délai pour chaque requête URLFetch. Par défaut, le délai 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>