En-têtes de requête et réponses

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

Consultez cette page de référence pour en savoir plus sur les en-têtes HTTP compatibles, ainsi que sur les limites des requêtes et des réponses dans App Engine. Pour comprendre comment App Engine reçoit les requêtes et envoie les réponses, consultez la page Mode de traitement des requêtes.

En-têtes de requête

Une requête HTTP entrante inclut des en-têtes HTTP envoyés par le client. Pour des raisons de sécurité, certains en-têtes sont nettoyés, modifiés ou supprimés par des proxys intermédiaires avant d'atteindre l'application.

En-têtes supprimés des requêtes entrantes

Les en-têtes suivants sont supprimés des requêtes entrantes si un client les envoie :

  • En-têtes dont le nom correspond au format X-Google-*. Ce format de nom est réservé à Google.

  • En-têtes dont les noms correspondent à des en-têtes spécifiques à App Engine. Seules les correspondances exactes et non sensibles à la casse sont supprimées. Par exemple, les en-têtes nommés X-Appengine-Country ou X-AppEngine-Country sont supprimés, mais X-Appengine-Cntry ne l'est pas.

En outre, les en-têtes suivants sont supprimés des requêtes entrantes, car ils concernent le transfert des données HTTP entre le client et le serveur :

  • Accept-Encoding
  • Connection
  • Keep-Alive
  • Proxy-Authorization
  • TE
  • Trailer
  • Transfer-Encoding

Par exemple, le serveur peut envoyer automatiquement une réponse compressée avec gzip en fonction de la valeur de l'en-tête de requête Accept-Encoding. L'application elle-même n'a pas besoin de savoir quels encodages de contenu peuvent être acceptés par le client.

Requêtes et WSGI

Le serveur détermine l'objet d'application Python à appeler en comparant l'URL de la requête aux formats d'URL du fichier de configuration de l'application. Il appelle ensuite l'objet d'application à l'aide des arguments définis dans la norme WSGI. L'objet d'application exécute les actions adaptées à la requête, prépare ensuite une réponse et la renvoie sous forme de liste de chaînes.

La plupart des applications utilisent un framework, tel que webapp2, pour gérer les requêtes WSGI. webapp2 est inclus dans l'environnement d'exécution Python 2.7.

Requêtes et CGI

Le serveur détermine le script de gestionnaire Python à exécuter en comparant l'URL de la requête aux formats d'URL du fichier de configuration de l'application. Il exécute ensuite le script dans un environnement contenant les données de la requête. Comme décrit dans la norme CGI, le serveur place les données de la requête dans les variables d'environnement et dans le flux d'entrée standard. Le script exécute les actions adaptées à la requête, puis prépare une réponse et la place dans le flux de sortie standard.

La plupart des applications utilisent une bibliothèque pour analyser les requêtes CGI et renvoyer les réponses CGI, comme le module cgi de la bibliothèque standard Python, ou un framework Web connaissant le protocole CGI (tel que webapp). Pour en savoir plus sur les variables d'environnement et le format des données de flux d'entrée, vous pouvez consulter la documentation de CGI.

En-têtes spécifiques à App Engine

En tant que service pour l'application, App Engine ajoute les en-têtes suivants à toutes les requêtes :

X-Appengine-Country
Pays d'origine de la requête, sous forme de code de pays ISO 3166-1 alpha-2. App Engine définit ce code à partir de l'adresse IP du client. Notez que les informations concernant le pays ne sont pas dérivées de la base de données WHOIS. Il est possible qu'une adresse IP pour laquelle des informations associées au pays sont présentes dans la base de données WHOIS ne contienne pas ces informations dans l'en-tête X-Appengine-Country. Votre application doit gérer le code de pays spécial ZZ (pays inconnu).
X-Appengine-Region
Nom de la région d'origine de la requête. Cette valeur n'a de sens que dans le contexte du pays dans X -Appengine-Country. Par exemple, si le pays est "États-Unis" et la région "ca", "ca" signifie "Californie", et non "Canada". La liste complète des valeurs de région valides se trouve dans la norme ISO-3166-2.
X-Appengine-City
Nom de la ville d'origine de la requête. Par exemple, la valeur d'en-tête d'une requête provenant de Mountain View serait mountain view. Il n'existe pas de liste canonique de valeurs valides pour cet en-tête.
X-Appengine-CityLatLong
Latitude et longitude de la ville d'où provient la requête. Cette chaîne peut par exemple prendre la forme "37.386051, -122.083851" pour une requête provenant de Mountain View.
X-Cloud-Trace-Context
Identifiant unique de la requête utilisé pour Cloud Trace et Cloud Logging. Aucune option ne permet de désactiver cet en-tête ni de choisir le taux d'échantillonnage pour le traçage, car toutes les applications de l'environnement standard App Engine sont tracées automatiquement.
X-Forwarded-For: [CLIENT_IP(s)], [global forwarding rule IP]

