Core concepts
ポーリング
受付時の status_url を、ジョブが終端状態になるまで取得します。
推奨する待機方法
- 最初は 2 秒を目安に待ち、応答の
next_poll_after_secondsがあればその値を優先します。 - 間隔の指定がない場合は、待機を徐々に延ばして最大 10 秒にします。
- 複数のワーカーでは、ランダムな待ち時間を加えます。
terminalが true になったら終了します。result_readyが true の場合だけ結果を取得します。- モデルに応じたアプリケーション側の待機期限を設けます。
Python 3 の標準ライブラリだけを使った例です。STATUS_URL には受付時の URL を設定します。
import json
import os
import random
import time
from urllib.request import Request, urlopen
status_url = os.environ["STATUS_URL"]
headers = {"Authorization": f"Bearer {os.environ['ORCHESTOR_API_KEY']}"}
deadline = time.monotonic() + 600
interval = 2.0
while True:
remaining = deadline - time.monotonic()
if remaining <= 0:
raise TimeoutError("待機期限を超えました。元のジョブ ID で確認を再開してください。")
request = Request(status_url, headers=headers)
with urlopen(request, timeout=min(30, remaining)) as response:
state = json.load(response)["data"]
if state["terminal"]:
break
delay = state.get("next_poll_after_seconds")
if delay is None:
delay = interval
time.sleep(min(max(0, deadline - time.monotonic()), delay + random.uniform(0, 0.5)))
interval = min(interval * 1.5, 10.0)
print(state)この例では HTTP エラーと通信障害を呼び出し元に返します。以下の条件で待機と再試行を追加してください。待機の終了はジョブの取消ではありません。
再試行の判断
| 応答 | 次の処理 |
|---|---|
200、未完了 | next_poll_after_seconds に従い、状態を再取得します。 |
200、終端 | 待機を終了し、成功時は result_url を取得します。 |
401 | 停止し、認証情報を修正します。 |
404 | 停止し、ジョブ ID とキーの所属先を確認します。 |
429 | retry-after 秒待ちます。 |
再試行可能な 5xx・通信障害 | 待機期限内で指数バックオフとランダムな遅延を使って状態取得を再試行します。 |
長時間の処理では Webhookを使い、通知を取り逃した場合の確認手段としてポーリングを残します。