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

Utilisez le fichier cron.yaml pour définir des tâches planifiées pour votre application.

Pour en savoir plus sur la planification des tâches, y compris sur la façon de tester, déployer ou supprimer des tâches Cron, consultez la page Planifier des tâches à l'aide de Cron.

Exemple

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

Syntaxe

Le fichier cron.yaml doit se trouver dans le répertoire racine de votre application à côté du fichier app.yaml : le fichier cron.yaml configure les tâches planifiées pour votre application Python.

Pour en savoir plus sur le format YAML, consultez le site Web YAML.

Définitions de tâches Cron

Élément Description
description Facultatif. La description est visible dans la console GCP et l'interface d'administration du serveur de développement. Sa valeur doit être indiquée entre guillemets.
retry_parameters Facultatif. Si le gestionnaire de requêtes d'une tâche Cron renvoie un code d'état HTTP qui n'est pas compris entre 200 et 299 (inclus), App Engine considère que la 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 ayant échoué en incluant un bloc retry-parameters dans votre fichier de configuration.

Consultez la section Nouvelles tentatives d'exécution de tâche Cron pour plus d'informations.

schedule Obligatoire. Cet élément planifie l'exécution de la tâche Cron (voir la syntaxe ci-dessous).
target

La chaîne target est ajoutée devant le nom d'hôte de votre application. Il s'agit généralement du nom d'un service. La tâche Cron sera acheminée vers la version du service nommé qui est configuré pour le trafic.

Si le nom de service spécifié pour target est introuvable, la requête Cron est acheminée vers le service default ou vers la version de votre application configurée pour recevoir du trafic. Pour en savoir plus sur le routage, consultez la page Mode de routage des requêtes.

Si vous utilisez un fichier de distribution, vos tâches peuvent être réacheminées. Par exemple, avec les fichiers cron.yaml et dispatch.yaml, la tâche sera exécutée dans service2, même si sa cible est service1 :


# 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
timezone Le champ timezone doit correspondre à un nom de fuseau horaire zoneinfo standard. Si vous n'indiquez pas de fuseau horaire, la planification utilise le format UTC (également appelé GMT).
url Obligatoire. Le champ url spécifie une URL dans votre application qui sera appelée par le service Cron. Pour en savoir plus, consultez la section Sécuriser des URL pour Cron.

Définir l'élément schedule pour les tâches Cron

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

Intervalles sous-quotidiens

Utilisez un intervalle sous-quotidien pour exécuter une tâche plusieurs fois par jour selon un horaire répétitif. Vous pouvez définir un intervalle de fin ou de début :

  • Intervalle de fin : définit l'intervalle de temps 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 est terminée ou a expiré. Le service Cron exécute les tâches dans ce type d'intervalle tout au long de la journée de 24 heures, en commençant à 00:00, et attend pendant la durée spécifiée entre chaque tâche.

    Exemple : Pour la planification "every 5 minutes", la tâche est exécutée quotidiennement à intervalles de 5 minutes. Si une instance de tâche en cours d'exécution selon cette planification se termine à 02:01, la tâche suivante attend 5 minutes et redémarre à 02:06.

  • Intervalle de début : définit un intervalle régulier de démarrage de chaque tâche par le service Cron. Contrairement à l'intervalle de fin, l'intervalle de début exécute chaque tâche indépendamment du moment où la tâche précédente est terminée ou a expiré. 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.

    Comme l'heure de début d'une tâche est stricte, si l'exécution d'une instance de tâche dure plus longtemps que l'intervalle défini, le service Cron peut ignorer une tâche. Une heure de début particulière dans l'intervalle peut être ignorée si la tâche précédente n'est pas terminée ou n'a pas expiré.

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

Intervalle personnalisé

Définissez un intervalle personnalisé dans votre planification si vous souhaitez que la tâche soit exécutée une fois par jour, sur un ou plusieurs jours et pendant un ou plusieurs mois. Les tâches planifiées selon un calendrier personnalisé sont exécutées toute l'année, uniquement à l'heure spécifiée les jours et les 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.

Considérations importantes concernant l'élément schedule :

  • Vous devez décider si vous souhaitez utiliser un intervalle sous-quotidien ou personnalisé. Vous ne pouvez pas combiner 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 de 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 peut arriver que des requêtes soient envoyées pour plusieurs instances d'une même tâche. 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.

Formater l'élément schedule

Pour spécifier le moment où votre tâche doit être exécutée, vous devez définir l'élément schedule en utilisant la syntaxe suivante :

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

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

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

    Exemple : schedule: every 12 hours

  • [INTERVAL_VALUE] : valeur entière et unité de temps correspondante. 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 de début ou de l'intervalle personnalisé.
Exemples d'intervalles de fin
Les exemples ci-dessous vous aideront à comprendre comment définir des planifications de tâches selon un intervalle de fin :
  • Démarre tous les jours à minuit et attend 5 minutes entre chaque tâche. À la fin de chaque tâche, le service Cron attend 5 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 de début
  • [TYPE] : les intervalles quotidiens doivent inclure le préfixe every.

    Exemple : schedule: every 12 hours

  • [INTERVAL_VALUE] : valeur entière et unité de temps correspondante. Valeurs valides pour l'unité de temps :
    • minutes ou mins
    • hours
  • [INTERVAL_SCOPE] : spécifie une clause correspondant à la valeur [INTERVAL_VALUE]. Vous pouvez définir une plage de temps personnalisée ou utiliser l'option 24 heures synchronized.#NOTYPO
    • 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, sachant que :

      • HH sont des entiers allant de 00 à 23.
      • MM sont des entiers allant de 00 à 59.
    • Choisissez l'option synchronized pour spécifier une plage horaire de 24 heures (from 00:00 to 23:59) divisée de manière égale par la valeur [INTERVAL_VALUE].

      Important : La valeur [INTERVAL_VALUE] doit diviser le chiffre 24 en un nombre entier, sinon une erreur se produit. Les valeurs valides pour [INTERVAL_VALUE] incluent : 1, 2, 3, 4, 6, 8, 12 ou 24.

