Mode de traitement des requêtes

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

OK

Ce document décrit comment votre application App Engine reçoit des requêtes et envoie des réponses.

Pour en savoir plus, consultez la documentation de référence sur les en-têtes de requêtes et les réponses.

Si votre application utilise des services, vous pouvez adresser des requêtes à un service spécifique ou à une version particulière de ce service. Pour en savoir plus sur l'adressage des services, consultez la page Mode de routage des requêtes.

Traiter des requêtes

Votre application est responsable du démarrage d'un serveur Web et du traitement des requêtes. Vous pouvez utiliser n'importe quel framework Web disponible pour votre langage de développement.

Lorsque le service App Engine reçoit une requête Web pour votre application, il appelle le servlet correspondant à l'URL, comme décrit dans le fichier web.xml du répertoire WEB-INF/ de l'application. Il est compatible avec les spécifications de l'API Java Servlet 2.5 ou 3.1 pour fournir les données de la requête au servlet et accepter les données de réponse.

App Engine exécute plusieurs instances de votre application, et chaque instance dispose de son propre serveur Web pour le traitement des requêtes. Toute requête pouvant être acheminée vers n'importe quelle instance, les requêtes consécutives du même utilisateur ne sont pas nécessairement envoyées à la même instance. Le nombre d'instances peut être ajusté automatiquement en fonction de l'évolution du trafic.

Par défaut, chaque serveur Web ne traite qu'une requête à la fois. Pour répartir de multiples requêtes à chaque serveur Web en parallèle, marquez votre application comme threadsafe (à fil sécurisé) en ajoutant un élément <threadsafe>true</threadsafe> à votre fichier appengine-web.xml.

L'exemple de classe de servlet ci-dessous affiche un message simple dans le navigateur de l'utilisateur.

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(name = "requests", description = "Requests: Trivial request", urlPatterns = "/requests")
public class RequestsServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    resp.setContentType("text/plain");
    resp.getWriter().println("Hello, world");
  }
}

Quotas et limites

App Engine alloue automatiquement des ressources à votre application lorsque le trafic augmente. Toutefois, les restrictions suivantes s'appliquent :

• App Engine réserve une capacité de scaling automatique pour les applications à faible latence, qui répondent aux requêtes en moins d'une seconde.

• En outre, le temps de latence des applications fortement dépendantes des processeurs peut augmenter de manière à permettre le partage efficace des ressources avec les autres applications hébergées sur les mêmes serveurs. Aucune limite de latence n'est appliquée aux requêtes de fichiers statiques.

Chaque requête entrante vers l'application est prise en compte dans la limite des requêtes. Les données envoyées en réponse à une requête sont comptabilisées dans la limite de bande passante sortante (facturable).

Les requêtes HTTP et HTTPS (sécurisées) sont comptabilisées dans les limites de requêtes, de bande passante entrante (facturable) et de bande passante sortante (facturable). Dans la console Google Cloud, la page Détails des quotas affiche également les valeurs de Requêtes sécurisées, la Bande passante entrante sécurisée et la Bande passante sortante sécurisée de manière distincte à titre informatif. Seules les requêtes HTTPS sont comptabilisées dans ces valeurs. Pour en savoir plus, consultez la page Quotas.

Les limites ci-dessous s'appliquent spécifiquement à l'utilisation de gestionnaires de requêtes :