Liste d'adresses IP séparées par une virgule via lesquelles la requête du client a été acheminée. La première adresse IP de cette liste est généralement l'adresse IP du client qui a créé la requête. Les adresses IP suivantes fournissent des informations sur les serveurs proxy qui ont également traité la requête avant qu'elle n'atteigne le serveur d'application. Exemple :

X-Forwarded-For: clientIp, proxy1Ip, proxy2Ip
X-Forwarded-Proto [http | https]

Affiche http ou https en fonction du protocole utilisé par le client pour se connecter à votre application.

L'équilibreur de charge Google Cloud met fin à toutes les connexions https, puis transfère le trafic vers les instances App Engine via http. Par exemple, si un utilisateur demande l'accès à votre site via https://PROJECT_ID.REGION_ID.r.appspot.com, la valeur de l'en-tête X-Forwarded-Proto est https.

En outre, App Engine peut définir les en-têtes suivants, qui sont réservés à une utilisation interne par App Engine :

  • X-Appengine-Https
  • X-Appengine-User-IP
  • X-Appengine-Api-Ticket
  • X-Appengine-Request-Log-Id
  • X-Appengine-Default-Version-Hostname
  • X-Appengine-Timeout-Ms
Les services App Engine peuvent ajouter des en-têtes de requête supplémentaires :

  • Pour les gestionnaires login:admin ou login:required spécifiés dans app.yaml, App Engine ajoute l'ensemble d'en-têtes suivant :

    • X-Appengine-User-Email, avec l'exemple d'en-tête : "ange@example.com"
    • X-Appengine-Auth-Domain, avec l'exemple d'en-tête : "example.com"
    • X-Appengine-User-ID, avec l'exemple d'en-tête : "100979712376541954724"
    • X-Appengine-User-Nickname, avec l'exemple d'en-tête : "ange"
    • X-Appengine-User-Organization, avec l'exemple d'en-tête : "example.com"
    • X-Appengine-User-Is-Admin, avec l'exemple d'en-tête : "1"
  • Le service de file d'attente de tâches ajoute aux requêtes des en-têtes supplémentaires qui fournissent des détails sur la tâche dans la requête et sur la file d'attente à laquelle elle est associée.

  • Les requêtes du service Cron ajoutent l'en-tête suivant :

    X-Appengine-Cron: true

    Pour en savoir plus, consultez la page Sécuriser les URL pour Cron.

  • Les requêtes provenant d'autres applications App Engine comportent un en-tête identifiant l'application à l'origine de la requête, si cette application utilise le service de récupération d'URL :

    X-Appengine-Inbound-Appid

    Pour en savoir plus, consultez la documentation sur App Identity.

Réponses aux requêtes

Cette documentation sur les en-têtes HTTP s'applique uniquement aux réponses renvoyées aux requêtes HTTP entrantes. La réponse peut être modifiée avant d'être renvoyée au client. Pour les en-têtes HTTP associés aux requêtes sortantes générées par votre code App Engine, consultez la documentation sur les en-têtes pour URLFetch.

En-têtes supprimés

Les en-têtes suivants sont ignorés et supprimés de la réponse :

  • Connection
  • Content-Encoding*
  • Content-Length
  • Date
  • Keep-Alive
  • Proxy-Authenticate
  • Server
  • Trailer
  • Transfer-Encoding
  • Upgrade

* Peut être de nouveau ajouté si la réponse est compressée par App Engine.

Les en-têtes dont le nom ou la valeur comporte des caractères non-ASCII sont également supprimés.

En-têtes ajoutés ou remplacés

Les en-têtes suivants sont ajoutés ou remplacés dans la réponse :

