Planifier des tâches avec cron.yaml

Le service Cron d'App Engine permet de configurer des tâches planifiées qui s'exécutent à des heures définies ou à intervalles réguliers. Ces tâches sont communément appelées tâches Cron. Elles sont automatiquement déclenchées par le service Cron d'App Engine. Vous pouvez les utiliser, par exemple, pour envoyer un e-mail de rapport quotidien, pour mettre à jour toutes les dix minutes certaines données en cache, ou pour mettre à jour une fois par heure certaines informations récapitulatives.

Une tâche Cron appelle une URL, à l'aide d'une requête HTTP GET, à une heure spécifique de la journée. Une requête HTTP invoquée par une tâche Cron peut être exécutée pour une durée maximale de 60 secondes, mais elle est soumise aux mêmes restrictions que les requêtes HTTP.

Les applications gratuites peuvent gérer jusqu'à 20 tâches planifiées. Les applications payantes peuvent en gérer jusqu'à 250.

À propos du fichier de configuration cron

Un fichier cron.yaml situé dans le répertoire racine de votre application (avec app.yaml) configure les tâches planifiées pour votre application Python. Voici un exemple de fichier cron.yaml :

cron:
- description: "daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
- description: "monday morning mailout"
  url: /mail/weekly
  schedule: every monday 09:00
  timezone: Australia/NSW
- description: "new daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
  target: beta

Le fichier cron.yaml utilise la syntaxe YAML et contient des définitions pour chacune des tâches Cron. Une définition de tâche doit comporter les éléments url et schedule. Vous avez également la possibilité de spécifier les éléments description, timezone, target et retry_parameters :

url
Obligatoire. URL de l'application à laquelle vous souhaitez que le service Cron envoie des requêtes de tâches.
schedule
Obligatoire. Définit le planning d'exécution de la tâche, consultez la syntaxe ci-dessous.
description
Facultatif. Décrit votre tâche Cron, visible depuis la console GCP.
timezone
Facultatif. Nom du fuseau horaire, ou "zoneinfo", que vous souhaitez utiliser pour la planification de la tâche. Si vous ne spécifiez pas de fuseau horaire, la planification utilise le fuseau horaire UTC, également appelé GMT.
target
Facultatif. Nom d'un service spécifique de l'application. Une fois l'élément target spécifié, le service Cron cible la requête de tâche sur ce service dans l'application. Les requêtes de tâches sont acheminées vers les versions du service spécifié configurées pour le trafic. Découvrez comment les requêtes sont acheminées.

Remarques importantes sur l'élément target :

  • Si la répartition du trafic est activée, vos requêtes de tâches ne seront pas réparties entre les versions que vous avez configurées.
    • Répartition par adresse IP : les requêtes de tâches du service Cron sont toujours envoyées à partir de la même adresse IP et sont donc acheminées vers la même version à chaque fois.
    • Répartition par cookie : les requêtes de tâches n'incluent pas de cookie avec la requête et ne sont donc pas acheminées vers d'autres versions.
  • Si vous utilisez un fichier de distribution, vos tâches peuvent être réacheminées lorsque la même URL est également configurée dans le fichier dispatch.yaml. Par exemple, si l'URL /tasks/hello_service2 est définie dans les deux fichiers cron.yaml et dispatch.yaml, les requêtes de tâches sont envoyées à service2, même si target: service1 est spécifié :

    cron.yaml :

    cron:
    - description: "test dispatch vs target"
      url: /tasks/hello_service2
      schedule: every 1 mins
      target: service1

    dispatch.yaml :

    dispatch:
    - url: '*/tasks/hello_service2'
      service: service2
retry_parameters
Facultatif. Indique d'exécuter de nouveau les tâches ayant échoué, consultez la syntaxe ci-dessous.

Définir l'élément schedule des tâches Cron

Les tâches Cron sont planifiées à intervalles réguliers et sont spécifiées à l'aide d'un format simple semblable à l'anglais. Vous pouvez définir un calendrier pour que votre tâche s'exécute plusieurs fois par jour ou à des jours et des mois spécifiques.

Intervalles multiquotidiens

