非同期タスクモデル

ドキュメントをアップロードしても処理は開始されず、処理を開始しても同じリクエスト内で完了するとは限りません。すべてのドキュメントとバッチは、固定された閉じたステータスのセットを遷移します。このページでは、そのライフサイクルを最初から最後まで解説します。

ステータスライフサイクル

すべてのドキュメント（および集約されたすべてのバッチ）は、常に次の5つの状態のいずれかにあります。

queued → processing → succeeded | failed | canceled

• queued — アップロード済み、またはワーカーが取得するのを待機中。
• processing — ワーカーがドキュメントを取得し、データ抽出を実行中。
• succeeded — 抽出が完了。結果レスポンスのline_itemsが設定されます。
• failed — このドキュメントの抽出を完了できませんでした（これはドキュメントレベルの結果であり、API呼び出しエラーではありません。エラーハンドリングのprocessing_errorに関する注意事項を参照してください）。
• canceled — 処理開始前にドキュメントがキューから削除されました（例：ドキュメントがqueuedの状態でバッチが削除された場合）。

この5つの値のセットは公開契約であり、システムが内部で使用する状態から意図的に切り離されています。新しい内部中間状態が後で導入されても、ここに6番目の値が追加されることはありません。今日解析するすべてのv1レスポンスは引き続き動作します。

タイムスタンプチェーン

ドキュメント（GET /documents/{id}）とバッチ（GET /batches/{batch_name}/results）の両方のレスポンスには、同じ3つのフィールドが含まれています。これにより、「キューに入ったまま停止している」状態と「アクティブに実行中」の状態と「本当に完了した」状態を区別できます。

ポーリング vs ウェブフック

バッチの完了を確認する方法は2つあります。

• ポーリング — GET /batches/{batch_name} を定期的に呼び出し、all_done を確認します。シンプルで、サーバー側に特別なインフラは不要ですが、ポーリング間隔が短すぎるとリクエストを無駄に消費し（ステータスエンドポイントの上限は120回/分です。レート制限を参照）、長すぎると完了に気づくまでに遅延が生じます。
• ウェブフック — PUT /batches/{batch_name}/webhook でコールバックURLを一度登録するだけで、繰り返し問い合わせる代わりに、バッチが完了した瞬間に通知を受け取れます。詳細はウェブフックガイドをご覧ください。このガイドでは、一度通知を受け取った後にバッチにさらにドキュメントを追加して再処理した場合の動作についても説明しています（簡単に言うと、追加の登録なしで自動的に再通知されます）。

1回だけ処理する小さなバッチであれば、数回のポーリングが最も簡単です。より大量の処理や、リクエストループを待機させたくない場合は、ウェブフックの方が適しています。