Tâches planifiées

Le scheduler du SDK exécute les tâches récurrentes d'une application. Vous enregistrez une entrée nommée avec une expression cron ; à chaque échéance, le scheduler lance une tâche ou envoie une requête POST à une route de votre application. Chaque application ne voit et ne peut annuler que ses propres entrées.

Le client createSdk du framework n'a pas de méthode pour le scheduler : comme indiqué dans SDK → Tasks, les entrées sont mises en place pour votre application par la plateforme. Cette page décrit ce qu'une entrée contient et ce que votre code doit faire quand elle se déclenche.

Opérations

Opération Rôle Réponse
Enregistrer Créer ou mettre à jour une entrée (par son name) { "ok": true }
Lister Lister les entrées de votre application, avec leur dernière exécution { "tasks": [...] }
Annuler Supprimer une entrée par son name { "cancelled": true }, ou false si aucune entrée de ce nom n'appartient à votre application

Enregistrer à nouveau un nom existant remplace tous les champs de l'entrée. C'est aussi la façon de la suspendre ou de la réactiver : enregistrez-la avec enabled: false, puis enabled: true. À la réactivation, les échéances manquées pendant la pause sont elles aussi rattrapées.

Définir une entrée

Champ Requis Notes
name oui Nom de l'entrée. Les noms sont uniques sur toute la plateforme : un nom déjà utilisé par une autre application est refusé avec 400
schedule (ou cron) oui L'expression cron, évaluée en UTC
task ou handler_url oui (l'un des deux) Une tâche déclarée avec defineTask, ou l'URL d'une route de votre application à appeler en POST. Si les deux sont fournis, c'est task qui est retenu
payload non Données transmises à la tâche à chaque exécution (entrées task uniquement)
timeout_secs non Durée maximale d'une exécution de tâche, en secondes (300 par défaut). Une valeur hors de l'intervalle 1 à 1800 est ramenée à la borne la plus proche
enabled non false pour enregistrer une entrée en pause (true par défaut)

Un name ou une expression cron manquants, ou une expression invalide, sont refusés avec 400. Les expressions standard à 5 champs sont acceptées, ainsi que les expressions à 6 champs avec les secondes en tête et les raccourcis @hourly, @daily (ou @midnight), @weekly, @monthly et @yearly (ou @annually). Dans le champ jour de la semaine, 0 et 7 désignent tous deux le dimanche. Une nouvelle entrée attend sa prochaine échéance : elle ne se déclenche pas à l'enregistrement.

Exemple d'entrée qui appelle une route chaque jour à 06:00 UTC :

{
  "name": "daily-report",
  "schedule": "0 6 * * *",
  "handler_url": "https://<app>.inklura.fr/api/cron/daily-report?key=<secret>"
}

Et une entrée qui lance une tâche chaque nuit à 03:00 UTC :

{
  "name": "nightly-report",
  "schedule": "0 3 * * *",
  "task": "generate-report",
  "payload": { "month": "current" }
}

La tâche doit être déclarée dans le worker de tâches de votre application (voir SDK → Tasks). Son handler reçoit payload en second argument, et le job est enregistré avec trigger: "cron".

Note

Une entrée handler_url suppose que les appels HTTP planifiés soient activés pour votre application, et l'URL doit commencer par l'une des adresses de rappel autorisées pour elle (sur son propre domaine). Elle ne peut contenir ni identifiants ni fragment (#) ; une chaîne de requête est acceptée. Sinon, l'enregistrement est refusé avec 403. Ces conditions sont vérifiées à nouveau avant chaque exécution.

Liste des entrées

Chaque élément de tasks contient notamment :

Champ Notes
name Nom de l'entrée
cron L'expression telle qu'enregistrée
kind http (entrée handler_url) ou task
handler_url L'URL appelée, ou null
timeout_secs Durée maximale retenue
enabled false si l'entrée est en pause
registered_at Date du premier enregistrement (horodatage Unix en secondes)
last_run Dernière échéance exécutée avec succès, ou null

L'appel que reçoit votre route

Avec handler_url, le scheduler envoie une requête POST avec un petit corps JSON :

{ "name": "daily-report", "app_id": "<votre application>", "scheduled_for": 1767225600 }

scheduled_for est l'heure d'envoi de la requête, en horodatage Unix (secondes). Ce n'est pas l'heure théorique de l'échéance : ne vous en servez pas pour reconnaître une échéance déjà traitée.

Votre route dispose de 60 secondes pour répondre. Une réponse 2xx marque l'exécution comme terminée. Toute autre réponse (une redirection comprise), ou l'absence de réponse, laisse cette échéance en attente : elle est retentée environ 30 secondes plus tard, sans limite de tentatives, et les échéances suivantes attendent qu'elle aboutisse. Une même entrée ne s'exécute jamais deux fois en parallèle, mais une échéance peut être livrée plus d'une fois : faites en sorte que la route supporte d'être exécutée deux fois.

Les échéances manquées, par exemple pendant une interruption de service, ne sont pas perdues : elles sont rattrapées une par une, dans l'ordre.

Sécuriser la route appelée

La route fait partie de votre application : c'est donc à elle de vérifier que l'appel est légitime. La convention la plus simple est un secret partagé dans la chaîne de requête : enregistrez l'URL avec ?key=<secret> et vérifiez ce key avant tout travail.

// src/app/api/cron/daily-report/route.ts
import { createSdk } from "@bext-stack/framework/sdk";

const sdk = createSdk("<app-id>");

export async function POST(req: Request) {
  const key = new URL(req.url).searchParams.get("key");
  if (!key || key !== (await sdk.secrets.get("CRON_SECRET"))) {
    return new Response("forbidden", { status: 403 });
  }
  // …exécuter la tâche…
  return new Response("ok");
}

Stockez la valeur avec les secrets de votre application plutôt que dans le code.

Attention

Le secret figure dans l'URL : gardez-le hors des journaux, changez-le s'il fuite, et utilisez toujours une URL en HTTPS sur le domaine de votre application.

Travail planifié de longue durée

Le scheduler sert à déclencher à l'heure, pas à exécuter longtemps : une route appelée doit répondre en moins de 60 secondes. Si le travail est lourd, planifiez directement une tâche (champ task), ou faites en sorte que votre route ajoute un message dans une queue et réponde tout de suite.

Automatisations de la plateforme

Les étapes temporelles des automatisations de la plateforme (délais des journeys, par exemple) sont planifiées par la plateforme elle-même. Vous n'avez rien à enregistrer pour elles.

Voir aussi