Skip to main content
POST
Démarrer une exécution
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs Authentification : clé API requise (Authorization: Bearer <API Key>). Le corps de la requête est une instance du contrat d’entrée de l’app (input_schema du détail). La validation est stricte. wait contrôle si cet appel attend un résultat :
  • Omise : suit le défaut de execution.mode de l’app. Les apps sync attendent un état terminal (plafonné par execution.timeout_seconds de l’app) ; les apps async renvoient un run_id immédiatement.
  • Explicite 0–60 : les deux modes se comportent de la même façon et attendent au plus wait secondes. wait=0 renvoie dès que l’exécution est en file. Pour une app sync, vous pouvez prendre d’abord le run_id, puis faire un long-poll avec Obtenir une exécution wait.
Quand la réponse atteint déjà un état terminal, sample_records peut inclure le premier lot. Paginer le résultat complet avec Obtenir les enregistrements d’exécution. version épingle l’exécution à une release historique (contrat et tarifs suivent cette version). build sert au debug de l’auteur : il épingle un snapshot de build immuable (run_kind=test, exclu des stats publiques, toujours facturé). version et build sont mutuellement exclusifs. La porte d’exécution correspond à la porte de détail : les apps invisibles renvoient 404 ; les apps visibles qui n’acceptent pas d’exécutions renvoient 403 (les auto-tests de l’auteur sont sans restriction) ; les nouvelles exécutions épinglées à une version yankée sont rejetées (422).

Requête

Paramètres de chemin

string
requis
Référence d’app : app_<hex> ou <namespace>/<app_name>.

Paramètres de requête

number
Secondes maximales d’attente d’un état terminal. Omettez pour utiliser le défaut du mode de l’app ; 0 renvoie immédiatement après le démarrage.Plage 0 à 60.
integer
Nombre maximal d’enregistrements à produire. L’exécution se termine normalement quand le plafond est atteint. Utilisez-le pour contrôler coût et durée.Plage ≥ 1.
string
défaut:"api"
Marqueur de canal. Défaut api ; les SDK et MCP définissent leurs propres valeurs. Utilisable comme filtre sur la liste d’exécutions et la facturation.
string
Épingler à une version précise. Par défaut la dernière version.
string
Debug auteur uniquement. Épingler à un snapshot de build. Mutuellement exclusif avec version.

Corps de la requête

Objet JSON façonné par input_schema de l’app. Le démarrage le plus sûr est de copier une entrée de examples dans le détail de l’app et de l’éditer.

Exemple de requête

Réponse

200 succès

La charge utile est encapsulée dans data. Champs :
string
requis
Id de l’exécution. Utilisez-le pour le statut, les enregistrements et l’annulation.
string
Nom d’utilisateur de l’éditeur.
string
Nom de l’app.
string
Version épinglée. null pour les exécutions de debug.
string
Snapshot de build épinglé par une exécution de debug. null pour les exécutions de production.
string
production pour les exécutions normales ; test pour le debug de l’auteur.
enum
requis
État de l’exécution. Valeurs : PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.
object
Écho de l’entrée. Les champs marqués sensitive dans le contrat d’entrée sont expurgés.
object
Progression. done / total sont rapportés par l’app ; status_text est une chaîne d’état lisible de l’app.
string
Result dataset id.
boolean
true quand l’exécution a partiellement réussi ou a été annulée. Les enregistrements produits restent utilisables.
boolean
true tant que l’annulation a été demandée et que l’exécution se termine encore (arrêt coopératif / récupération de résultat partiel). Toujours false en états terminaux (normalisé côté serveur), donc les clients n’ont pas à le dériver de state.
string
Start channel.
string
Id de la tâche upstream, le cas échéant.
string
Heure de début. Aussi l’ancre des filtres de plage temporelle et de l’attribution de facturation.
string
Most recent execution start time. Re-stamped on retry.
string
Quand un worker a réclamé l’exécution pour la première fois. Contrairement à started_at, ce n’est jamais réécrit en cas de réessai, donc c’est l’ancre du temps en file : en file = first_started_at - created_at, et temps total mur = finished_at - first_started_at. Dériver le temps en file de started_at compte les tentatives antérieures comme file. null seulement pour les exécutions jamais réclamées.
string
End time.
object
Mesure objective d’usage : ce que l’exécution a fait. Séparée de la facturation ; c’est ce que comparent les évaluations.
object
Grand livre de facturation = usage × tarifs × règles de facturation. events[] liste chaque événement facturable avec quantité, prix unitaire et montant ; total est la somme ; charged indique si le débit a été appliqué. Complet seulement après un état terminal.
object
Objet d’erreur en cas d’échec (code / category / message / retryable).
object[]
Premier lot d’enregistrements quand la réponse est déjà terminale ; sinon null.
object[]
Avertissements structurés, par exemple billing-qty-missing.

Erreurs

Les réponses d’erreur utilisent {"error": {code, category, message, retryable}}. Voir Erreurs.

Bibliothèques clientes

Notes

  • Vocabulaire d’état : PENDING, QUEUED, RUNNING, SUCCEEDED, PARTIALLY_SUCCEEDED, FAILED, CANCELLED, EXPIRED. Les cinq derniers sont terminaux.
  • Ne démarrez pas une deuxième exécution pour le même objectif seulement parce qu’un wait a expiré. Sondez d’abord le run_id existant.
  • Les exécutions en échec ne sont pas facturées. Le succès partiel et l’annulation ne facturent que les enregistrements produits.