Cache-Control, Expires et Vary

Ces en-têtes spécifient la stratégie de mise en cache pour les proxys intermédiaires (tels que l'interface Google et les fournisseur d'accès à Internet) et les navigateurs. Si votre application définit ces en-têtes de réponse, ils ne seront généralement pas modifiés, sauf si votre application définit également un en-tête Set-Cookie ou si la réponse est générée pour un utilisateur connecté à l'aide d'un compte administrateur.

Si vous définissez un en-tête de réponse Set-Cookie dans votre application, l'en-tête Cache-Control sera défini sur private (s'il n'est pas déjà plus restrictif) et l'en-tête Expires sera défini sur la date actuelle (si sa valeur n'est pas déjà une valeur passée). Généralement, cela permettra aux navigateurs, mais pas aux serveurs proxy intermédiaires, de mettre en cache la réponse. Ce fonctionnement est appliqué pour des raisons de sécurité, car, si la réponse était mise en cache publiquement, un autre utilisateur pourrait ultérieurement interroger la même ressource et récupérer le cookie du premier utilisateur.

Si vous utilisez un framework basé sur WebOb (tel que webapp ou webapp2), le framework définit l'en-tête Cache-Control sur no-cache par défaut. Vous devez donc le remplacer si vous souhaitez activer la mise en cache dans vos gestionnaires de script.

Si vous ne spécifiez pas l'en-tête de réponse Cache-Control dans votre application, le serveur peut le définir sur private et ajouter un en-tête Vary: Accept-Encoding.

Pour en savoir plus sur la mise en cache et obtenir la liste des valeurs Vary acceptées par l'interface Google, consultez la section Mettre en cache les réponses.

Content-Encoding

En fonction des en-têtes de requête et du type d'en-tête Content-Type de la réponse, le serveur peut compresser automatiquement le corps de la réponse, comme décrit ci-dessus. Dans ce cas, un en-tête Content-Encoding: gzip est ajouté pour indiquer que le corps est compressé. Pour en savoir plus, consultez la page Compression de la réponse.

Content-Length ou Transfer-Encoding

Le serveur ignore toujours l'en-tête Content-Length renvoyé par l'application. Soit il définit Content-Length sur la longueur du corps (après compression, le cas échéant), soit il supprime Content-Length et utilise l'encodage de transfert fragmenté (ajout d'un en-tête Transfer-Encoding: chunked).

Content-Type

Si l'en-tête n'est pas spécifié par l'application, le serveur définit un en-tête Content-Type: text/html par défaut.

Date

Doit être défini sur la date et l'heure actuelles.

Server

Doit être défini sur Google Frontend. Le serveur de développement définit cet en-tête sur Development/x, x correspondant au numéro de version.

Si vous accédez à des pages dynamiques sur votre site alors que vous êtes connecté à l'aide d'un compte administrateur, App Engine inclut des statistiques par requête dans les en-têtes de réponse, par exemple :

X-Appengine-Resource-Usage
Ressources utilisées par la requête, y compris l'heure côté serveur exprimée en millisecondes.

Les réponses comportant des statistiques d'utilisation des ressources ne seront pas aptes à la mise en cache.

Si l'en-tête X-Appengine-BlobKey se trouve dans la réponse de l'application, il sera utilisé, conjointement avec l'en-tête facultatif X-Appengine-BlobRange, pour remplacer le corps par tout ou partie du contenu d'un blob blobstore. Si Content-Type n'est pas spécifié par l'application, il sera défini sur le type MIME du blob. Si une plage est demandée, l'état de la réponse sera remplacé par 206 Partial Content et un en-tête Content-Range sera ajouté. Les en-têtes X-Appengine-BlobKey et X-Appengine-BlobRange seront supprimés de la réponse. Normalement, vous n'avez pas besoin de définir ces en-têtes vous-même, car la classe blobstore_handlers.BlobstoreDownloadHandler les définit. Pour en savoir plus, consultez la page Diffuser un blob.

En-têtes de réponse définis dans la configuration de l'application

Les en-têtes de réponse HTTP personnalisés peuvent être définis par URL pour les chemins d'accès dynamiques et statiques dans le fichier de configuration de votre application. Pour en savoir plus, consultez les sections http_headers dans la documentation de la configuration.