Choisissez un intervalle multiquotidien pour exécuter une tâche plusieurs fois par jour suivant une planification répétitive. Vous pouvez définir un intervalle après heure de fin ou de début :

  • Intervalle après heure de fin : définit le délai entre "l'heure de fin" d'une tâche et le début de la tâche suivante, "l'heure de fin" désignant l'heure à laquelle la tâche se termine ou expire. Le service Cron exécute les tâches associées à ce type d'intervalle tout au long d'une journée de 24 heures, à compter de 00:00, et respecte le délai spécifié avant de déclencher une nouvelle tâche.

    Exemple : pour la planification every 5 minutes, la tâche est exécutée tout au long de la journée à intervalles de cinq minutes. Si une instance de tâche en cours d'exécution selon cette planification se termine à 02h01, la tâche suivante attend cinq minutes et redémarre à 02h06.

  • Intervalle après heure de début : définit un intervalle de temps régulier pour le démarrage de chaque tâche par le service Cron. Contrairement à l'intervalle après heure de fin, l'intervalle après heure de début permet d'exécuter chaque tâche indépendamment du moment où la tâche précédente s'est terminée, et indépendamment du fait que le délai d'expiration soit dépassé. Vous pouvez définir une plage horaire pendant laquelle la tâche sera exécutée, ou planifier l'exécution de tâches 24 heures sur 24 à partir de 00:00.

    Étant donné que l'heure de début d'une tâche est précise, si le temps d'exécution d'une instance de tâche est plus long que l'intervalle de temps défini, le service Cron peut ignorer une tâche. Une heure de début dans l'intervalle peut être ignorée si la tâche précédente n'est pas terminée ou a dépassé le délai d'expiration.

    Exemple : Pour la planification every 5 minutes from 10:00 to 14:00, la première tâche commence à 10:00, puis la tâche s'exécute toutes les cinq minutes. Si la première tâche s'exécute pendant sept minutes, la tâche de 10:05 est ignorée et le service Cron n'exécute aucune autre instance de cette tâche avant 10:10.

Intervalle personnalisé

Vous pouvez appliquer un intervalle personnalisé pour définir une planification selon laquelle votre tâche peut être exécutée une fois par jour, pour un ou plusieurs jours spécifiques et pour un ou plusieurs mois choisis. Les tâches planifiées selon un calendrier personnalisé sont exécutées toute l'année, à l'heure spécifiée des jours et des mois sélectionnés.

Exemple : Pour la planification 1,2,3 of month 07:00, la tâche est exécutée une fois à 07:00 les trois premiers jours de chaque mois.

Remarques importantes sur l'élément schedule :

  • Vous devez décider si vous souhaitez appliquer un intervalle multiquotidien ou un intervalle personnalisé. Vous ne pouvez pas combiner, ni utiliser des éléments de différents types d'intervalles. Voici un exemple de définition de planification non valide : schedule: every 6 hours mon,wed,fri.
  • Une seule instance d'une tâche doit être exécutée à tout moment. Le service Cron est conçu pour assurer une exécution "au moins une fois". Autrement dit, si une tâche est planifiée, App Engine envoie la requête de tâche au moins une fois. Dans de rares cas, il est possible que plusieurs instances de la même tâche fassent l'objet d'une requête. Par conséquent, votre gestionnaire de requêtes doit être idempotent et votre code doit garantir l'absence d'effets secondaires si cela se produit.

Mettre en forme le schedule

Pour spécifier le moment d'exécution de la tâche, vous devez définir l'élément schedule à l'aide de la syntaxe suivante :

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Choisissez un type d'intervalle pour définir l'élément schedule :

Intervalle après heure de fin
  • [TYPE] : les intervalles quotidiens doivent inclure le préfixe every.

    Exemple : schedule: every 12 hours

  • [INTERVAL_VALUE] : une valeur entière et l'unité de temps correspondante. Voici des valeurs valides pour l'unité de temps :
    • minutes ou mins
    • hours
  • [INTERVAL_SCOPE] : non applicable. Pour définir une heure de début ou une plage spécifique d'exécution des tâches, reportez-vous à la syntaxe de l'intervalle après heure de début ou de l'intervalle personnalisé.
Exemples d'intervalles après heure de fin
Les exemples ci-dessous vous aideront à comprendre comment définir des planifications de tâches selon un intervalle après heure de fin :
  • Démarre tous les jours à minuit et attend cinq minutes entre chaque tâche. À la fin de chaque tâche, le service Cron attend cinq minutes avant d'exécuter la tâche suivante :
    schedule: every 5 minutes
  • Démarre tous les jours à minuit et attend 30 minutes entre chaque tâche. À la fin de chaque tâche, le service Cron attend 30 minutes avant d'exécuter la tâche suivante :
    schedule: every 30 mins
Intervalle après heure de début
  • [TYPE] : les intervalles quotidiens doivent inclure le préfixe every.

    Exemple : schedule: every 12 hours

  • [INTERVAL_VALUE] : une valeur entière et l'unité de temps correspondante. Voici des valeurs valides pour l'unité de temps :
    • minutes ou mins
    • hours
  • [INTERVAL_SCOPE] : spécifie une clause qui correspond à [INTERVAL_VALUE]. Vous pouvez définir une période personnalisée ou utiliser l'option synchronized sur 24 heures.
    • Insérez la clause from [HH:MM] to [HH:MM] pour définir une heure de début et une plage spécifiques d'exécution des tâches.

      Vous devez spécifier les valeurs de l'heure au format 24 heures, HH:MM, où :

      • HH sont des valeurs entières allant de 00 à 23 ;
      • MM sont des valeurs entières allant de 00 à 59.
    • Servez-vous de synchronized pour spécifier une période de 24 heures (from 00:00 to 23:59) divisée de manière égale par la valeur [INTERVAL_VALUE].

      Important : [INTERVAL_VALUE] doit diviser 24 en une valeur entière pour éviter qu'une erreur se produise. Les valeurs valides pour [INTERVAL_VALUE] incluent : 1, 2, 3, 4, 6, 8, 12 et 24.

