Documentation de référence de queue.xml

Les applications utilisant le SDK App Engine pour gérer les files d'attente de tâches définissent ces files d'attente à l'aide d'un fichier de configuration appelé queue.xml. Pour les applications Java, ce fichier est stocké dans le répertoire WEB-INF de l'application. Vous pouvez aussi bien configurer les queue.xml que les files d'attente de retrait à l'aide du fichier queue.xml. Toutefois, ce fichier de configuration est facultatif pour les files d'attente d'envoi, qui ont une file d'attente par défaut. Les files d'attente de retrait se configurent spécifiquement dans un fichier queue.xml.

Exemple

Voici un exemple de base qui définit une file d'attente nommée et remplace le taux de traitement par défaut :

<queue-entries>
  <queue>
    <name>my-push-queue</name>
    <rate>1/s</rate>
  </queue>
</queue-entries>

Voici un exemple plus complexe du fichier queue.xml, qui illustre la configuration du nombre de tentatives pour les tâches et la modification du taux de traitement par défaut.

<queue-entries>
  <queue>
    <name>fooqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <task-retry-limit>7</task-retry-limit>
      <task-age-limit>2d</task-age-limit>
    </retry-parameters>
  </queue>
  <queue>
    <name>barqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <min-backoff-seconds>10</min-backoff-seconds>
      <max-backoff-seconds>200</max-backoff-seconds>
      <max-doublings>0</max-doublings>
    </retry-parameters>
  </queue>
  <queue>
    <name>bazqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <min-backoff-seconds>10</min-backoff-seconds>
      <max-backoff-seconds>200</max-backoff-seconds>
      <max-doublings>3</max-doublings>
    </retry-parameters>
  </queue>
</queue-entries>

Syntaxe

Le fichier queue.xml est un fichier XML dont l'élément racine est <queue-entries>. Cette directive contient une ou plusieurs files d'attente nommées, ou aucune, dans les éléments <queue>. Chaque définition de file d'attente peut spécifier les éléments suivants :

Élément Description
<bucket-size> (files d'attente d'envoi)

Facultatif. Une file d'attente de tâches utilise l'algorithme token bucket pour contrôler le taux d'exécution des tâches. Chaque file d'attente nommée possède un bucket de jetons (token) qui contient des jetons dont le nombre maximal est spécifié par la valeur bucket_size. Chaque fois que votre application exécute une tâche, un jeton est supprimé du bucket. Le traitement des tâches dans la file d'attente se poursuit jusqu'à épuisement des jetons dans le bucket. App Engine ajoute en continu des jetons dans le bucket en fonction du taux que vous avez spécifié pour la file d'attente.

La taille du bucket limite le taux de traitement lorsqu'un grand nombre de tâches se trouve dans la file d'attente et que le taux est élevé. La valeur maximale de la taille du bucket est "500". Cela permet d'obtenir un taux élevé de sorte que le traitement démarre rapidement après la mise en file d'attente d'une tâche, tout en limitant l'utilisation des ressources lorsqu'un grand nombre de tâches sont placées en file d'attente pour une courte période.

Si vous ne spécifiez pas de valeur bucket_size pour une file d'attente, la valeur par défaut est "5". Nous vous recommandons de définir une valeur supérieure, car la taille par défaut peut s'avérer insuffisante dans de nombreux cas d'utilisation : la taille recommandée correspond au taux de traitement divisé par 5 (taux/5).

Pour en savoir plus sur cet élément, consultez la description comparative de max_burst_size

dans la documentation de référence de l'API Cloud Tasks.
<max-concurrent-requests> (files d'attente d'envoi)

Facultatif. Définit le nombre maximal de tâches pouvant s'exécuter simultanément en fonction de la file d'attente spécifiée. Cette valeur est un nombre entier. Par défaut, la limite est de 1 000 tâches par file d'attente. La limite supérieure recommandée est de 5 000 tâches par file d'attente. Notez que les files d'attente peuvent augmenter lentement lorsqu'elles viennent d'être créées ou si elles sont restées inactives pendant un certain temps.