Limite	Volume
Taille d'une requête	32 Mo
Taille d'une réponse	32 Mo
Délai avant expiration de la requête	Dépend du type de scaling utilisé par votre application
Nombre total de fichiers, au maximum (fichiers d'application et fichiers statiques)	10 000 au total, 1 000 par répertoire
Taille maximale d'un fichier d'application	32 Mo
Taille maximale d'un fichier statique	32 Mo
Taille maximale du total des fichiers d'application et des fichiers statiques	Le premier gigaoctet est gratuit Le tarif est ensuite de 0,026 $ par gigaoctet et par mois
Délai avant expiration de la requête en attente	10 secondes
Taille maximale d'un seul champ d'en-tête de requête	8 kilo-octets pour les environnements d'exécution de deuxième génération dans l'environnement standard. Les requêtes adressées à ces environnements d'exécution avec des champs d'en-tête dépassant 8 kilo-octets renvoient des erreurs HTTP 400.

Limites de requêtes

Toutes les requêtes HTTP/2 sont converties en requêtes HTTP/1.1 lors de leur transmission au serveur d'applications.

Limites de réponse

• Les réponses dynamiques sont limitées à 32 Mo. Si un gestionnaire de scripts génère une réponse supérieure à cette limite, le serveur renvoie une réponse vide avec un code d'état 500 indiquant une erreur interne du serveur. Cette limite ne s'applique pas aux réponses qui diffusent des données provenant de l'ancien service Blobstore ou de Cloud Storage.

• La limite d'en-tête de réponse est de 8 ko pour les environnements d'exécution de deuxième génération. Les en-têtes de réponse qui dépassent cette limite renvoient des erreurs HTTP 502, avec des journaux affichant upstream sent too big header while reading response header from upstream.

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 ou modifiés par des serveurs proxy intermédiaires avant d'atteindre l'application.

Pour en savoir plus, consultez la documentation de référence sur les en-têtes de requête.

Gérer les délais d'expiration des requêtes

App Engine est optimisé pour les applications dont les requêtes sont de courte durée (quelques centaines de millisecondes en général). Pour être efficace, une application doit répondre rapidement à la majorité des requêtes. Si ce n'est pas le cas, elle n'est pas adaptée à l'infrastructure App Engine. Pour garantir ce niveau de performances, le système impose un délai d'expiration de la requête maximal pour chaque application.

Si votre application dépasse ce délai, App Engine interrompt le gestionnaire de requêtes. L'environnement d'exécution Java interrompt le servlet en générant une exception com.google.apphosting.api.DeadlineExceededException. S'il n'existe aucun gestionnaire de requêtes pour intercepter cette exception, l'environnement d'exécution renvoie une erreur de serveur HTTP 500 au client.

S'il existe un gestionnaire de requêtes et que DeadlineExceededException est intercepté, l'environnement d'exécution fournit au gestionnaire de requêtes une durée de moins d'une seconde pour préparer une réponse personnalisée. Si le gestionnaire de requêtes prend plus d'une seconde après la génération de l'exception pour préparer une réponse personnalisée, une exception HardDeadlineExceededError est renvoyée.

Les exceptions DeadlineExceededExceptions et HardDeadlineExceededErrors forcent la clôture de la requête et arrêtent l'instance.

Pour connaître le temps restant avant expiration du délai, l'application peut importer com.google.apphosting.api.ApiProxy et appeler ApiProxy.getCurrentEnvironment().getRemainingMillis(). Cela s'avère utile si l'application prévoit de commencer une tâche susceptible de prendre trop de temps. Si vous savez que le traitement d'une unité de travail dure cinq secondes, mais que la méthode getRemainingMillis() renvoie une durée inférieure, il est inutile de démarrer cette unité de travail.

Avertissement : L'exception DeadlineExceededException peut être générée à partir de n'importe quel point de votre programme, y compris des blocs finally, laissant alors votre programme dans un état non valide. Cette situation peut provoquer des blocages ou des erreurs inattendues dans le code à thread, car les verrous ne peuvent pas être libérés. Une fois la requête terminée, l'environnement d'exécution met fin au processus du serveur pour que les futures requêtes ne soient pas affectées. En revanche, toutes les requêtes simultanées traitées par le même processus seront arrêtées. Cela équivaut à appeler Thread.stop dans le thread principal. Pour obtenir plus d'informations, consultez l'article Why is Thread.stop deprecated?. Pour des raisons de sécurité, ne vous fiez pas à l'exception DeadlineExceededException. Assurez-vous plutôt que vos requêtes se terminent bien avant expiration du délai (appelez getRemainingMillis() si nécessaire).

Réponses

App Engine transmet au servlet un objet de requête et un objet de réponse, puis attend que le servlet complète l'objet de réponse et le renvoie. Les données de l'objet de réponse sont alors envoyées à l'utilisateur.

Des limites de taille s'appliquent à la réponse que vous générez et celle-ci peut être modifiée avant d'être renvoyée au client.

Pour en savoir plus, consultez la documentation de référence sur les réponses aux requêtes.

Réponses en flux continu

App Engine n'accepte pas les réponses en flux continu dans lesquelles les données sont envoyées au client par blocs incrémentiels pendant le traitement d'une requête. Toutes les données de votre code sont collectées comme indiqué ci-dessus et envoyées sous la forme d'une réponse HTTP unique.

Compression de la réponse

App Engine met tout en œuvre pour diffuser du contenu compressé avec gzip aux clients qui l'acceptent. Pour déterminer si le contenu doit être compressé, App Engine effectue les opérations suivantes lors de la réception d'une requête :

1. Le service vérifie si le client peut recevoir des réponses compressées de manière fiable en consultant les en-têtes Accept-Encoding et User-Agent dans la requête. Cette approche permet d'éviter les bugs connus associés au contenu compressé avec gzip qui se produisent avec les navigateurs les plus courants.

2. Vérifie si la compression du contenu est appropriée en affichant l'en-tête Content-Type que vous avez configuré pour le gestionnaire de réponses. En général, la compression est appropriée pour les types de contenus textuels et non pour les types de contenus binaires.

Veuillez noter les points suivants :

• Un client peut forcer la compression des types de contenu textuel en définissant à la fois les en-têtes de requête Accept-Encoding et User-Agent sur gzip.

• Si une requête ne spécifie pas gzip dans l'en-tête Accept-Encoding, App Engine ne compresse pas les données de réponse.

• L'interface Google met en cache les réponses des gestionnaires de répertoires et de fichiers statiques App Engine. En fonction de divers facteurs, tels que le type des données de réponse mises en cache en premier, les en-têtes Vary que vous avez spécifiés dans la réponse ou les en-têtes inclus dans la requête, un client peut avoir demandé des données compressées, mais recevoir des données non compressées, et inversement. Pour en savoir plus, consultez la section Mettre en cache les réponses.

Mettre en cache les réponses

L'interface Google et éventuellement le navigateur de l'utilisateur ainsi que d'autres serveurs proxy de mise en cache intermédiaires mettent en cache les réponses de votre application, comme indiqué par les en-têtes de mise en cache standards que vous spécifiez dans la réponse. Vous pouvez spécifier ces en-têtes de réponse soit via votre framework, directement dans votre code, soit via les gestionnaires de répertoires et de fichiers statiques d'App Engine.

Dans l'interface Google, la clé du cache correspond à l'URL complète de la requête.

Mettre en cache du contenu statique

Pour vous assurer que les clients reçoivent toujours le contenu statique mis à jour dès sa publication, nous vous recommandons de diffuser le contenu statique à partir de répertoires avec versions gérées, tels que css/v1/styles.css. L'interface Google ne valide pas le cache (vous devez rechercher le contenu mis à jour) avant l'expiration du cache. Même après son expiration, le cache n'est pas mis à jour tant que le contenu de l'URL de la requête n'a pas été modifié.

Les en-têtes de réponse suivants, que vous pouvez définir dans appengine-web.xml, modifient le moment et la méthode de mise en cache du contenu par l'interface Google :

• Cache-Control doit être défini sur public pour que l'interface Google mette en cache le contenu. Il peut également être mis en cache par l'interface Google, sauf si vous spécifiez une instruction Cache-Control private ou no-store. Si vous ne définissez pas cet en-tête dans appengine-web.xml, App Engine l'ajoute automatiquement pour toutes les réponses traitées par un gestionnaire de répertoires ou de fichiers statiques. Pour en savoir plus, consultez la section En-têtes ajoutés ou remplacés.

• Vary : pour permettre au cache de renvoyer différentes réponses pour une URL en fonction des en-têtes envoyés dans la requête, définissez une ou plusieurs des valeurs suivantes dans l'en-tête de réponse Vary : Accept, Accept-Encoding, Origin, ou X-Origin.

  En raison du potentiel de cardinalité élevée, les données ne seront pas mises en cache pour d'autres valeurs Vary.

  Exemple :

  1. Vous spécifiez l'en-tête de réponse suivant :

     Vary: Accept-Encoding

  2. Votre application reçoit une requête contenant l'en-tête Accept-Encoding: gzip. App Engine renvoie une réponse compressée, et l'interface Google met en cache la version des données de réponse compressée avec gzip. Toutes les requêtes ultérieures pour cette URL contenant l'en-tête Accept-Encoding: gzip recevront les données du cache compressées avec gzip jusqu'à l'invalidation de celui-ci (en raison du changement de contenu après l'expiration du cache).

  3. Votre application reçoit une requête qui ne contient pas l'en-tête Accept-Encoding. App Engine renvoie une réponse non compressée, et l'interface Google met en cache la version non compressée des données de réponse. Toutes les requêtes ultérieures pour cette URL ne contenant pas l'en-tête Accept-Encoding recevront les données compressées du cache jusqu'à ce que le cache soit invalidé.

  Si vous ne spécifiez pas d'en-tête de réponse Vary, l'interface Google crée une seule entrée de cache pour l'URL et l'utilise pour toutes les requêtes, quels que soient les en-têtes de la requête. Exemple :

  1. Vous ne spécifiez pas l'en-tête de réponse Vary: Accept-Encoding.
  2. Une requête contient l'en-tête Accept-Encoding: gzip, et la version compressée avec gzip des données de réponse est mise en cache.
  3. Une deuxième requête ne contient pas l'en-tête Accept-Encoding: gzip. Toutefois, comme le cache contient une version compressée avec gzip des données de réponse, la réponse sera compressée avec gzip même si le client a demandé des données non compressées.

