Skip to main content
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 をポーリングする。
  • 失敗した実行は課金されない。部分成功とキャンセルは、生成されたレコード分のみ課金される。