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

Définissez les tâches planifiées pour votre application à l'aide du fichier cron.xml.

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.xml :

<?xml version="1.0" encoding="UTF-8"?>
<cronentries>
  <cron>
    <url>/recache</url>
    <description>Repopulate the cache every 2 minutes</description>
    <schedule>every 2 minutes</schedule>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
    <target>version-2</target>
  </cron>
</cronentries>

Pour obtenir un XSD décrivant le format, consultez le fichier docs/cron.xsd dans le SDK.

Syntaxe

Le fichier cron.xml doit se trouver dans le répertoire WEB-INF de votre application avec appengine-web.xml : le fichier cron.xml configure les tâches planifiées pour l'application Java.

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.
<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 du trafic.Pour obtenir plus d'informations sur le routage, consultez la page Mode de routage des requêtes.

<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 pour les 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 de fin ou de début :

  • Intervalle 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 avec ce type d'intervalle tout au long d'une journée de 24 heures, à compter de 00:00, et respecte la durée spécifiée entre chaque 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 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 de fin, l'intervalle 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 planifier une seule exécution de la tâche par jour, pour un ou plusieurs jours spécifiques et pour un ou plusieurs mois spécifiques. Les tâches planifiées selon un calendrier personnalisé sont exécutées toute l'année à l'heure spécifiée, pour chacun 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 le 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 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]</schedule>

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

Intervalle 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, 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 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 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 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 de début
Les exemples suivants peuvent vous aider à comprendre comment définir des planifications de tâches basées sur un intervalle 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 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>
      <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 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>
    <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 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>
      <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 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.xml 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 fois.

<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 cinq. 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> Délai maximal entre chaque tentative d'exécution d'une tâche Cron ayant échoué, mesuré à partir du moment où elle a été exécutée pour la première fois. 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 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> Nombre maximal de fois où l'intervalle entre les nouvelles tentatives de tâche Cron en échec 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 obtenir plus d'informations, consultez la page sur 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.

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 vous servir de l'outil appcfg.sh pour déployer vos tâches Cron sur App Engine.

Option 1 : Importer l'ensemble de l'application

Pour importer l'ensemble de votre application, qui met également à jour le service Cron avec les entrées de votre fichier cron.xml, exécutez la commande suivante :

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
Option 2 : Importer uniquement les mises à jour Cron

Si vous ne souhaitez que mettre à jour la configuration Cron sans importer le reste de l'application, exécutez la commande suivante :

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]

Supprimer toutes les tâches Cron

Pour supprimer toutes les tâches Cron :

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

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries/>
    
  2. Déployez le fichier cron.xml sur App Engine.

Disponibilité de Cron dans la console GCP

La page Files d'attente de tâches de la console GCP comporte un onglet dans lequel vous pouvez voir 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.

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

Envoyer des commentaires concernant…

Environnement standard App Engine pour Java