Les en-têtes de la requête influent également sur la mise en cache :

• Si la requête contient un en-tête Authorization, le contenu ne sera pas mis en cache par l'interface Google.

Expiration du cache

Par défaut, les en-têtes de mise en cache que les gestionnaires de répertoires et de fichiers statiques App Engine ajoutent aux réponses indiquent aux clients et aux proxys Web, tels que l'interface Google, que le cache doit expirer au bout de 10 minutes.

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 fait de déployer 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.

Vous pouvez modifier le délai d'expiration par défaut pour tous les gestionnaires de répertoires et de fichiers statiques en spécifiant l'élément static-files dans votre fichier appengine-web.xml.

Journalisation

Votre application peut écrire des informations dans les journaux d'application à l'aide de java.util.logging.Logger. Les données de journal de votre application peuvent être affichées dans la console Google Cloud à l'aide de Cloud Logging. Chaque requête journalisée se voit attribuer un ID de requête, un identifiant global unique basé sur l'heure de début de la requête. La console Google Cloud peut reconnaître les niveaux de journalisation de la classe Logger et afficher de manière interactive les messages à différents niveaux.

Tout ce que le servlet écrit dans le flux de sortie standard (System.out) et dans le flux d'erreur standard (System.err) est collecté par App Engine et enregistré dans les journaux de l'application. Les lignes écrites dans le flux de sortie standard sont journalisées au niveau "INFO" et les lignes écrites dans le flux d'erreur standard sont journalisées au niveau "AVERTISSEMENT". Tout framework de journalisation (tel que log4j) qui écrit dans les flux de résultat ou d'erreur standards est accepté. Cependant, pour un contrôle plus détaillé de l'affichage des niveaux de journalisation dans la console Google Cloud, le framework de journalisation doit utiliser un adaptateur java.util.logging.

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(
    name = "RequestLogging",
    description = "Requests: Logging example",
    urlPatterns = "/requests/log"
)
public class LoggingServlet extends HttpServlet {