Exemples d'intervalles après heure de début
Les exemples suivants peuvent vous aider à comprendre comment définir des planifications de tâches basées sur un intervalle après heure de début :
  • Exécution toutes les cinq minutes de 10h00 à 14h00, tous les jours :
    schedule: every 5 minutes from 10:00 to 14:00
  • Exécution une fois par heure de 08h00 à 16h00, tous les jours :
    schedule: every 1 hours from 08:00 to 16:00
  • Exécution une fois toutes les deux heures, tous les jours à partir de minuit :
    schedule: every 2 hours synchronized
Intervalle personnalisé
  • [TYPE] : les intervalles personnalisés peuvent inclure le préfixe every pour définir un intervalle répétitif, ou vous pouvez définir une liste spécifique de jours dans un mois.
    • Pour définir un intervalle répétitif, vous pouvez inclure le préfixe every.

      Exemples :

      schedule: every day 00:00
      schedule: every monday 09:00

    • Pour définir des jours spécifiques, vous devez utiliser des nombres ordinaux. Les valeurs valides vont du 1er jour du mois jusqu'au nombre maximal de jours de ce mois, par exemple :
      • 1st ou first
      • 2nd ou second
      • 3rd ou third
      • Et jusqu'au 31st ou thirtyfirst

      Exemple :

      schedule: 1st,3rd tuesday
      schedule: 2nd,third wednesday of month 09:00

  • [INTERVAL_VALUE] : les intervalles personnalisés incluent une liste des jours spécifiques pendant lesquels vous souhaitez que la tâche soit exécutée. Cette liste doit être définie sous forme de liste d'éléments séparés par une virgule et peut inclure l'une des valeurs suivantes :
    • La valeur entière du jour du mois jusqu'à un maximum de 31 jours, par exemple :
      • 1
      • 2
      • 3
      • Et jusqu'à 31
    • Le nom du jour sous forme des valeurs longues ou abrégées qui sont indiquées ci-dessous :
      • monday ou mon
      • tuesday ou tue
      • wednesday ou wed
      • thursday ou thu
      • friday ou fri
      • saturday ou sat
      • sunday ou sun
      • day pour spécifier tous les jours de la semaine

    Exemples :

    schedule: 2nd monday,thu
    schedule: 1,8,15,22 of month 09:00
    schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00

  • [INTERVAL_SCOPE] : spécifie une clause qui correspond à la valeur [INTERVAL_VALUE] spécifiée. Les intervalles personnalisés peuvent inclure la clause of [MONTH], qui spécifie un seul mois dans une année ou une liste de plusieurs mois séparés par des virgules. Vous devez également définir une heure précise pour l'exécution de la tâche, par exemple : of [MONTH] [HH:MM].

    Par défaut, si la clause of est exclue, l'intervalle personnalisé est exécuté tous les mois.

    • [MONTH] : vous devez indiquer les mois sous forme de liste d'éléments séparés par une virgule, et vous pouvez inclure une combinaison des valeurs longues ou abrégées qui sont indiquées ci-dessous :
      • january ou jan
      • february ou feb
      • march ou mar
      • april ou apr
      • may
      • june ou jun
      • july ou jul
      • august ou aug
      • september ou sep
      • october ou oct
      • november ou nov
      • december ou dec
      • month pour spécifier tous les mois de l'année
    • [HH:MM] : vous devez spécifier les valeurs de l'heure au format 24 heures, HH:MM, où :
      • HH sont des valeurs entières allant de 00 à 23 ;
      • MM sont des valeurs entières allant de 00 à 59.
    • Exemple :

      schedule: 1st monday of sep,oct,nov 09:00
      schedule: 1 of jan,april,july,oct 00:00

