Fichier de référence cron.xml pour les outils du SDK App Engine

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 avec 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 avec app.yaml : cron.yaml configure les tâches planifiées pour votre application Java 8.

Définitions de tâches Cron

Élément Description
description Facultatif. La description est visible dans la console Google Cloud et dans l'interface d'administration du serveur de développement.
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 cette tâche a échoué. Par défaut, les tâches qui ont é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 votre fichier de configuration.

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

schedule Obligatoire. Planifie l'exécution de la tâche Cron. Consultez 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 le trafic. Consultez la section Mode de routage des requêtes pour en savoir plus.
timezone Le champ timezone doit correspondre à un nom de fuseau horaire zoneinfo standard. Si vous ne spécifiez pas de fuseau horaire, les tâches s'exécutent au format UTC (également appelé GMT).
url Obligatoire. Le champ url est simplement une URL dans votre application. Si l'élément url contient les caractères XML spéciaux &, <, >, ' ou ", vous devez les échapper.

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 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 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 tâche, ou exécuter des tâches 24h/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 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</schedule>.
  • 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]</schedule>

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</schedule>

  • [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 :
  • 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</schedule>
  • 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</schedule>
Intervalle après heure de début
  • [TYPE] : les intervalles quotidiens doivent inclure le préfixe every.

    Exemple : <schedule>every 12 hours</schedule>

  • [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</schedule>
  • Exécution une fois par heure de 08h00 à 16h00, tous les jours :
    <schedule>every 1 hours from 08:00 to 16:00</schedule>
  • Exécution une fois toutes les deux heures, tous les jours à partir de minuit : 
    <schedule>every 2 hours synchronized</schedule>
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>
<schedule>every monday 09:00</schedule>

    • 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>
<schedule>2nd,third wednesday of month 09:00</schedule>

  • [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>
<schedule>1,8,15,22 of month 09:00</schedule>
<schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>

  • [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>
<schedule>1 of jan,april,july,oct 00:00</schedule>

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</schedule>
  • Exécution tous les lundis à 09h00 :
    <schedule>every monday 09:00</schedule>
  • Exécution une fois le deuxième mercredi de mars à 17h00 :
    <schedule>2nd wednesday of march 17:00</schedule>
  • 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</schedule>
  • 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</schedule>
  • 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</schedule>
  • 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</schedule>
  • Exécution une fois par trimestre. Le premier jour de janvier, avril, juillet et octobre, la tâche s'exécute une fois à 00h00 : 
    <schedule>1 of jan,april,july,oct 00:00</schedule>

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

Si le gestionnaire de requêtes de 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 qui ont é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.xml contenant un seul job Cron configuré pour être relancé jusqu'à cinq fois (valeur par défaut) avec un intervalle initial entre les tentatives de 2,5 secondes qui double à chaque nouvelle tentative.

<cronentries>
  <cron>
    <url>/retry</url>
    <description>Retry on jsdk</description>
    <schedule>every 10 minutes</schedule>
    <retry-parameters>
      <min-backoff-seconds>2.5</min-backoff-seconds>
      <max-doublings>5</max-doublings>
    </retry-parameters>
  </cron>
</cronentries>

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 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 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. 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 ce nombre est spécifié avec job_retry_limit, App Engine effectue une nouvelle tentative 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 : 2**(max_doublings - 1) * min_backoff.

Requêtes Cron

En-têtes de requête

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

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, à l'exception des requêtes des administrateurs d'anciennes applications connectés, qui sont autorisés à définir des en-têtes à des fins de test.

Adresse IP d'origine

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.

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.

Limites

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

Disponibilité de Cron dans le serveur de développement

Le serveur de développement n'exécute pas automatiquement les tâches Cron. Vous pouvez utiliser votre interface Cron locale ou l'interface de gestion des tâches planifiées afin de déclencher les URL associées à vos tâches avec curl ou un outil similaire.

Déployer des tâches Cron

Vous pouvez utiliser la CLI gcloud pour déployer vos tâches Cron sur App Engine.

Pour déployer les tâches Cron spécifiées dans votre fichier de configuration cron.yaml, exécutez la commande suivante :

gcloud

    gcloud app deploy cron.yaml

Maven

    mvn appengine:deployCron cron.yaml

Gradle

    gradle appengineDeployCron cron.yaml

IDE

Si vous utilisez IntelliJ ou Eclipse, vous pouvez sélectionner chaque fichier de configuration à déployer à l'aide du formulaire de déploiement.

Supprimer toutes les tâches Cron

Pour supprimer toutes les tâches Cron :

  1. Remplacez le contenu du fichier cron.yaml par ce qui suit :

    cron:

  2. Déployez le fichier cron.yaml sur App Engine.

Disponibilité de Cron dans Google Cloud Console

La page Files d'attente de tâches de la console Google Cloud comporte un onglet affichant les tâches qui exécutent des tâches Cron.

Vous avez également la possibilité de consulter la page sur les journaux pour savoir quand des tâches Cron ont été ajoutées ou supprimées.