  private static final Logger log = Logger.getLogger(LoggingServlet.class.getName());

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    log.info("An informational message.");
    log.warning("A warning message.");
    log.severe("An error message.");
    // ...
  }
}

Le SDK Java d'App Engine contient un modèle de fichier logging.properties, dans le répertoire appengine-java-sdk/config/user/. Pour l'utiliser, copiez-le dans votre répertoire WEB-INF/classes (ou ailleurs dans l'archive WAR), puis copiez la propriété système java.util.logging.config.file dans "WEB-INF/logging.properties" (ou à l'emplacement de votre choix en fonction de la racine de l'application). Vous pouvez définir les propriétés système dans le fichier appengine-web.xml comme suit :

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> ... <system-properties> <property name="java.util.logging.config.file" value="WEB-INF/logging.properties" /> </system-properties> </appengine-web-app>

Le servlet consigne les messages à l'aide du niveau de journalisation INFO (via log.info()). Le niveau par défaut, WARNING, supprime les messages INFO du résultat de sortie. Pour changer le niveau de journalisation, modifiez le fichier logging.properties.

Environnement

Toutes les propriétés système et les variables d'environnement sont propres à votre application. La définition d'une propriété système n'affecte que la façon dont votre application interprète cette propriété, mais pas celle dont la VM Java l'interprète.

Vous pouvez définir les propriétés système et les variables d'environnement de votre application dans le descripteur de déploiement.

App Engine définit plusieurs propriétés système qui identifient l'environnement d'exécution :

• com.google.appengine.runtime.environment est défini sur "Production" lors de l'exécution sur App Engine, et sur "Development" lors de l'exécution sur le serveur de développement.

  En plus d'utiliser System.getProperty(), vous pouvez accéder aux propriétés système à l'aide de notre API sécurisée comme suit : Exemple :

  if (SystemProperty.environment.value() ==
      SystemProperty.Environment.Value.Production) {
      // The app is running on App Engine...
  }
  

• L'élément com.google.appengine.runtime.version correspond à l'ID de version de l'environnement d'exécution, tel que "1.3.0". Vous pouvez obtenir la version en appelant la méthode suivante : String version = SystemProperty.version.get();

• L'élément com.google.appengine.application.id correspond à l'identifiant de l'application. Vous pouvez obtenir l'identifiant en appelant la méthode suivante : String ID = SystemProperty.applicationId.get();

• L'élément com.google.appengine.application.version correspond à la version majeure et mineure du service d'application en cours d'exécution, au format "X.Y". Le numéro de la version majeure ("X") est spécifié dans le fichier appengine-web.xml du service. Le numéro de la version mineure ("Y") est défini automatiquement lorsque chaque version de l'application est importée sur App Engine. Vous pouvez obtenir l'identifiant en appelant la méthode suivante : String ID = SystemProperty.applicationVersion.get();

  Sur le serveur Web de développement, la version majeure renvoyée est toujours la version du service par défaut et la version mineure est toujours "1".

Le service App Engine définit également les propriétés système suivantes lorsqu'il initialise la VM Java sur un serveur d'applications :

• file.separator
• path.separator
• line.separator
• java.version
• java.vendor
• java.vendor.url
• java.class.version
• java.specification.version
• java.specification.vendor
• java.specification.name
• java.vm.vendor
• java.vm.name
• java.vm.specification.version
• java.vm.specification.vendor
• java.vm.specification.name
• user.dir

ID d'instances

Vous pouvez récupérer l'ID de l'instance qui traite une requête à l'aide de ce code :

com.google.apphosting.api.ApiProxy.getCurrentEnvironment().getAttributes().get("com.google.appengine.instance.id")

Dans l'environnement de production, un administrateur connecté peut utiliser l'ID dans une URL : https://INSTANCE_ID-dot-VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com. La requête est alors acheminée vers cette instance spécifique. Si l'instance ne peut pas traiter la requête, elle renvoie immédiatement l'erreur 503.

ID de requête

Au moment de la requête, vous pouvez enregistrer l'ID de requête, un identifiant unique qui peut être utilisé ultérieurement pour mettre en corrélation une requête et les journaux qui y sont associés.

Remarque : Pour le moment, App Engine ne permet pas d'utiliser des ID de requêtes pour rechercher directement les journaux associés.

Le code suivant montre comment obtenir l'ID de requête dans le contexte d'une requête :

com.google.apphosting.api.ApiProxy.getCurrentEnvironment().getAttributes().get("com.google.appengine.runtime.request_log_id")

Forcer les connexions HTTPS

Pour des raisons de sécurité, toutes les applications doivent encourager les clients à se connecter via le protocole https. Pour indiquer au navigateur de privilégier https à http pour une page ou un domaine donné, définissez l'en-tête Strict-Transport-Security dans vos réponses. Exemple :

Strict-Transport-Security: max-age=31536000; includeSubDomains

Pour définir cet en-tête pour tout contenu statique diffusé par votre application, ajoutez-le aux fichiers statiques et gestionnaires de fichiers de votre application.

La plupart des frameworks d'application et des serveurs Web permettent de définir cet en-tête pour les réponses générées à partir de votre code. Pour en savoir plus sur l'en-tête Strict-Transport-Security de Spring Boot, consultez la section HTTP Strict Transport Security (HSTS).

Attention : Les clients ayant reçu cet en-tête dans le passé refusent de se connecter si https n'est plus fonctionnel ou est désactivé pour une raison quelconque. Pour en savoir plus, consultez cet aide-mémoire sur le mécanisme HTTP Strict Transport Security.

Gérer les tâches asynchrones en arrière-plan

Une tâche en arrière-plan désigne toute tâche effectuée par votre application pour une requête après la transmission d'une réponse HTTP. Évitez d'effectuer des tâches en arrière-plan dans votre application et examinez votre code pour vous assurer que toutes les opérations asynchrones sont terminées avant de transmettre votre réponse.

Pour les tâches de longue durée, nous vous recommandons d'utiliser Cloud Tasks. Avec Cloud Tasks, les requêtes HTTP ont une longue durée de vie et ne renvoient une réponse qu'une fois les tâches asynchrones terminées.

Avertissement : L'exécution de tâches asynchrones en arrière-plan peut entraîner une facturation plus élevée. App Engine peut effectuer un scaling à la hausse des instances en raison d'une charge de processeur élevée, même en l'absence de requêtes actives. Les utilisateurs peuvent également rencontrer une latence accrue en raison des requêtes présentes dans la file d'attente pour les instances disponibles.