Limiter le nombre de tâches simultanées vous permet de mieux contrôler le taux d'exécution de la file d'attente et peut empêcher l'exécution simultanée d'un trop grand nombre de tâches. Cela peut également éviter les conflits avec le datastore et libérer des ressources pour d'autres files d'attente ou pour le traitement en ligne.

Pour en savoir plus sur cet élément, consultez la description comparative de max_concurrent_dispatches dans la documentation de référence de l'API Cloud Tasks.

<mode>

Facultatif. Identifie le mode de file d'attente. La valeur par défaut de ce paramètre est push, qui identifie une file d'attente d'envoi. Si vous souhaitez utiliser des files d'attente de retrait, définissez le mode sur pull.

<name>

Obligatoire. Nom de la file d'attente. Il s'agit du nom que vous spécifiez lorsque vous appelez QueueFactory.getQueue().

Un nom de file d'attente peut contenir des lettres majuscules et minuscules, des chiffres et des traits d'union. La longueur maximale d'un nom de file d'attente est de 100 caractères.

Toutes les applications ont une file d'attente nommée default. Cette file d'attente a un taux prédéfini de 5 tâches par seconde, mais vous pouvez modifier ce taux en définissant une file d'attente par défaut dans le fichier queue.xml. Si vous ne configurez pas de file d'attente par défaut dans le fichier queue.xml, celle-ci ne s'affiche pas dans la console Google Cloud Platform avant sa première utilisation. Vous pouvez personnaliser les paramètres de cette file d'attente en définissant une file d'attente nommée default.

<rate> (files d'attente d'envoi)

Obligatoire. Fréquence à laquelle les tâches sont traitées sur cette file d'attente. Sa valeur est un nombre suivi d'une barre oblique et d'une unité de temps. Les unités valides sont s pour les secondes, m pour les minutes, h pour les heures et d pour les jours. Par exemple, la valeur 5/m indique que les tâches seront traitées à raison de cinq fois par minute. La valeur maximale du paramètre rate est 500/s.

Si le nombre est 0 (par exemple 0/s), la file d'attente est considérée comme "suspendue" et aucune tâche n'est traitée.

Pour en savoir plus sur cet élément, consultez la description comparative de max_dispatches_per_second dans la documentation de référence de l'API Cloud Tasks.

<retry-parameters>

Facultatif. Configure le nombre de tentatives d'exécution des tâches ayant échoué dans les files d'attente d'envoi. Ce paramètre supplémentaire vous permet d'indiquer le nombre maximal de tentatives d'exécution des tâches ayant échoué dans une file d'attente donnée. Vous pouvez également définir un délai maximal entre chaque tentative et contrôler l'intervalle entre chacune d'elles.

Les paramètres relatifs aux nouvelles tentatives peuvent contenir les sous-éléments suivants :

<task-retry-limit>
Nombre de tentatives. Par exemple, si la valeur 0 est spécifiée et que la tâche échoue, celle-ci n'est pas relancée. Si la valeur 1 est spécifiée et que la tâche échoue, la tâche est relancée une seule fois. Si ce paramètre n'est pas spécifié, la tâche se répète indéfiniment. Si task_retry_limit est spécifié avec task_age_limit, la tâche est relancée jusqu'à ce que les deux limites soient atteintes.
<task-age-limit> (files d'attente d'envoi)
Délai maximal entre chaque tentative d'exécution d'une tâche ayant échoué, mesuré à partir du moment où elle a été exécutée pour la première fois. Sa valeur est un nombre suivi d'une unité de temps. Les unités valides sont s pour les secondes, m pour les minutes, h pour les heures et d pour les jours. Par exemple, la valeur 5d spécifie un délai de cinq jours après la première tentative d'exécution de la tâche. Si ce paramètre n'est pas spécifié, la tâche est relancée indéfiniment. Si vous spécifiez également le paramètre task_retry_limit, App Engine réessaie d'exécuter la tâche jusqu'à ce que les deux limites soient atteintes.
<min-backoff-seconds> (files d'attente d'envoi)
Nombre minimal de secondes entre chaque tentative d'exécution d'une tâche ayant échoué. La valeur par défaut est 0.1.
<max-backoff-seconds> (files d'attente d'envoi)
Nombre maximal de secondes entre chaque tentative d'exécution d'une tâche ayant échoué. La valeur par défaut est 3600.
<max-doublings> (files d'attente d'envoi)
Nombre maximal de fois où l'intervalle entre les tentatives d'exécution de tâches ayant échoué est doublé avant que l'augmentation ne devienne constante. La constante est : 2**max_doublings * min_backoff_seconds. La valeur par défaut est 16.
<target> (files d'attente d'envoi)