Exemples d'intervalles personnalisés
Les exemples suivants peuvent vous aider à comprendre comment définir des planifications de tâches basées sur un intervalle personnalisé :
  • Exécution tous les jours à minuit :
    schedule: every day 00:00
  • Exécution tous les lundis à 09h00 :
    schedule: every monday 09:00
  • Exécution une fois le deuxième mercredi de mars à 17h00 :
    schedule: 2nd wednesday of march 17:00
  • Exécution six fois en mai. Pendant les deux premières semaines, la tâche s'exécute une fois les lundi, mercredi et vendredi à 10h00 :
    schedule: 1st,second mon,wed,fri of may 10:00
  • Exécution une fois par semaine. Tous les sept jours à compter du premier jour de chaque mois, la tâche s'exécute une fois à 09h00 :
    schedule: 1,8,15,22 of month 09:00
  • Exécution toutes les deux semaines. Le premier et le troisième lundi de chaque mois, la tâche s'exécute une fois à 04h00 :
    schedule: 1st,third monday of month 04:00
  • Exécution trois fois par an. Les premiers lundis de septembre, d'octobre et de novembre, la tâche s'exécute une fois à 09h00 :
    schedule: 1st monday of sep,oct,nov 09:00
  • Exécution une fois par trimestre. Le premier jour de janvier, avril, juillet et octobre, la tâche s'exécute une fois à minuit :
    schedule: 1 of jan,april,july,oct 00:00

Spécifier de nouvelles tentatives d'exécution

Si le gestionnaire de requêtes d'une tâche Cron renvoie un code d'état qui n'est pas compris entre 200 et 299 (inclus), App Engine considère que cette tâche a échoué. Par défaut, les tâches ayant échoué ne font pas l'objet de nouvelles tentatives. Vous pouvez mettre en place de nouvelles tentatives d'exécution des tâches en échec en incluant un bloc retry_parameters dans le fichier de configuration.

Voici un exemple de fichier cron.yaml contenant une seule tâche Cron configurée pour être relancée jusqu'à cinq fois (valeur par défaut) avec un intervalle initial entre les tentatives de 2,5 secondes qui double à chaque nouvelle tentative.

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    min_backoff_seconds: 2.5
    max_doublings: 5

Syntaxe des nouvelles tentatives d'exécution Cron

Les paramètres des nouvelles tentatives sont décrits dans le tableau ci-dessous.

Élément Description
job_retry_limit Le nombre maximal de nouvelles tentatives d'exécution pour une tâche Cron en échec ne doit pas dépasser "5". Si job_age_limit est également utilisé, App Engine réessaie d'exécuter la tâche Cron jusqu'à ce que les deux limites soient atteintes. Lorsque cet élément est omis dans les paramètres, la limite est définie par défaut sur "5".
job_age_limit Le délai maximal d'une nouvelle tentative d'exécution d'une tâche Cron en échec, mesuré à partir de la première exécution de la tâche Cron. 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 une limite de cinq jours après la première tentative d'exécution de la tâche Cron. Si job_retry_limit est également utilisé, App Engine réessaie d'exécuter la tâche Cron jusqu'à ce que les deux limites soient atteintes.
min_backoff_seconds Nombre minimal de secondes d'attente avant de relancer une tâche Cron après son échec.
max_backoff_seconds Nombre maximal de secondes d'attente avant de relancer une tâche Cron après son échec.
max_doublings 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 la suivante : 2**(max_doublings - 1) * min_backoff.

Valider des requêtes Cron

Vous voudrez peut-être vérifier que les requêtes adressées à vos URL Cron proviennent d'App Engine et non d'une autre source. Vous pouvez effectuer cette vérification en validant un en-tête HTTP et l'adresse IP source de la requête :

  • Les requêtes du service Cron contiennent également un en-tête HTTP :

    X-Appengine-Cron: true
    

    L'en-tête X-Appengine-Cron est défini en interne par Google App Engine. Si votre gestionnaire de requêtes trouve cet en-tête, il peut valider qu'il s'agit d'une requête Cron. Les en-têtes X- sont supprimés par App Engine lorsqu'ils proviennent de sources externes, ce qui vous permet de faire confiance à cet en-tête.

  • Google App Engine émet des requêtes Cron à partir de l'adresse IP 10.0.0.1.

Importer des tâches Cron

Pour importer des tâches Cron, vous devez spécifier le fichier cron.yaml en tant que paramètre dans la commande gcloud suivante :

gcloud app deploy cron.yaml

Supprimer des tâches Cron

Pour supprimer l'ensemble des tâches Cron, modifiez le fichier cron.yaml de manière qu'il contienne uniquement les éléments suivants :

cron:

Afficher des informations sur la tâche

Vous pouvez afficher la version analysée de vos tâches Cron, y compris les heures d'exécution des tâches, à l'aide de la commande appcfg.py cron_info.

Notez que appcfg.py cron_info ne calculera pas correctement les planifications si un fuseau horaire différent de UTC est spécifié.

Disponibilité de Cron dans la console Google Cloud Platform

Vous pouvez vérifier les tâches Cron planifiées sur la page Tâches Cron de la console GCP.

Vous pouvez également consulter la page Journaux pour voir à quel moment des tâches Cron ont été ajoutées ou supprimées.

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

Envoyer des commentaires concernant…

Environnement flexible App Engine pour les documents Python