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

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

Vous ne devez utiliser le fichier appengine-web.xml pour configurer votre application que si vous migrez une application existante de l'environnement d'exécution Java 8 d'App Engine vers la dernière version Java compatible et que vous souhaitez utiliser l'ancienne version services groupés. Si vous utilisez un appengine-web.xml dans votre projet, le fichier app.yaml est automatiquement généré lors du déploiement.

Les applications Java App Engine utilisent un fichier de configuration nommé appengine-web.xml pour spécifier les informations concernant 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.

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
`<application>`	Non obligatoire si vous déployez votre application à l'aide d'outils basés sur le SDK Google Cloud, tels 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 Google 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 du 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 Google Cloud Console.
`<app-engine-apis>`	Facultatif. Si vous souhaitez utiliser les anciens services groupés App Engine pour des environnements d'exécution de deuxième génération, définissez ce champ sur `true`.
`<entrypoint>`	Facultatif et uniquement pour les environnements d'exécution de deuxième génération. Remplace le point d'entrée par défaut, qui est la ligne de commande du processus qui démarre l'application Java. Par défaut, l'entrypoint généré pour une classe d'instance F4 (les paramètres de mémoire sont calculés à partir de la classe d'instance) équivaut à la configuration suivante : <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <entrypoint> java -showversion -Xms32M -Xmx819M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED --add-opens java.logging/java.util.logging=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime </entrypoint> </appengine-web-app> Vous pouvez modifier la configuration pour ajouter des indicateurs de processus JVM supplémentaires ou définir votre propre processus de démarrage. Notez que l'application est déployée dans le répertoire `/workspace`, et que les fichiers JAR de l'environnement d'exécution se trouvent dans le répertoire `/base/java_runtime`. Découvrez comment personnaliser le point d'entrée de l'environnement d'exécution Java à l'aide de variables d'environnement.
`<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 : <async-session-persistence enabled="true" /> 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 : <async-session-persistence enabled="true" queue-name="myqueue"/> 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, 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` : <precompilation-enabled>false</precompilation-enabled>
`<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 : <public-root>/static</public-root>
`<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 la dernière version Java compatible, vous devez spécifier cette entrée avec la valeur `java21`. Exemple : <runtime>java21</runtime>
`<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 : <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account>
`<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 : <sessions-enabled>true</sessions-enabled> 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` : <ssl-enabled>false</ssl-enabled> 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> Facultatif. Vous pouvez configurer un connecteur HTTP pour améliorer l'utilisation du processeur et de la mémoire. <system-properties> <property name="appengine.use.httpconnector" value="true"/> </system-properties> À partir de Java 21, vous pouvez configurer votre serveur Web Java pour qu'il utilise des threads virtuels. Exemple : <system-properties> <property name="appengine.use.virtualthreads" value="true"/> </system-properties> Pour en savoir plus sur la compatibilité avec les threads, consultez la page Jetty 12 : Compatibilité avec les threads virtuels.
`<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`. <url-stream-handler>urlfetch</url-stream-handler>
`<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.
`<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>`, `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 : <warmup-requests-enabled>false</warmup-requests-enabled>
`<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. Spécifiez le nom complet d'un connecteur dans l'élément `<name>` : <vpc-access-connector> <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name> </vpc-access-connector> Pour en savoir plus, consultez la page Se connecter aux ressources internes d'un réseau VPC.

É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

É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> <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> <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> <instance-class>B8</instance-class> <manual-scaling> <instances>5</instances> </manual-scaling> </appengine-web-app>

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

É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 : "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. Exemple : <staging> <delete-jsps>false</delete-jsps> </staging>

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

Exemple :

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

Options de préproduction par défaut

Les valeurs par défaut pour les options de préproduction diffèrent selon que vous utilisez des outils basés sur Google Cloud SDK, tels que la gcloud CLI, ou les plug-ins basés sur Google Cloud SDK Maven, Gradle, Eclipse ou IntelliJ.

É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 Google Cloud
`enable-jar-splitting`	`false`	`true`
`jar-splitting-excludes`	NA	NA
`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

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>