Documentation de référence du fichier queue.yaml

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

Le fichier de configuration queue.yaml permet de créer et de configurer presque toutes les files d'attente de tâches (push ou pull) utilisée par votre application. Toutes les applications App Engine disposent d'une file d'attente d'envoi préconfigurée nommée default. Bien que vous ne créiez pas la file d'attente default vous-même, vous pouvez ajouter d'autres files d'attente ou modifier la configuration de la file d'attente default à l'aide du fichier queue.yaml.

Pour les applications Java, ce fichier est stocké n'importe où dans le répertoire du code source.

Pour configurer des files d'attente d'envoi, vous pouvez utiliser les méthodes queue.yaml ou Gestion des files d'attente de Cloud Tasks, mais pas les deux en même temps. Combiner la méthode d'importation queue.yaml avec les méthodes de gestion des files d'attente peut produire des résultats inattendus et n'est pas recommandé.

Pour configurer les files d'attente de retrait, vous devez utiliser le fichier queue.yaml.

Attention : L'importation d'un fichier queue.yaml via une version de gcloud CLI inférieure à la version 332.0.0 utilise une interface obsolète pour le service. À compter du 2022-09-20, les tentatives d'utilisation de la méthode d'importation peuvent échouer en renvoyant des erreurs de serveur. Pour résoudre ce problème, assurez-vous que l'API Cloud Tasks est activée dans votre projet et que gcloud CLI a été mis à jour vers la version 332.0.0 ou une version ultérieure.

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:
- name: my-push-queue
  rate: 1/s

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

queue:
- name: fooqueue
  rate: 1/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d
- name: barqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 0
- name: bazqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 3

Syntaxe

Le fichier queue.yaml est un fichier YAML dont la directive racine est queue. Cette directive contient plusieurs files d'attente nommées, ou aucune. 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 token bucket (seau à jetons) 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. Par exemple, vous pouvez déterminer la taille de votre bucket en fonction du taux de traitement. 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 avez fourni lors de l'appel de la méthode 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 cinq tâches par seconde. Notez que cette file d'attente par défaut ne s'affiche dans la console Google Cloud qu'après sa première utilisation ou configuration. Vous pouvez configurer la file d'attente par défaut, y compris modifier le taux par défaut, en définissant une file d'attente nommée "default" dans votre fichier queue.yaml.
<rate> (files d'attente d'envoi)	Obligatoire. Fréquence à laquelle les tâches sont traitées sur cette file d'attente. Sa valeur représente 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 à une fréquence de cinq fois par minute. La valeur maximale de 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 limitant les tentatives d'exécution d'une tâche ayant échoué, défini à partir du moment où la tâche a été exécutée pour la première fois. Sa valeur est un nombre suivi d'une unité de temps : s pour les secondes, m pour les minutes, h pour les heures et d pour les jours. Par exemple, la valeur 5d indique une limite 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 ce paramètre ainsi que 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 d'attente 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 d'attente 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 l'ID de votre application est my-app et que vous définissez "target" (cible) sur my-version-dot-my-service, le nom d'hôte de l'URL sera défini sur my-version-dot-my-service-dot-my-app.REGION_ID.r.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 dispatch, la requête HTTP de votre tâche peut être interceptée et réacheminé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 :

É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 <total-storage-limit> dépasse l'espace de stockage sur disque total disponible pour une application, elle est rabaissée automatiquement de façon à ne pas excéder l'espace de stockage disponible.

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

Le fichier queue.yaml peut se trouver n'importe où dans le répertoire du code source.

Pour déployer le fichier de configuration de file d'attente sans modifier la version actuellement diffusée, exécutez l'une des commandes suivantes dans le répertoire contenant ce fichier, selon votre environnement :

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

Si vous utilisez IntelliJ ou Eclipse, vous pouvez sélectionner chaque fichier de configuration à déployer à l'aide du formulaire de déploiement.

Supprimer des files d'attente

Pour supprimer une file d'attente :

1. Supprimez la définition de la file d'attente du fichier queue.yaml.

2. Importez la modification apportée à votre fichier queue.yaml.

   gcloud app deploy queue.yaml

3. Supprimez la file d'attente dans la console Google Cloud 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 Google Cloud, vous devez attendre sept jours avant de pouvoir recréer une file d'attente portant le même nom.