Runs & Results
Avvia un’esecuzione
Avvia un’esecuzione Data App con input conformi al contratto di input. Opzionalmente attendi il risultato.
POST
Avvia un’esecuzione
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs
Autenticazione: API key obbligatoria (Authorization: Bearer <API Key>).
Il body della richiesta è un’istanza del contratto di input dell’app (input_schema dal dettaglio app). La validazione è strict.
wait controlla se questa chiamata attende un risultato:
- Omesso: segui il default
execution.modedell’app. Le appsyncattendono uno stato terminale (limitato daexecution.timeout_seconds); le appasyncrestituiscono subito unrun_id. - Esplicito 0–60: entrambi i modi si comportano uguale e attendono al massimo
waitsecondi.wait=0ritorna appena la run è in coda. Per un’appsyncpuoi prendere prima ilrun_ide poi fare long-poll con Ottieni un’esecuzionewait.
sample_records può includere il primo batch. Scorri il risultato completo con Ottieni record dell’esecuzione.
version pinna la run a un release storico (contratto e pricing seguono quella versione). build è per debug dell’autore: pinna uno snapshot di build immutabile (run_kind=test, escluso dalle stats pubbliche, comunque fatturato). version e build sono mutuamente esclusivi.
Il gate della run coincide col gate di dettaglio: app invisibili restituiscono 404; app visibili che non accettano run restituiscono 403 (i self-test dell’autore non hanno restrizioni); nuove run pinnate a una versione yanked sono rifiutate (422).
Richiesta
Parametri di percorso
string
obbligatorio
Riferimento app:
app_<hex> oppure <namespace>/<app_name>.Parametri di query
number
Secondi massimi di attesa di uno stato terminale. Ometti per il default della mode app;
0 ritorna subito dopo lo start.Intervallo da 0 a 60.integer
Numero massimo di record da produrre. La run termina normalmente al raggiungimento del cap. Usalo per controllare costo e durata.Intervallo ≥ 1.
string
predefinito:"api"
Marker di canale. Default
api; SDK e MCP impostano i propri valori. Usabile come filtro su lista run e fatturazione.string
Pinna a una versione specifica. Default: ultima versione.
string
Solo debug autore. Pinna a uno snapshot di build. Mutuamente esclusivo con
version.Body della richiesta
Oggetto JSON conforme ainput_schema dell’app. Partenza più sicura: copia una entry da examples nel dettaglio app e modificala.
Esempio di richiesta
Risposta
200 successo
data. Campi:
string
obbligatorio
ID esecuzione. Usalo per stato, record e cancel.
string
Username del publisher.
string
Nome dell’app.
string
Versione pinnata.
null per run di debug.string
Snapshot di build pinnato da una run di debug.
null per run production.string
production per run normali; test per run di debug dell’autore.enum
obbligatorio
Stato run. Valori:
PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.object
Echo dell’input. I campi marcati
sensitive nel contratto di input sono redatti.object
Progresso.
done / total sono riportati dall’app; status_text è una stringa di stato leggibile dall’app.string
ID dataset risultato.
boolean
true quando la run è parzialmente riuscita o è stata annullata. I record prodotti restano usabili.boolean
true mentre l’annullamento è stato richiesto e il run è ancora in fase di chiusura (arresto cooperativo / recupero dei risultati parziali). Sempre false negli stati terminali (normalizzato lato server), quindi i client non devono ricavarlo da state.string
Canale di avvio.
string
ID task upstream, se presente.
string
Ora di start. Anche ancora per filtri temporali e attribution di fatturazione.
string
Ora di start dell’esecuzione più recente. Re-stampata al retry.
string
Quando un worker ha claimato la run la prima volta. A differenza di
started_at non viene mai riscritto al retry: ancora per il tempo in coda: queued = first_started_at - created_at, wall time totale = finished_at - first_started_at. Derivare il tempo in coda da started_at conta i tentativi precedenti come queueing. null solo per run mai claimate.string
Ora di fine.
object
Metering usage oggettivo: quanto ha fatto la run. Separato dalla fatturazione; è ciò che le evaluation confrontano.
object
Ledger di fatturazione = usage × pricing × regole di billing.
events[] elenca ogni evento billable con quantità, prezzo unitario e importo; total è la somma; charged indica se l’addebito è stato applicato. Completo solo dopo uno stato terminale.object
Oggetto errore in caso di failure (
code / category / message / retryable).object[]
Primo batch di record quando la risposta è già terminale; altrimenti
null.object[]
Warning strutturati, ad esempio
billing-qty-missing.Errori
Le risposte di errore usano
{"error": {code, category, message, retryable}}. Vedi Errori.
Librerie client
Note
- Vocabolario stati:
PENDING,QUEUED,RUNNING,SUCCEEDED,PARTIALLY_SUCCEEDED,FAILED,CANCELLED,EXPIRED. Gli ultimi cinque sono terminali. - Non avviare una seconda run per lo stesso obiettivo solo perché un wait è andato in timeout. Fai prima poll del
run_idesistente. - Le run fallite non sono fatturate. Successo parziale e cancel fatturano solo i record prodotti.