Documentation de référence sur le 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

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.yaml. Vous pouvez utiliser le fichier queue.yaml pour configurer des files d'attente d'envoi. Toutefois, ce fichier de configuration est facultatif pour les files d'attente d'envoi, qui ont une file d'attente par défaut.

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

name

Obligatoire. Nom de la file d'attente.

Un nom de file d'attente peut être composé de lettres majuscules et minuscules, de chiffres et de 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, mais vous pouvez modifier ce taux en spécifiant une file d'attente par défaut dans le fichier queue.yaml. Si vous ne configurez pas de file d'attente par défaut dans le fichier queue.yaml, la file d'attente par défaut ne s'affiche dans Google Cloud Console qu'après 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 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

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

Le fichier queue.yaml doit se trouver dans le répertoire racine ou dans le répertoire qui définit le service par défaut.

Pour déployer le fichier de configuration de la file d'attente, exécutez la commande suivante :

gcloud app deploy queue.yaml

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 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, vous devez attendre sept jours pour pouvoir recréer une file d'attente portant le même nom.