EN
Copied
Concepts

Jobs & cycle de vie

Un job est une unité de travail. Cette page décrit ses états, transitions, événements et la sémantique de reprise.

Un job est une unité de travail. Chaque module s'exécute sous forme de job. Les jobs sont isolés, observables, reprenables.

Machine à états

   ┌─────────┐   pris par file   ┌─────────┐    succès     ┌──────┐
   │ pending │ ────────────────► │ running │ ────────────► │ done │
   └─────────┘                   └─────────┘               └──────┘
        │                             │
        │       annulation            │    erreur fatale
        ▼                             ▼
   ┌───────────┐                 ┌────────┐
   │ cancelled │                 │ failed │
   └───────────┘                 └────────┘

   done / failed / cancelled  ──── (après 7 jours) ────►  expired
État Signification
pending Créé, en attente dans la file FIFO
running Pris par un worker, en cours d'exécution
done Terminé avec succès, résultats téléchargeables
failed Échec (voir error_message)
cancelled Annulé via l'UI ou l'API
expired Plus de 7 jours depuis l'état terminal : fichiers de résultats purgés

Transitions et assignation à la file sont atomiques ; un job n'est jamais pris deux fois.

Création

POST /api/jobs             { "queries": [...], "zones": [...] }   # crée un job scrap
POST /api/jobs/{type}      { ...paramètres module }               # raccourci typé

Voir API Jobs.

Observabilité

GET /api/jobs/{id}            # statut, compteurs, métadonnées
GET /api/jobs/{id}/stream     # SSE : status / log / done

Le flux se ferme à la fin du job. Timeout de sécurité : 6 heures. Payloads des événements : voir États & événements SSE.

Résultats

GET /api/jobs/{id}/download?format=csv|json|xlsx
GET /api/jobs/{id}/items?offset=0&limit=200

Les résultats restent 7 jours après l'état terminal, puis sont purgés. L'enregistrement du job demeure.

Erreurs & reprises

Un job failed expose error_message et error_count (items en erreur dans le job : un job peut être done avec error_count > 0).

POST /api/jobs/{id}/resume

Crée une nouvelle tentative qui repart du dernier item réussi.

Une seule reprise d'un même job peut être pending ou running à la fois : un second appel renvoie 400 tant que la première n'a pas atteint un état terminal.

Durée maximale d'exécution

Un job s'exécute pendant 24 heures au plus. Une fois la limite atteinte, le job s'arrête proprement et passe en failed, avec un error_message indiquant que la durée maximale est atteinte. Les résultats déjà obtenus sont conservés et téléchargeables.

Pour les jobs reprenables, un job de suite est remis en file automatiquement : mêmes réglages, source_job_id pointant vers le job arrêté, départ là où il s'est arrêté et débit limité au reliquat. Aucun appel à /resume n'est nécessaire. Un job long apparaît donc comme une chaîne de jobs de 24 heures au plus chacun, le dernier portant le fichier de résultats complet.

Si le job n'a pas progressé pendant son exécution, ou si le compte a déjà 5 jobs en attente ou en cours, aucune suite n'est remise en file : l'error_message le précise et le job peut être repris par POST /api/jobs/{id}/resume.

Annulation

POST /api/jobs/{id}/cancel    # conserve les résultats partiels
DELETE /api/jobs/{id}         # annule et supprime l'enregistrement

Concurrence

La suite