Documentation de référence sur le fichier app.yaml

Le fichier app.yaml permet de configurer les paramètres de votre application App Engine. Il fait correspondre les chemins d'URL avec les gestionnaires de requêtes et les fichiers statiques. Le fichier app.yaml contient également des informations sur le code de l'application, telles que l'environnement d'exécution et l'identifiant de la version la plus récente.

Chaque service de l'application possède son propre fichier app.yaml, qui joue le rôle de descripteur pour son déploiement. Vous devez d'abord créer le fichier app.yaml pour le service default afin de pouvoir créer et déployer des fichiers app.yaml pour des services supplémentaires dans l'application.

Structure des répertoires

Chaque service doit disposer d'un fichier app.yaml dans son répertoire racine. Pour savoir comment structurer plusieurs services dans votre application, consultez la page Structurer des services Web dans App Engine.

Exemple

Voici un exemple de fichier app.yaml pour une application PHP :

runtime: python27
api_version: 1
threadsafe: true

handlers:
- url: /
  script: home.app

- url: /index\.html
  script: home.app

- url: /stylesheets
  static_dir: stylesheets

- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

- url: /admin/.*
  script: admin.app
  login: admin

- url: /.*
  script: not_found.app

Une instruction script: peut contenir un chemin de fichier se terminant par .py, ce qui signifie que le script utilise CGI, ou un chemin de module Python, avec des noms de packages séparés par des points, ce qui signifie que le script utilise WSGI.

Syntaxe

La syntaxe du fichier app.yaml est au format YAML.

