実行と結果
実行を開始
入力契約を満たすパラメータで Data App 実行を開始。結果待ち可。
POST
実行を開始
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs
認証:APIキー必須(Authorization: Bearer <API Key>)。
リクエストボディは App の入力契約(App 詳細の input_schema)の 1 つのインスタンス。検証は厳格。
wait はこの呼び出しで結果を待つかどうかを制御する:
- 省略時:App の
execution.modeの既定に従う。syncの App は終端状態まで待つ(上限は App のexecution.timeout_seconds)。asyncの App はすぐにrun_idを返す。 - 0〜60 を明示:どちらのモードも同じ動作になり、最大
wait秒待つ。wait=0は実行がキューに入った時点ですぐに返る。syncの App でも先にrun_idを受け取り、Get a run のwaitでロングポーリングできる。
sample_records に最初のバッチが含まれることがある。結果全体は Get run records でページングして取得する。
version は実行を過去の Release に固定する(契約と料金はそのバージョンに従う)。build は作者のデバッグ用で、変更不可の Build スナップショットに固定する(run_kind=test、公開統計からは除外されるが課金はされる)。version と build は同時に指定できない。
実行のゲートは詳細のゲートと同じ:見えない App は 404 を返す。見えていても実行を受け付けていない App は 403 を返す(作者のセルフテストは制限されない)。yank されたバージョンに固定した新しい実行は拒否される(422)。
リクエスト
パスパラメータ
string
必須
App 参照:
app_<hex> または <namespace>/<app_name>。クエリパラメータ
number
終端状態まで待つ最大秒数。省略すると App のモードの既定値を使う。
0 は開始直後にすぐ返る。範囲 0〜60。integer
生成するレコードの最大数。上限に達すると実行は正常に終了する。コストと所要時間の制御に使う。範囲は 1 以上。
string
デフォルト:"api"
チャネルの目印。既定は
api。SDK と MCP はそれぞれ独自の値を設定する。実行一覧と請求のフィルターとして使える。string
特定のバージョンに固定する。既定は最新バージョン。
string
作者のデバッグ専用。Build スナップショットに固定する。
version とは同時に指定できない。リクエスト body
App のinput_schema に沿った JSON オブジェクト。最も確実なのは、App 詳細の examples から 1 件をコピーして編集すること。
リクエスト例
レスポンス
200 成功
data に包まれます。フィールド:
string
必須
実行 ID。状態の確認、レコードの取得、キャンセルに使う。
string
発行者ユーザー名。
string
App 名。
string
固定されたバージョン。デバッグ実行では
null。string
デバッグ実行が固定した Build スナップショット。本番実行では
null。string
通常は
production。作者デバッグは test。enum
必須
実行の状態。値:
PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED。object
入力のエコー。入力契約で
sensitive とマークされたフィールドはマスクされる。object
進捗。
done / total は App が報告し、status_text は App が返す人が読める状態文字列。string
結果データセットの ID。
boolean
実行が部分的に成功した、またはキャンセルされた場合に
true。生成済みのレコードは引き続き利用できる。boolean
取消要求済みで収束中なら
true(協調停止/部分結果回収)。終端では常に false(サーバ正規化)。state から導出不要。string
開始チャネル。
string
上流タスクの ID(存在する場合)。
string
開始時刻。期間フィルターと請求の帰属の基準にもなる。
string
直近の実行開始時刻。再試行のたびに更新される。
string
ワーカーが初めて実行を引き受けた時刻。
started_at と違いリトライで上書きされないため壁時計の基準: queued = first_started_at - created_at、総壁時間 = finished_at - first_started_at。started_at から queued を取ると以前の試行を待ちと誤算。未割当のみ null。string
終了時刻。
object
客観使用量: 実行が何をしたか。課金と分離。評価比較の基準。
object
請求台帳 = 使用量 × 料金 × 請求ルール。
events[] は課金対象の各イベントを数量・単価・金額とともに列挙し、total はその合計、charged は課金が適用されたかどうか。終端状態に達して初めて確定する。object
失敗時のエラーオブジェクト(
code / category / message / retryable)。object[]
レスポンスの時点で既に終端状態の場合は最初のバッチのレコード。それ以外は
null。object[]
構造化された警告(例:
billing-qty-missing)。エラー
エラー応答は
{"error": {code, category, message, retryable}} です。エラー を参照。
クライアントライブラリ
注意事項
- 状態の語彙:
PENDING、QUEUED、RUNNING、SUCCEEDED、PARTIALLY_SUCCEEDED、FAILED、CANCELLED、EXPIRED。最後の 5 つが終端状態。 - 待機がタイムアウトしたからといって、同じ目的の 2 回目の実行を開始しないこと。まず既存の
run_idをポーリングする。 - 失敗した実行は課金されない。部分成功とキャンセルは、生成されたレコード分のみ課金される。