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 :

• Propriétaire
• Éditeur
• Administrateur Cloud Scheduler (roles/cloudscheduler.admin)

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.

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 :

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.

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

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.