Facultatif. Chaîne nommant un service ou une version, une version de frontend ou un backend sur lequel exécuter toutes les tâches placées dans cette file d'attente. La valeur par défaut est la chaîne vide.

La chaîne précède le nom de domaine de votre application lors de la construction de la requête HTTP d'une tâche. Par exemple, si votre ID application est my-app et que vous définissez la cible sur my-version.my-service, le nom d'hôte de l'URL sera défini sur my-version.my-service.my-app.appspot.com.

Si la cible n'est pas spécifiée, les tâches sont appelées sur la même version de l'application où elles ont été mises en file d'attente. Par conséquent, si vous avez placé en file d'attente une tâche à partir de la version par défaut de l'application sans indiquer de cible sur la file d'attente, la tâche est appelée dans la version par défaut de l'application. Notez que si la version par défaut de l'application change entre le moment où la tâche est mise en file d'attente et son exécution, la tâche sera exécutée dans la nouvelle version par défaut.

Si vous utilisez des services avec un fichier de distribution, la requête HTTP de votre tâche peut être interceptée et redirigée vers un autre service.

Les éléments suivants peuvent être spécifiés pour toutes les files d'attente au sein d'une application, dans l'élément racine <queue-entries> :

Élément Description
<total-storage-limit>

Facultatif. Chaîne qui remplace la limite du quota de stockage par défaut disponible pour le stockage en file d'attente (100 M). Exemple :


<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

Ce quota fait partie du quota de stockage total de l'application (y compris le quota de datastore et blobstore).

Si aucun suffixe n'est indiqué, le nombre que vous spécifiez est interprété en octets. Les suffixes suivants sont acceptés :

  • B (octets)
  • K (kilo-octets)
  • M (mégaoctets)
  • G (gigaoctets)
  • T (téraoctets)

Si la valeur associée à <total-storage-limit> dépasse l'espace de stockage total sur disque disponible pour une application, la limite est bloquée.

Déployer le fichier de configuration de file d'attente

Le fichier queue.xml doit résider dans le répertoire WEB-INF du service par défaut.

Pour déployer le fichier de configuration de la file d'attente sans modifier la version actuellement diffusée, utilisez la commande suivante :

appcfg.sh update_queues <application directory>

en remplaçant <application directory> par le chemin d'accès au répertoire principal de votre application.

Supprimer des files d'attente

Pour supprimer une file d'attente :

  1. Supprimez la définition de la file d'attente dans le fichier queue.xml.

  2. Importez la modification dans le fichier queue.xml.

    [PATH_TO_APP_ENGINE_SDK]\bin\appcfg.sh update_queues [YOUR_APP_DIR]
    

    Ou sous Windows :

    [PATH_TO_APP_ENGINE_SDK]\bin\appcfg.cmd update_queues [YOUR_APP_DIR]
    
  3. Supprimez la file d'attente dans la console GCP en la sélectionnant et en cliquant sur Supprimer la file d'attente :

    Accéder à la page "Files d'attente de tâches"

Si vous supprimez une file d'attente de la console GCP, vous devez attendre sept jours pour pouvoir recréer une file d'attente portant le même nom.

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

Envoyer des commentaires concernant…

Environnement standard App Engine pour Java 8