Tâches Cron Orbit

Les tâches cron planifient des requêtes HTTP récurrentes vers votre projet déployé, afin qu'un nettoyage nocturne, une synchronisation horaire ou un résumé hebdomadaire s'exécute à l'heure sans que vous ayez à configurer un planificateur distinct.

Où vivent les tâches cron

Ouvrez Orbit, cliquez sur le projet et choisissez Crons sous le groupe Configure dans la bande d'onglets du projet. La page s'intitule Cron jobs et décrit ce qu'elle fait : planifier des requêtes HTTP vers votre déploiement en production, en utilisant la syntaxe cron standard à cinq champs en UTC, ou les alias @hourly, @daily, @weekly et @monthly.

La page affiche l'hôte cible qu'elle appellera, vous pouvez donc vérifier d'un coup d'œil qu'il pointe vers le bon déploiement.

Comment cela fonctionne

Orbit n'exécute pas votre code dans un planificateur. Il appelle une URL de votre propre projet selon un calendrier, et votre code effectue le travail.

Cela signifie que ce que vous planifiez est une route ordinaire de votre application, par exemple /api/cron/cleanup. Tout ce que votre application peut faire en réponse à une requête, elle peut le faire selon un calendrier.

Créer une tâche cron

1. Cliquez sur New cron.
2. Donnez-lui un Name, jusqu'à 120 caractères.
3. Définissez le Path sur votre projet, en commençant par une barre oblique.
4. Choisissez un Schedule parmi les présets ou tapez une expression.
5. Choisissez une Method. GET est la valeur par défaut.
6. Ajoutez un Request body si la méthode est POST, PUT ou PATCH.
7. Définissez un Timeout entre 1 et 300 secondes. La valeur par défaut est 30.
8. Laissez l'option Generate a Bearer secret cochée sauf si vous avez votre propre authentification.
9. Cliquez sur Create cron.

Présets de planning

Ou écrivez votre propre expression à cinq champs : minute, heure, jour du mois, mois, jour de la semaine.

Authentifier l'appel

Si vous laissez l'option de secret Bearer cochée, un jeton aléatoire est généré et envoyé en tant que header Authorization lors de chaque exécution. Il est affiché une fois, immédiatement après la création, avec une note indiquant qu'il ne sera plus jamais affiché.

Copiez-le et vérifiez-le dans votre gestionnaire :

export async function GET(req) {
  const auth = req.headers.get('authorization');
  if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 });
  }
  // do the work
}

Stockez le secret à l'aide des variables d'environnement du projet : voir Variables d'environnement dans Orbit.

Vous pouvez également envoyer vos propres en-têtes à la place, si votre application a déjà un schéma d'authentification.

Lire la liste des tâches

Chaque tâche affiche :

• Schedule, l'expression selon laquelle elle s'exécute.
• Next, quand elle s'exécutera ensuite.
• Last, quand elle s'est exécutée pour la dernière fois et comment cela s'est passé.
• Un compteur ok / fail.
• Last error, où l'échec le plus récent a laissé un message.
• Un badge PAUSED quand elle est désactivée.

Quatre actions se trouvent sur chaque ligne : Run now, Pause ou Resume, et Delete.

Run now exécute la tâche immédiatement, indépendamment de son calendrier, et rapporte le résultat. C'est la bonne façon de tester une nouvelle tâche plutôt que d'attendre le prochain tick.

Résultats d'exécution

Chaque exécution est enregistrée avec son statut, son code de réponse, sa durée, son erreur et ce qui l'a déclenchée, donc une tâche qui échoue par intermittence laisse une trace que vous pouvez lire plutôt qu'un seul « last error ».

Choisir un délai d'expiration

Le délai d'expiration est par exécution, entre 1 et 300 secondes, par défaut 30.

Définissez-le un peu au-dessus du pire cas réel de la tâche, pas beaucoup au-dessus. Un délai d'expiration généreux sur une tâche qui s'est bloquée signifie cinq minutes d'un constructeur qui attend sans rien. Un délai d'expiration serré sur une tâche qui prend légitimement deux minutes signifie un échec permanent et une alerte trompeuse.

Encore mieux, gardez le gestionnaire rapide : enfilez le travail et retournez immédiatement, plutôt que de faire le travail en ligne. Une tâche cron qui retourne en 200 millisecondes ne dépassera jamais le délai.

Limites

Un projet peut contenir jusqu'à 50 tâches cron. C'est par projet, donc un compte avec plusieurs projets en a plus au total.

Si vous devez planifier quelque chose contre la staging plutôt que la production, utilisez à la place les Cron triggers dans Settings. Cette carte vous permet de choisir l'environnement et est plafonnée à dix déclencheurs par projet. Voir Paramètres du projet Orbit.

Supprimer une tâche

Cliquez sur Delete et confirmez. La confirmation note que l'historique d'exécution sera également supprimé, donc si vous voulez un enregistrement du comportement d'une tâche, capturez-le avant de supprimer.

Mettez en pause plutôt que de supprimer lorsque vous arrêtez temporairement une tâche. La mise en pause préserve la configuration, le secret et l'historique.

Conseils pratiques

Rendez les gestionnaires idempotents. Un appel cron peut être retentée, et Run now peut être pressé pendant qu'une exécution planifiée est déjà en cours. Votre gestionnaire doit être capable de s'exécuter deux fois sans faire le travail deux fois.

Ne planifiez pas tout à l'heure pile. 0 * * * * sur chaque tâche signifie que chaque tâche entre en concurrence au même moment. Espacez-les : 7 * * * *, 23 * * * *, et ainsi de suite.

Enregistrez dans votre gestionnaire. L'enregistrement d'exécution vous indique le code de réponse et la durée. Ce qui s'est réellement produit relève du ressort de votre application, et vous en aurez besoin quand une tâche ne fait silencieusement rien.

Dépannage

Chaque exécution est FAILED avec un 401. Votre gestionnaire rejette la requête. Vérifiez que le secret stocké dans vos variables d'environnement correspond à celui généré ici, y compris le préfixe Bearer dans la comparaison.

Chaque exécution est FAILED avec un 404. Le chemin n'existe pas sur le projet déployé. Testez-le dans un navigateur contre l'hôte cible affiché sur la page.

Les exécutions TIMEOUT. Le gestionnaire en fait trop en ligne. Divisez le travail ou augmentez le délai si le travail prend vraiment ce temps et n'est pas une boucle infinie.

Next n'avance jamais. La tâche est en pause. Cherchez le badge PAUSED.

La tâche s'exécute à la mauvaise heure. Vérifiez UTC par rapport à votre heure locale. C'est la surprise la plus courante avec les tâches planifiées.

Où aller ensuite

• Variables d'environnement dans Orbit pour stocker le secret cron.
• Paramètres du projet Orbit pour les déclencheurs cron par environnement.
• Webhooks Orbit pour être averti quand les choses tournent mal.