メインコンテンツへスキップ
すべてのリクエストはタスクとして保存されます。送信するとすぐにタスクidが返り、結果は後からWebhookまたはポーリングで受け取ります。同じリクエストで結果を受け取るには、POST /v1/sync/taskに送信します。
送信のレスポンスは 200 で、タスクは QUEUED です。
idを使ってポーリングします(リファレンス)。

ライフサイクル

ステータス

一時的な失敗に遭遇したタスクは QUEUED に戻り、再実行されます。再試行を使い切って初めて FAILED に確定するため、PROCESSING → QUEUED の遷移は正常です。 タスクが終了状態になるまで、ポーリングは response を省略します。失敗したタスクには代わりにトップレベルの error 文字列が付きます。

送信時とポーリング時のクレジット

料金、確保、上限はクレジットと上限に記載しています。

処理時間

task.latencyMs はエンジンが要した時間です。ワーカーが最初にタスクを取得した時点から最終結果までをミリ秒で測り、待ち時間は含みません。一時的な失敗で再びキューに戻っても、最初の取得時刻から数えます。送信レスポンスと QUEUED・PROCESSING では null で、終了したタスクのポーリングと webhook では数値です。レスポンスヘッダーの X-Latency-Ms は、このサーバーがその HTTP リクエスト1件に費やした時間で、別の値です。

優先度

priority は 1 から 10 を受け付け、既定値は 1 です。範囲外の値は拒否せず範囲内に丸めます。値はタスクのメタデータにそのまま返されます。
実行順序は優先度、送信時刻、アカウントのいずれによっても保証されません。依存する処理は、前のタスクが完了してから次を送信してください。

保持期間

終了したタスクは完了後24時間ポーリングできます。それ以降、GET /v1/async/task/{id} は 404 RESOURCE_NOT_FOUND を返します。これは不明なidや他のアカウントのタスクと同じレスポンスです。QUEUED と PROCESSING のタスクは、どれだけ古くても参照できます。 24時間の期間は、GET /v1/batches/{id}/items とグリッドの読み取りで返る結果本文にも適用されます。タスクの idempotencyKey はそれより長く、リクエストから少なくとも30日間予約されたままです(冪等性を参照)。Webhookの自動再試行は、この期間とは関係なく独自のスケジュールで実行されます。

1回のリクエストで結果を待つ

POST /v1/sync/taskは同じ本文を受け取り、タスクが終わるまで最大290秒リクエストを保持します。終わると、タスクをポーリングしたときと同じ本文で200を返します。失敗したタスクも同じです。 回答エンジンはSERPやSearchのタスクより時間がかかります。エンジン一覧の分類に合わせてリクエストを保持する時間を決め、HTTPクライアントのタイムアウトはそれより数秒長くしてください。
  • 待機時間が終わってもタスクが終わっていない場合は、202、タスク、Location: /v1/async/task/{id}を返します。タスクは実行を続け、通常どおり課金されます。そのアドレスをポーリングするか、Webhookで受け取ってください。サービスが多くのリクエストを保持しているときは、すぐに202が返ることもあります。
  • Prefer: wait=<秒>を送ると、290秒より短く保持します。HTTPクライアントのタイムアウトより短くすると、クライアントが切断する前にタスクidを受け取れます。
  • idempotencyKeyを送ってください。同じキーをもう一度送ると、そのキーを持つタスクで応答します。手元でタイムアウトしたリクエストを、タスクを二重に実行せずに再送できます。
  • Accept: text/htmlとpayload.include.html: trueを送ると、完了したタスクの保存ページをtext/htmlで返し、X-Task-Idにタスクidを入れます。失敗したタスクや、ページを保存できなかったタスクには、406とJSON本文を返します。

Webhookとポーリングの選択

Webhookを推奨します。受け取れなかった結果の回収にはポーリングを使ってください。 堅牢なクライアントは両方を使います。Webhookを速い経路として受け取り、通知を受け取れなかったタスクは24時間の期間内に余裕をもってポーリングしてください。

次のステップ

Webhook

ペイロード、署名、再試行。

バッチとグリッド

最大10,000件のタスクを一度に送信します。