Documentation de référence sur le fichier queue.yaml

Les applications qui gèrent les files d'attente de tâches à l'aide du SDK App Engine les définissent à l'aide d'un fichier de configuration appelé queue.yaml. Vous pouvez vous servir du fichier queue.yaml pour configurer aussi bien les files d'attente d'envoi que les files d'attente de retrait. Toutefois, ce fichier de configuration est facultatif pour les files d'attente d'envoi, qui disposent d'une file d'attente par défaut. En revanche, les files d'attente de retrait doivent être configurées spécifiquement dans un fichier queue.yaml.

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 du 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 une ou 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 (seau à jetons) pour contrôler le taux d'exécution des tâches. Chaque file d'attente nommée comprend un "token bucket" 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 des jetons dans le bucket en fonction du taux que vous avez spécifié pour la file d'attente.

La taille du bucket permet de limiter le taux de traitement lorsque de nombreuses tâches se trouvent dans la file d'attente et que le taux est élevé. La valeur maximale de 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 lorsque de nombreuses tâches sont placées en file d'attente sur 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 cette taille par défaut peut se révéler insuffisante dans de nombreux cas d'utilisation : la taille recommandée correspond au taux de traitement divisé par 5 (taux/5).

max_concurrent_requests (files d'attente d'envoi)

Facultatif. Définit le nombre maximal de tâches pouvant s'exécuter simultanément à partir 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. Sachez que l'exécution simultanée des files d'attente risque d'être plus lente lorsque celles-ci 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 d'empêcher l'exécution simultanée d'un trop grand nombre de tâches. Cela peut également éviter les conflits dans le datastore et libérer des ressources pour d'autres files d'attente ou pour le traitement en ligne.

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 cinq tâches par seconde, mais vous pouvez modifier ce taux en définissant 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, celle-ci ne se sera pas affichée dans la console Google Cloud Platform tant qu'elle n'aura pas été utilisée. 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 à un taux de 5 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.

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 tentatives peuvent contenir les sous-éléments suivants :

task_retry_limit
Il s'agit d'une limite globale du nombre maximal de tentatives pour une tâche. Si vous spécifiez 0 ou 1 et que la tâche échoue, celle-ci n'est pas relancée. Si vous spécifiez ce paramètre ainsi que le paramètre task_age_limit, la tâche est relancée jusqu'à ce que les deux limites soient atteintes. Enfin, si vous ne spécifiez pas ce paramètre, la tâche est relancée indéfiniment.
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ù 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 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 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/une version de service, 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.

Cette chaîne précède le nom de domaine de votre application lors de la création de la requête HTTP d'une tâche. Par exemple, si votre ID d'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 dans la même version de l'application que celle dans laquelle elles ont été mises en file d'attente. Par conséquent, si vous avez mis en file d'attente une tâche à partir de la version par défaut de l'application sans indiquer de cible pour la file d'attente, la tâche est appelée dans la version par défaut de l'application. Sachez 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 :

É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 Mo). Exemple :


total_storage_limit: 1.2G
queue:
  - name: fooqueue

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

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

  • B (octets)
  • K (kilo-octets)
  • M (méga-octets)
  • 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 la 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

gcloud app deploy queue.yaml

appcfg

Si vous installez le SDK App Engine d'origine, exécutez cette commande :

appcfg.py update_queues [YOUR_APP_DIR]

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

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

    gcloud app deploy queue.yaml
    

  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 avant de 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 Python