Exemples d'intervalles de début
Les exemples suivants vous aideront à comprendre comment définir des planifications de tâches à l'aide d'un intervalle d'heure de début :
  • Exécution toutes les 5 minutes de 10:00 à 14:00, tous les jours :
    schedule: every 5 minutes from 10:00 to 14:00
  • Exécution toutes les 5 minutes de 08:00 à 16:00, 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. Vous pouvez également définir une liste de jours spécifiques dans le mois :
    • Pour définir un intervalle répétitif, utilisez 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 dans 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 de jours spécifiques pendant lesquels la tâche doit être exécutée. La liste doit être au format séparé par des virgules 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 dans une combinaison des valeurs longues ou abrégées suivantes :
      • monday ou mon
      • tuesday ou tues
      • wednesday ou wed
      • thursday ou thurs
      • friday ou fri
      • saturday ou sat
      • sunday ou sun
      • Utilisez day pour spécifier tous les jours de la semaine.

    Exemples :

    schedule: 2nd monday,thurs
    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 correspondant à 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 d'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.

    • [MOIS] : vous devez spécifier les mois dans une liste au format séparé par des virgules et pouvez inclure une combinaison des valeurs longues ou abrégées suivantes :
      • 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
      • Utilisez 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, sachant que :
      • HH sont des entiers allant de 00 à 23.
      • MM sont des entiers 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 vous aideront à comprendre comment définir des planifications de tâches à l'aide d'un intervalle personnalisé :
  • Tous les jours à minuit :
    schedule: every day 00:00
  • Tous les lundis à 09:00 :
    schedule: every monday 09:00
  • Une fois le deuxième mercredi de mars à 17:00 :
    schedule: 2nd wednesday of march 17:00
  • Six fois en mai. Pendant les deux premières semaines, la tâche s'exécute une fois les lundi, mercredi et vendredi à 10:00 :
    schedule: 1st,second mon,wed,fri of may 10:00
  • Une fois par semaine. Tous les sept jours à compter du premier jour de chaque mois, la tâche s'exécute une fois à 09:00 :
    schedule: 1,8,15,22 of month 09:00
  • Toutes les deux semaines. Le premier et le troisième lundi de chaque mois, la tâche s'exécute une fois à 04:00 :
    schedule: 1st,third Monday of month 04:00
  • Trois fois par an. Le premier lundi de septembre, d'octobre et de novembre, la tâche s'exécute une fois à 09:00 :
    schedule: 1st monday of sep,oct,nov 09:00
  • Une fois par trimestre. Le premier jour de janvier, d'avril, de juillet et d'octobre, s'exécute une fois à minuit.
    schedule: 1 of jan,april,july,oct 00:00

Nouvelles tentatives d'exécution de tâches Cron

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 la 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 ayant échoué 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 effectuer jusqu'à cinq nouvelles tentatives (valeur par défaut), avec un intervalle entre les tentatives de 2,5 secondes qui double à chaque fois.

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 de nouvelle tentative sont décrits dans le tableau ci-dessous.

Élément Description
job_retry_limit Le nombre maximal de nouvelles tentatives d'exécution d'une tâche Cron en échec ne doit pas dépasser 5. Si ce nombre est spécifié avec job_age_limit, App Engine effectue une nouvelle tentative jusqu'à ce que les deux limites soient atteintes. Lorsque cet élément n'est pas spécifié dans les paramètres, la limite est définie par défaut sur 5.
job_age_limit 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. 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 la limite est spécifiée avec l'option job_retry_limit, App Engine effectue une nouvelle tentative d'exécution de la tâche Cron jusqu'à ce que les deux limites soient atteintes.
min_backoff_seconds Nombre minimal de secondes d'attente avant d'effectuer une nouvelle tentative d'exécution d'une tâche Cron après échec.
max_backoff_seconds Nombre maximal de secondes d'attente avant d'effectuer une nouvelle tentative d'exécution d'une tâche Cron après échec.
max_doublings Le nombre maximal de fois où l'intervalle entre les nouvelles tentatives de tâches Cron ayant échoué sera doublé avant que l'augmentation ne devienne constante. La constante est la suivante : 2**(max_doublings - 1) * min_backoff.

Requêtes Cron

En-têtes de requêtes

Les requêtes du service Cron contiennent 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 le gestionnaire de requêtes trouve cet en-tête, il peut valider qu'il s'agit d'une requête Cron. Si l'en-tête est présent dans une requête d'utilisateur externe adressée à votre application, il est supprimé, sauf dans les requêtes des administrateurs connectés de l'application qui sont autorisés à définir des en-têtes à des fins de test.

Adresse IP d'origine

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

Délais

Le délai avant expiration dans Cron dépend de la classe d'instance et du type de scaling configurés pour votre application :

Scaling automatique
Le délai avant expiration est d'environ 10 minutes.
Scaling de base et scaling manuel
Le délai avant expiration peut aller jusqu'à 24 heures.

Pour en savoir plus, consultez la section concernant les types de scaling et les classes d'instance.

Limites

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

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

Envoyer des commentaires concernant…

Environnement standard App Engine pour Python