Le format YAML accepte les commentaires. Les lignes commençant par le caractère dièse (#) sont ignorées :

# This is a comment.

Les formats d'URL et de chemin d'accès au fichier utilisent la syntaxe d'expressions régulières POSIX étendue, à l'exception des éléments classés et des classes utilisées pour les classements. Les références arrières aux correspondances groupées, telles que \1, sont compatibles, de même que les extensions Perl suivantes : \w \W \s \S \d \D.

Éléments de l'environnement d'exécution et d'application

Élément Description
application

L'approche recommandée pour spécifier votre ID d'application consiste à supprimer l'élément application de votre fichier app.yaml et à le remplacer par un indicateur de ligne de commande :

  • Pour exécuter la commande gcloud app deploy, vous devez spécifier l'indicateur --project :
    
    gcloud app deploy --project [YOUR_PROJECT_ID]
  • Pour exécuter la commande appcfg.py update, spécifiez l'indicateur -A :
    
    appcfg.py update -A [YOUR_PROJECT_ID]

Pour plus d'informations sur l'utilisation de ces commandes, consultez la page Déployer votre application.

L'ID application est l'ID de console GCP du projet que vous avez indiqué lors de la création de l'application dans la console Google Cloud Platform.

api_version

Obligatoire. La version de l'API dans l'environnement d'exécution donné utilisée par votre application.

Lorsque Google annonce la compatibilité avec une nouvelle version de l'API d'un environnement d'exécution, votre application déployée continue à utiliser celle pour laquelle elle a été écrite. Pour mettre à niveau votre application vers une nouvelle version de l'API, modifiez cette valeur, puis redéployez votre application sur App Engine. Lorsque vous définissez la valeur 1, le dernier environnement d'exécution compatible est utilisé dès que vous déployez cette application (actuellement, ).

Pour le moment, App Engine dispose d'une seule version de l'environnement d'exécution python27 : la version 1.

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

Facultatif. Le SDK Python contient un certain nombre de gestionnaires intégrés pour les fonctions d'application courantes. La directive builtins permet d'inclure des gestionnaires spécifiques dans le fichier app.yaml.

Vous pouvez utiliser les gestionnaires intégrés suivants :

appstats
Active les statistiques d'application à /_ah/stats/, que vous pouvez utiliser pour mesurer les performances de votre application. Pour utiliser les statistiques d'application, vous devez également installer l'enregistreur d'événements.
deferred
Active le gestionnaire différé à /_ah/queue/deferred. Il permet aux développeurs d'utiliser deferred.defer() pour simplifier la création de tâches dans la file d'attente de tâches. Voir également Exécuter des tâches en arrière-plan à l'aide de la bibliothèque différée.
remote_api
Active le gestionnaire intégré remote_api à /_ah/remote_api/. Ce gestionnaire intégré (builtin) permet aux applications distantes ayant les identifiants appropriés d'accéder au datastore à distance.
Exemple :

builtins:
- deferred: on
- appstats: on

L'instruction builtins est une instance spéciale de la directive includes. Chaque instruction builtin est l'équivalent, en Python, à une instruction includes avec un chemin élargi. Exemple :


builtins:
- name: on

Est équivalent à :


includes:
- $PYTHON_LIB/google/appengine/ext/builtins/name/

Lorsque vous utilisez des clauses builtins dans votre fichier app.yaml, tous les gestionnaires définis dans le fichier include.yaml intégré remplacent les gestionnaires que vous définissez dans votre fichier app.yaml. Toutefois, si vous incluez un fichier qui utilise ensuite les clauses builtins ou includes, les gestionnaires sont ajoutés par ordre de la hiérarchie d'inclusion. Autrement dit, les gestionnaires de l'inclusion "parent" sont ajoutés avant l'intégration des inclusions "enfant", et ainsi de suite.

Prenons l'exemple du fichier app.yaml suivant, qui utilise les gestionnaires appstats intégrés :


handlers:
- url: /.*
  script: main.app
builtins:
- appstats: on

La liste de gestionnaires qui en résulte est la suivante :


[/_ah/stats, /.*]

Si le fichier app.yaml utilise une instruction d'inclusion :


includes:
- included.yaml

Et le fichier included.yaml utilise une clause builtins :


handlers:
- url: /.*
  script: main.app
builtins:
- appstats: on

La liste de gestionnaires qui en résulte est alors :


[/.*, /_ah/stats]

La position de la clause builtins dans un fichier .yaml ne modifie pas le comportement.

default_expiration

Facultatif. Définit une durée de mise en cache globale par défaut pour tous les gestionnaires de fichiers statiques d'une application. Vous pouvez également configurer une durée de mise en cache pour des gestionnaires de fichiers statiques spécifiques. La valeur est une chaîne de nombres et d'unités, séparés par des espaces. 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 à quatre jours et cinq heures après la première requête sur ce fichier. Si cette valeur n'est pas définie, le serveur de production définit le délai d'expiration sur 10 minutes.

Exemple :

runtime: python27
api_version: 1
threadsafe: true

default_expiration: "4d 5h"

handlers:
# ...

Pour plus d'informations, consultez la section Expiration du cache statique.

env_variables

Facultatif. Vous pouvez définir des variables d'environnement dans le fichier app.yaml pour qu'elles soient disponibles dans votre application.

L'utilisation des variables d'environnement dont le préfixe est GAE est réservée au système. Ces variables ne sont pas autorisées dans le fichier app.yaml.

Ces variables seront disponibles dans le dictionnaire os.environ :

env_variables:
  DJANGO_SETTINGS_MODULE: 'myapp.settings'
error_handlers

Facultatif. Permet de configurer les pages d'erreur personnalisées qui s'affichent pour différents types d'erreurs.

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

error_code
Facultatif. L'élément error_code peut avoir l'une des valeurs suivantes :
over_quota
Indique que l'application a dépassé le quota d'une ressource.
dos_api_denial
Indique que la requête a été bloquée 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 affiché par votre application.

file
Chaque entrée "file" indique un fichier statique qui doit être diffusé à la place du message d'erreur générique. Si vous spécifiez un élément file sans élément error_code correspondant, le fichier statique constitue la page d'erreur par défaut de l'application. Les données d'erreur personnalisées doivent être inférieures à 10 kilo-octets.
Exemple

error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html
handlers

Obligatoire. Liste de formats d'URL, avec la description de leurs modes de gestion. Pour gérer les URL, App Engine peut exécuter le code de l'application ou diffuser des fichiers statiques importés avec le code, tels que des images, des fichiers CSS ou des fichiers JavaScript.

Voir la syntaxe de l'élément "handlers" et des sous-éléments

includes

Facultatif. L'instruction includes vous permet d'inclure le fichier de configuration d'une bibliothèque ou d'un service de votre application. Par exemple, vous pouvez inclure une bibliothèque d'administration des utilisateurs comme suit :


includes:
- lib/user_admin.yaml

App Engine résout le chemin d'accès inclus dans l'ordre suivant :

  • Chemin d'accès absolu ou relatif au répertoire de travail. Le chemin d'accès indiqué pointe vers un fichier.
  • Chemin d'accès relatif au répertoire de l'application, également appelé chemin de base. Le chemin de base et le chemin d'accès aboutissent à un fichier.
  • En fonction du fichier qui comprenait le fichier actuel. L'emplacement du fichier de référence et le chemin d'inclusion pointent vers le fichier inclus.

Si l'instruction include spécifie un répertoire, App Engine recherche un fichier appelé include.yaml dans ce répertoire. Si elle correspond à un fichier, ce fichier spécifique est inclus. L'instruction includes ne récupère que les types d'instructions ci-dessous à partir du fichier de destination (le cas échéant) :

Les formats skip_files inclus sont ajoutés à ceux du fichier app.yaml ou à la liste par défaut si app.yaml ne contient pas de liste explicite. Notez que les formats skip_files comparent les chemins absolus.

inbound_services

Facultatif. Les applications doivent activer ces services pour pouvoir recevoir des requêtes entrantes. Pour activer le service dans une application Python, vous pouvez inclure une section inbound_services dans le fichier app.yaml.

Les services entrants suivants sont disponibles :

mail
Permet à votre application de recevoir des messages.
warmup
Active les requêtes de préchauffage. Consultez la page Configurer des requêtes de préchauffage.
Exemple :

inbound_services:
  - mail
  - warmup
instance_class

Facultatif. Classe d'instance de ce service.

Les valeurs suivantes sont disponibles en fonction du scaling de votre service :

Autoscaling
F1, F2, F4, F4_1G
Valeur par défaut : F1 est affecté si vous ne spécifiez pas de classe d'instance avec l'élément automatic_scaling.
Scaling de base et scaling manuel
B1, B2, B4, B4_1G, B8
Valeur par défaut : B2 est affecté si vous ne spécifiez pas de classe d'instance avec l'élément basic_scaling ou manual_scaling.

Remarque : Si l'élément instance_class est défini sur F2 ou une valeur supérieure, vous pouvez optimiser les 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.

libraries

Facultatif. Le moteur d'exécution Python 2.7 utilise des bibliothèques tierces. Certaines d'entre elles sont disponibles par défaut, tandis que d'autres ne sont disponibles que si elles sont configurées. Vous pouvez indiquer la version que vous souhaitez utiliser en spécifiant les valeurs name et version.


libraries:
- name: PIL
  version: "1.1.7"
- name: webob
  version: "latest"
        

Notez que lorsque vous indiquez latest, le SDK détermine la dernière version de la bibliothèque au moment du déploiement. Une fois déployée, la version de la bibliothèque ne changera pas. Le seul moyen d'obtenir une version différente de la bibliothèque est de le déployer à nouveau.

Si vous développez une application qui n'a pas encore d'utilisateurs, vous n'avez pas besoin de suivre les nouvelles versions. En revanche, soyez prudent si votre application est utilisée activement. Vous pourriez être surpris de découvrir que votre application commence à utiliser une nouvelle version de bibliothèque non compatible avec les versions antérieures.

Pour obtenir une liste des bibliothèques tierces incluses, consultez la section Bibliothèques tierces. Vous pouvez utiliser des bibliothèques tierces supplémentaires en Python pur en les installant dans un répertoire local.

Si vous utilisez l'environnement flexible, consultez la section Utiliser des bibliothèques Python dans l'environnement flexible.

module

Remarque : Les modules sont maintenant appelés "services".

Pour gérer votre application avec l'outil gcloud, utilisez plutôt l'élément service.

Pour utiliser l'outil appcfg, les services doivent être déclarés dans les fichiers app.yaml en tant que modules. Exemple :


module: service-name

Obligatoire si vous créez un service. Facultatif pour le service default. Un nom doit avoir été attribué à chaque service et à chaque version. Il peut contenir des chiffres, des lettres et des traits d'union. La durée combinée du service et de la version ne peut pas comporter plus de 63 caractères, et ne peut pas commencer ni 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.

runtime

Obligatoire. Nom de l'environnement d'exécution utilisé par votre application. Pour Python 2.7, utilisez :


runtime: python27
service

Les services étaient anciennement appelés "modules".

Compatible seulement avec l'outil gcloud ou les plug-ins basés sur le SDK Cloud. Exemple : gcloud app deploy.

Pour utiliser l'outil appcfg, consultez la description du paramètre module.

Obligatoire si vous créez un service. Facultatif pour le service default. Un nom doit avoir été attribué à chaque service et à chaque version. Il peut contenir des chiffres, des lettres et des traits d'union. La durée combinée du service et de la version ne peut pas comporter plus de 63 caractères, et ne peut pas commencer ni 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.

Exemple :

service: service-name

Remarque : La commande gcloud app deploy est rétrocompatible et accepte les fichiers app.yaml existants comprenant des services déclarés en tant que modules. Exemple :


module: service-name
skip_files

Facultatif. L'élément skip_files indique les fichiers du répertoire de l'application qui ne doivent pas être importés dans App Engine. Sa valeur correspond soit à une expression régulière, soit à une liste d'expressions régulières. Tout nom de fichier correspondant à l'une des expressions régulières est omis de la liste des fichiers à importer lors du transfert de l'application. Les noms de fichiers sont relatifs au répertoire du projet.

L'élément skip_files dispose des expressions régulières suivantes par défaut :


skip_files:
- ^(.*/)?#.*#$
- ^(.*/)?.*~$
- ^(.*/)?.*\.py[co]$
- ^(.*/)?.*/RCS/.*$
- ^(.*/)?\..*$

Le format par défaut exclut les fichiers de sauvegarde Emacs ayant des noms sous la forme #...# et ...~, les fichiers .pyc et .pyo, les fichiers d'un répertoire de contrôle des révisions RCS, ainsi que les fichiers cachés Unix dont le nom commence par un point (.).

Pour ajouter des entrées à la liste des expressions régulières ci-dessus, faites-en un copier-coller dans votre fichier app.yaml, puis ajoutez vos propres expressions régulières. Par exemple, pour ignorer les fichiers dont le nom se termine par .bak en plus des formats par défaut, ajoutez une entrée à l'élément skip_files comme suit :


skip_files:
- ^(.*/)?#.*#$
- ^(.*/)?.*~$
- ^(.*/)?.*\.py[co]$
- ^(.*/)?.*/RCS/.*$
- ^(.*/)?\..*$
- ^(.*/)?.*\.bak$

Pour ignorer un répertoire complet, ajoutez son nom à la liste. Par exemple, pour ignorer un répertoire nommé logs, ajoutez la ligne suivante à celles décrites précédemment :


skip_files:
- logs/
threadsafe

Obligatoire. Configure votre application pour utiliser des requêtes simultanées. Si vous utilisez la bibliothèque threading de Python, les données thread locales telles qu'affichées par threading.local() sont effacées après chaque requête.


threadsafe: [true | false]

Remarque : L'instruction threadsafe est requise pour les applications Python 2.7. threadsafe: true exige que tous les gestionnaires de script soient des gestionnaires WSGI. Autrement dit, chaque script doit être spécifié dans une instruction script: avec le chemin du module Python, en séparant les noms de packages par des points. Le dernier composant d'une instruction script: utilisant un chemin de module Python est le nom d'une variable globale du service:. Cette variable doit être une application WSGI et est généralement appelée app par convention.

version

L'approche recommandée pour spécifier votre ID de version consiste à supprimer l'élément version de votre fichier app.yaml et à le remplacer par un indicateur de ligne de commande :

  • Pour exécuter la commande gcloud app deploy, spécifiez l'indicateur -v :
    
    gcloud app deploy -v [YOUR_VERSION_ID]
  • Pour exécuter la commande appcfg.py update, spécifiez l'indicateur -V :
    
    appcfg.py update -V [YOUR_VERSION_ID]

Pour plus d'informations sur l'utilisation de ces commandes, consultez la page Déployer votre application.

Identifiant de la version du code d'application que vous déployez sur App Engine.

L'ID de 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 étant réservés, ils ne peuvent pas être utilisés.

Remarque : 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-service.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.

Chaque version d'une application conserve sa propre copie du fichier app.yaml. Lors du transfert d'une application, la version mentionnée dans le fichier app.yaml en cours d'importation est la version créée ou remplacée par l'importation. Un administrateur peut modifier la version de l'application qui diffuse le trafic à l'aide de la console Google Cloud Platform. Il peut également tester d'autres versions avant de les configurer pour recevoir du trafic.

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 le champ name :


vpc_access_connector:
  name: "projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]"

Pour en savoir plus, consultez la page Se connecter aux ressources internes d'un réseau VPC.

Élément "handlers"

L'élément handlers est obligatoire dans le fichier de configuration app.yaml. Il fournit une liste de formats d'URL et des descriptions pour apprendre à les gérer. Pour gérer les URL, App Engine peut exécuter le code d'application ou diffuser les fichiers statiques transférés avec le code, tels que des fichiers image, CSS ou JavaScript.

Les formats sont évalués dans l'ordre indiqué dans le fichier app.yaml, de haut en bas. Le premier mappage dont le format correspond à l'URL est employé pour gérer la requête.

Le tableau suivant répertorie les sous-éléments de l'élément handlers qui contrôlent le comportement des scripts, des fichiers statiques, des répertoires statiques et d'autres paramètres.

Élément Description
application_readable Facultatif. Valeur booléenne. Par défaut, les fichiers déclarés dans les gestionnaires de fichiers statiques sont importés en tant que données statiques et sont seulement diffusés auprès des utilisateurs finaux. Ils ne peuvent pas être lus par une application. Si ce champ est défini sur "true", les fichiers sont également importés en tant que données de code pour que votre application puisse les lire. Les deux importations sont imputées aux quotas des ressources de stockage de votre code et de vos données statiques.
auth_fail_action

Facultatif. Décrit l'action entreprise lorsque l'élément login est spécifié pour un gestionnaire et que l'utilisateur n'est pas connecté. Le paramètre accepte les deux valeurs suivantes :

redirect
C'est la valeur par défaut. L'utilisateur est redirigé vers la page de connexion Google ou vers /_ah/login_required si l'authentification OpenID est utilisée. Après sa connexion ou la création d'un compte, l'utilisateur est redirigé vers l'URL de l'application.
unauthorized
La requête est rejetée avec l'affichage d'un code d'état HTTP 401 et d'un message d'erreur.

Si une application nécessite un comportement différent, elle peut elle-même assurer la gestion des connexions des utilisateurs. Pour plus d'informations, consultez la page sur l'API Users.

L'exemple suivant nécessite une connexion pour le répertoire /profile/ et une connexion d'administrateur pour le répertoire /admin/ :


handlers:
- url: /profile/.*
  script: user_profile.app
  login: required

- url: /admin/.*
  script: admin.app
  login: admin

- url: /.*
  script: welcome.app

Vous pouvez configurer un gestionnaire pour qu'il refuse l'accès aux URL protégées lorsque l'utilisateur n'est pas connecté, plutôt que de le rediriger vers la page de connexion, en ajoutant auth_fail_action: unauthorized à la configuration du gestionnaire :


handlers:
- url: /secure_api/.*
  script: api_handler.app
  login: required
  auth_fail_action: unauthorized
expiration Facultatif. Durée pendant laquelle un fichier statique diffusé par ce gestionnaire doit être mis en cache par les serveurs proxy et les navigateurs. La valeur est une chaîne de nombres et d'unités, séparés par des espaces. 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 quatre jours et cinq heures après la première requête du fichier. Si cet élément n'est pas spécifié, la durée default_expiration définie dans l'application s'applique. Pour en savoir plus, consultez la section Expiration du cache de fichiers statiques.
http_headers

Facultatif. Vous pouvez définir des en-têtes HTTP pour les réponses de vos gestionnaires de fichiers statiques ou de répertoires. Si vous devez définir des en-têtes HTTP dans vos gestionnaires script, vous devez les indiquer dans le code de votre application.

Exemple

handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value
  # ...

Compatibilité avec le CORS

Une des principales applications de cette fonctionnalité consiste à accepter le partage de ressources multi-origines (CORS), tel que l'accès aux fichiers hébergés par une autre application App Engine.

Par exemple, vous pouvez avoir une application de jeu mygame.appspot.com qui accède aux éléments hébergés par myassets.appspot.com. Cependant, si mygame tente d'envoyer une requête XMLHttpRequest à myassets, elle n'aboutit pas à moins que le gestionnaire de myassets affiche un en-tête de réponse Access-Control-Allow-Origin: contenant la valeur http://mygame.appspot.com.

Voici comment faire en sorte que votre gestionnaire de fichiers statiques affiche la valeur d'en-tête de réponse requise :


handlers:
- url: /images
  static_dir: static/images
  http_headers:
    Access-Control-Allow-Origin: http://mygame.appspot.com
  # ...

Remarque : Si vous souhaitez autoriser tous les utilisateurs à accéder à vos ressources, vous pouvez utiliser le caractère générique '*' au lieu de http://mygame.appspot.com.

login

Facultatif. Détermine si le gestionnaire d'URL requiert que l'utilisateur soit connecté. Cet élément accepte les trois valeurs suivantes :

optional
C'est la valeur par défaut. Ne nécessite pas que l'utilisateur soit connecté.
required
Si l'utilisateur s'est connecté, le gestionnaire fonctionne normalement. Sinon, l'action indiquée dans auth_fail_action est effectuée.
admin
Comme la valeur required, cette valeur exécute auth_fail_action si l'utilisateur n'est pas connecté. De plus, si l'utilisateur n'est pas un administrateur de l'application, un message d'erreur lui est envoyé, quel que soit le paramètre auth_fail_action. Si l'utilisateur est un administrateur, le gestionnaire poursuit.

Lorsqu'un gestionnaire d'URL ayant un paramètre login défini sur une valeur autre que optional correspond à une URL, le gestionnaire vérifie d'abord si l'utilisateur s'est connecté à l'application à l'aide de son option d'authentification. Sinon, par défaut, l'utilisateur est redirigé vers la page de connexion. Vous pouvez également configurer l'application avec auth_fail_action de sorte qu'elle refuse simplement les requêtes d'un gestionnaire émanant d'utilisateurs qui ne sont pas authentifiés correctement, au lieu de les rediriger vers la page de connexion.

Remarque : La restriction de connexion admin s'applique également aux requêtes internes pour lesquelles App Engine définit les en-têtes spéciaux X-Appengine appropriés. Par exemple, les tâches cron planifiées respectent la restriction admin, car App Engine définit un en-tête HTTP X-AppEngine-Cron: true pour les requêtes correspondantes. Cependant, les requêtes peuvent ne pas respecter la restriction de connexion required, car les tâches Cron planifiées ne sont pas exécutées en tant qu'utilisateur.

mime_type

Facultatif. Si vous précisez le type MIME, ce gestionnaire l'utilise pour diffuser tous les fichiers. Dans le cas contraire, le type MIME d'un fichier est dérivé de l'extension du nom de fichier. Si le même fichier est importé avec plusieurs extensions, l'extension obtenue peut dépendre de l'ordre dans lequel les importations ont eu lieu.

Pour en savoir plus sur les types de médias MIME disponibles, consultez le site Web de l'IANA sur les types de médias MIME.

redirect_http_response_code

Facultatif. L'élément redirect_http_response_code est utilisé avec le paramètre secure pour définir le code de réponse HTTP affiché lors de l'exécution d'une redirection requise par le mode de configuration du paramètre secure. L'élément redirect_http_response_code accepte les valeurs suivantes :

301
Code de réponse "Moved Permanently" (ressource déplacée définitivement)
302
Code de réponse "Found" (ressource déplacée temporairement)
303
Code de réponse "See Other" (ressource située ailleurs)
307
Code de réponse "Temporary Redirect" (redirection temporaire)
Exemple

handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always
  redirect_http_response_code: 301

Lorsque la requête d'un utilisateur est redirigée, le code d'état HTTP est défini sur la valeur du paramètre redirect_http_response_code. Le code d'état 302 s'affiche si le paramètre n'est pas spécifié.

script

Facultatif. Indique le chemin d'accès au script à partir du répertoire racine de l'application :


handlers:
# The root URL (/) is handled by the WSGI application named
# "app" in home.py. No other URLs match this pattern.
- url: /
  script: home.app

# The URL /index.html is also handled by the home.py script.
- url: /index\.html
  script: home.app

# A regular expression can map parts of the URL to the
# path of the script.
- url: /browse/(books|videos|tools)
  script: \1.catalog.app

# All other URLs use the WSGI application named in "app"
# in not_found.py.
- url: /.*
  script: not_found.app

Une instruction script: doit être un chemin d'importation Python, tel que package.module.app, qui pointe vers une application WSGI. Le dernier composant d'une instruction script: utilisant un chemin de module Python est le nom d'une variable globale du module. Cette variable doit être une application WSGI et est généralement appelée app par convention.

Remarque : Comme pour une instruction Python import, chaque sous-répertoire constituant un package doit contenir un fichier nommé __init__.py.

secure Facultatif. Tous les gestionnaires d'URL peuvent utiliser le paramètre secure, y compris les gestionnaires de scripts et de fichiers statiques. L'élément secure peut avoir les valeurs suivantes :
optional
Les requêtes HTTP et HTTPS dont les URL correspondent au gestionnaire aboutissent sans redirection. L'application peut examiner la requête pour déterminer le protocole utilisé et répondre en conséquence. Il s'agit de la valeur par défaut lorsqu'aucun élément secure n'est fourni pour un gestionnaire.
never
Les requêtes d'accès à une URL, qui correspondent à ce gestionnaire et qui utilisent le protocole HTTPS, sont automatiquement redirigées vers l'URL HTTP équivalente. Lorsque la requête HTTPS d'un utilisateur est redirigée pour être convertie en requête HTTP, les paramètres sont supprimés de la requête. Cela empêche un utilisateur de soumettre accidentellement des données de requête destinées à une connexion sécurisée, via une connexion non sécurisée.
always
Les requêtes d'accès à une URL, qui correspondent à ce gestionnaire et qui n'utilisent pas le protocole HTTPS, sont automatiquement redirigées vers l'URL HTTPS contenant le même chemin d'accès. Les paramètres de requête sont conservés pour la redirection.
Exemple

handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always

Le serveur Web de développement ne prend pas en charge les connexions HTTPS. Il ignore le paramètre secure, de sorte que les chemins accessibles via HTTPS peuvent être testés par le biais de connexions HTTP standard au serveur Web de développement.

Pour cibler une version spécifique de votre application à l'aide du domaine appspot.com, vous devez remplacer les points qui séparent généralement les composants du sous-domaine de l'URL par la chaîne -dot-. Exemple :


https://[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com

Pour utiliser des domaines personnalisés avec HTTPS, vous devez d'abord activer et configurer les certificats SSL pour ce domaine.

Pour les comptes Google, la connexion et la déconnexion s'effectuent toujours via une connexion sécurisée, quelle que soit la manière dont les URL sont configurées.

static_dir

Facultatif. Chemin d'accès au répertoire contenant les fichiers statiques, à partir du répertoire racine de l'application. Tout ce qui figure à la fin du format d'url correspondant est ajouté à static_dir pour former le chemin d'accès complet au fichier demandé.

Chaque fichier du répertoire statique est diffusé en utilisant le type MIME qui correspond à son extension de nom de fichier, sauf s'il est ignoré par le paramètre mime_type du répertoire. Tous les fichiers du répertoire en question sont transférés en tant que fichiers statiques, et aucun d'eux ne peut être exécuté en tant que script.

Tous les fichiers de ce répertoire sont transférés avec votre application en tant que fichiers statiques. App Engine stocke et diffuse des fichiers statiques indépendamment des fichiers de votre application. Les fichiers statiques ne sont pas disponibles par défaut dans le système de fichiers de l'application. Pour modifier ce comportement, définissez l'option application_readable sur "true".

Exemple :

handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
  static_dir: stylesheets
  # ...
static_files

Facultatif. Un gestionnaire de modèles de fichiers statiques associe un format d'URL aux chemins d'accès des fichiers statiques qui sont transférés avec l'application. L'expression régulière du format d'URL peut définir des regroupements d'expressions régulières à utiliser pour la construction du chemin d'accès au fichier. Vous pouvez utiliser cette méthode au lieu de static_dir pour mapper des fichiers spécifiques à une structure de répertoire, et non le répertoire entier.

Exemple :

handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to
# static files in the static/ directory. The URL pattern is a
# regular expression, with a grouping that is inserted into the
# path to the file.
- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$
  # ...

App Engine stocke et diffuse des fichiers statiques indépendamment des fichiers d'application. Les fichiers statiques ne sont pas disponibles par défaut dans le système de fichiers de l'application. Pour modifier ce comportement, définissez l'option application_readable sur "true".

Les fichiers statiques doivent être différents des fichiers de code d'application. Si un chemin d'accès à un fichier statique correspond à un chemin d'accès à un script utilisé dans un gestionnaire dynamique, le gestionnaire dynamique ne peut pas accéder au script.

upload

Facultatif. Expression régulière qui correspond aux chemins d'accès de tous les fichiers référencés par ce gestionnaire. Elle est nécessaire, car le gestionnaire ne peut pas déterminer quels fichiers du répertoire de votre application correspondent aux formats url et static_files donnés. Les fichiers statiques sont transférés et gérés indépendamment des fichiers d'application. L'exemple ci-dessus peut utiliser le schéma upload suivant : archives/(.*)/items/(.*)

url

Élément requis sous l'élément handlers. Format d'URL sous la forme d'une expression régulière. L'expression peut contenir des regroupements qu'il est possible de désigner dans le chemin d'accès au script à l'aide de références arrières à des expressions régulières. Par exemple, /profile/(.*)/(.*) correspond à l'URL /profile/edit/manager, et utilise edit et manager comme premier et second regroupements.

Le format d'URL présente des différences de comportement lorsqu'il est utilisé avec les éléments suivants :

static_dir
Utilise le préfixe d'une URL. Le format d'expression régulière ne doit pas contenir de groupements lorsqu'il est utilisé avec l'élément static_dir. Toutes les URL commençant par ce préfixe sont gérées par ce gestionnaire, en utilisant la partie d'URL située après le préfixe comme une partie du chemin d'accès au fichier.
static_files
Un gestionnaire de formats de fichiers statiques associe un format d'URL à des chemins d'accès aux fichiers statiques transférés avec l'application. L'expression régulière du format d'URL peut définir des regroupements d'expressions régulières à utiliser pour la construction du chemin d'accès au fichier. Vous pouvez utiliser cette méthode au lieu de static_dir pour mapper des fichiers spécifiques à une structure de répertoire, et non le répertoire entier.

Éléments de scaling

Pour en savoir plus sur le scaling des applications App Engine, consultez la section Scaling des instances dynamiques.

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

É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 vous permet de définir 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. La valeur par défaut est 0.6.

Ce paramètre spécifie le seuil d'utilisation du processeur à partir duquel de nouvelles instances sont démarrées pour gérer le trafic. Vous pouvez 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 %.

Important : Si vous déployez des applications à l'aide de l'outil appcfg à partir du SDK App Engine pour Python, vous ne pouvez pas utiliser ce paramètre dans votre fichier app.yaml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres d'autoscaling 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. La valeur par défaut est 0.6.

É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 la valeur 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 pour Python, vous ne pouvez pas utiliser ce paramètre dans votre fichier app.yaml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres d'autoscaling dans l'API Explorer ou à l'aide de l'API App Engine Admin.

max_instances
Facultatif. Définissez une valeur comprise entre 0 et 2 147 483 647, où zéro désactive le paramètre.

Ce paramètre spécifie le nombre maximal d'instances qu'App Engine doit créer pour cette version de module. Cette solution permet de limiter les coûts d'un module.

Important : Si vous déployez des applications à l'aide de l'outil appcfg à partir du SDK App Engine pour Python, vous ne pouvez pas utiliser ce paramètre dans votre fichier app.yaml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres d'autoscaling 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. Sachez que vous êtes facturé à hauteur du nombre d'instances spécifiées, que celles-ci 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 Python, vous ne pouvez pas utiliser ce paramètre dans votre fichier app.yaml. Définissez plutôt le paramètre comme décrit dans la page Définir des paramètres d'autoscaling 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 génère une nouvelle instance (par défaut : 10, maximum : 80).

Élément combiné à target_throughput_utilization 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.

Vous risquez de rencontrer des taux de latence plus importants au niveau de l'API si ce paramètre est trop élevé. 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 les 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

Facultatif. Nombre maximal d'instances inactives qu'App Engine doit gérer pour cette version. Spécifiez une valeur comprise entre 1 et 1 000, ou automatic. La valeur par défaut est automatic. 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. L'atteinte de ce seuil correspond au déclenchement du scaling, qui se traduit par une augmentation du nombre d'instances. La valeur par défaut est 30ms.

App Engine peut créer une instance à tout moment dans l'intervalle spécifié entre min_pending_latency et max_pending_latency. En d'autres termes, App Engine ne crée pas d'instance pour diffuser une requête en attente avant l'heure spécifiée dans min_pending_latency, mais il en crée une lorsque la valeur max_pending_latency est atteinte.

  • Une valeur maximale faible 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 vont peut-être devoir attendre plus longtemps pour que l'application diffuse leur requête (s'il y a des requêtes en attente et qu'il n'y a aucune instance inactive pour les diffuser), 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. Sachez que vous êtes facturé à hauteur du nombre d'instances spécifiées, que celles-ci reçoivent ou non du trafic. Ce paramètre ne s'applique qu'à la version qui reçoit la plus grande partie du trafic. Tenez bien compte des éléments suivants :

  • Une valeur minimale faible permet de limiter vos coûts d'exploitation pendant les périodes d'inactivité, mais signifie que le nombre d'instances immédiatement disponible en cas de pic de charge soudain risque d'être réduit.
  • Une valeur minimale élevée vous permet de préparer l'application aux pics de charge rapides des requêtes. App Engine conserve le nombre minimal d'instances en cours d'exécution pour diffuser les requêtes entrantes. Vous êtes facturé à hauteur du nombre d'instances spécifiées, que celles-ci traitent ou non des requêtes. 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 garde 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 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. L'atteinte de ce seuil correspond au déclenchement du scaling qui se traduit par une diminution du nombre d'instances. La valeur par défaut est 30ms.

  • 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

service: my-service
runtime: python27
api_version: 1
instance_class: F2
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms  # default value
  max_pending_latency: automatic
  max_concurrent_requests: 50
basic_scaling

Facultatif. L'élément basic_scaling définit le nombre d'instances d'un service.

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 cinq minutes (5m).
max_instances
Obligatoire. Nombre maximal d'instances qu'App Engine peut créer pour cette version du service. Cette solution permet de limiter les coûts d'un service.
Exemple

service: my-service
runtime: python27
api_version: 1
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

Facultatif. L'élément manual_scaling active le scaling manuel et définit le nombre d'instances d'un service.

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

instances
Nombre d'instances à attribuer au service au démarrage.
Exemple

service: my-service
runtime: python27
api_version: 1
instance_class: B8
manual_scaling:
  instances: 5

Expiration du cache de fichiers statiques

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 définir une durée de mise en cache globale par défaut pour tous les gestionnaires de fichiers statiques d'une application, en incluant l'élément default_expiration de premier niveau. Vous pouvez également configurer une durée de cache pour des gestionnaires de fichiers statiques spécifiques.

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

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Environnement standard App Engine pour Python 2