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. Ces tâches Cron 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, ou pour mettre à jour des données mises en cache toutes les 10 minutes ou des informations récapitulatives une fois par heure.

Un job Cron envoie une requête HTTP GET planifiée vers le point de terminaison spécifié dans l'application où le job Cron est configuré. Le gestionnaire de ce point de terminaison exécute la logique lors de l'appel.

Le service Cron d'App Engine ne peut pas être utilisé pour appeler des points de terminaison Web en dehors de l'application hôte App Engine. Vous ne pouvez pas l'utiliser pour appeler des points de terminaison App Engine à partir d'autres applications en dehors de l'application hôte.

Les requêtes de jobs Cron sont soumises aux mêmes limites que les autres requêtes HTTP. Les applications gratuites peuvent gérer jusqu'à 20 tâches planifiées. Les applications payantes peuvent en gérer jusqu'à 250.

Pour déployer ou mettre à jour les planifications, votre compte requiert l'un des rôles de gestion de l'authentification et des accès suivants :

Vous pouvez définir l'autorisation sur la page "IAM" dans Google Cloud Console.

À propos du fichier de configuration cron

Pour tous les environnements d'exécution, à l'exception de Java, un fichier cron.yaml situé dans le répertoire racine de votre application (avec le fichier app.yaml) configure les tâches planifiées pour votre application.

Pour Java, un fichier cron.yaml situé dans le répertoire WEB-INF de votre application (avec le fichier app.yaml) configure les tâches planifiées pour votre application.

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 pouvez également spécifier les éléments description, timezone, target et retry_parameters :

url
Champ obligatoire. URL de l'application à laquelle vous souhaitez que le service Cron envoie des requêtes de tâches.
schedule
Champ obligatoire. Planifie l'exécution de la tâche. Consultez la syntaxe ci-dessous.
description
Champ facultatif. Décrit votre tâche Cron, qui est visible depuis la console Google Cloud et l'interface d'administration du serveur de développement local.
timezone
Champ 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
Champ 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 le mode de routage des requêtes.

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 routé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 fichiers cron.yaml et dispatch.yaml suivants, 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
Champ facultatif. Indique d'exécuter de nouveau les tâches ayant échoué. Consultez la syntaxe ci-dessous.

Définir l'élément schedule d'un job 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 jobs associés à ce type d'intervalle tout au long d'une journée de 24 heures, à compter d'un intervalle après l'heure de création/mise à jour du job, et respecte l'intervalle spécifié entre chaque job.

    Exemple : pour la planification every 5 minutes, la tâche est exécutée quotidiennement à 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 période pendant laquelle vous souhaitez exécuter votre job, ou exécuter des jobs 24h/24 à partir du début de la période spécifiée.

    É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 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 de tâche doit être exécutée. 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 l'élément 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, consultez 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 :
  • Attend cinq minutes après le déploiement pour s'exécuter la première fois. À la fin de chaque job, le service Cron attend 30 minutes avant d'exécuter le job suivant : 
    schedule: every 5 minutes
  • Attend 30 minutes après le déploiement pour s'exécuter la première fois. À la fin de chaque job, le service Cron attend 30 minutes avant d'exécuter le job suivant : 
    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 entiers allant de 00 à 23.
      • MM sont des entiers 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 premier 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 de valeurs longues ou abrégées, comme indiqué 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 de valeurs longues ou abrégées comme indiqué 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 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 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 définir de nouvelles tentatives d'exécution pour les 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 être relancée jusqu'à cinq fois 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:
    job_retry_limit: 5
    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 Entier représentant le nombre maximal de nouvelles tentatives pour une tâche Cron ayant échoué. La valeur minimale est 0 et la valeur maximale 5. Si vous spécifiez également job_age_limit, App Engine relance la tâche Cron jusqu'à ce qu'elle atteigne les deux limites. La valeur par défaut de job_retry_limit est 0.
job_age_limit Délai maximal d'une nouvelle tentative d'exécution d'une tâche Cron ayant échoué, mesuré à partir de la première exécution de la tâche Cron. La valeur représente un nombre suivi d'une unité de temps, à savoir s pour les secondes, m pour les minutes, h pour les heures ou 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 vous spécifiez également job_retry_limit, App Engine relance la tâche Cron jusqu'à ce qu'elle atteigne les deux limites.
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 : 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 l'en-tête HTTP suivant :

    "X-Appengine-Cron": "true"

    Cet en-tête et les autres en-têtes sont définis en interne par App Engine. Si un client envoie ces en-têtes, ils sont supprimés de la requête,

  • App Engine émet des requêtes Cron à partir de l'adresse IP 0.1.0.2. Pour les tâches Cron créées avec des versions anciennes de gcloud (antérieures à la version 326.0.0), les requêtes Cron proviennent de 0.1.0.1.

Dans les environnements d'exécution Java, dans Jetty ou Tomcat, vous pouvez effectuer cette validation dans un filtre.

Délai avant expiration de la requête

Le délai avant expiration de la requête Cron dépend du type de scaling configuré pour l'application:

Scaling automatique
Délai avant expiration de la requête de 10 minutes.
Scaling de base et scaling manuel
Délai avant expiration de la requête de 24 heures.

Pour en savoir plus, consultez la section Mode de gestion des instances.

Pour en savoir plus sur les délais avant expiration des requêtes par environnement et par type de scaling, consultez la page Choisir un environnement App Engine.

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 afin qu'il ne contienne que l'élément suivant :

cron:

Disponibilité de Cron dans Google Cloud Console

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

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