Work のポーリング

GET /api/v1/cloud/environments/{environment_id}/work/poll self_hosted Environment から利用可能な work item を 1 件取得します。利用可能な work がない状態でポーリングすると、JSON の null を Body とした HTTP 200 OK が返されます。ポーリングは work item を配信しますが、確認応答は行いません。worker は Session work を実行する前に Work item の確認応答を呼び出す必要があります。

パスパラメータ

パラメータ	型	説明
`environment_id`	string	`env_` プレフィックス付きの Environment ID

リクエストヘッダー

ヘッダー	必須	説明
`Authorization`	はい	`Bearer $QODER_PAT`
`Worker-ID`	いいえ	安定した worker 識別子。キュー統計と ack の identity チェックに推奨

クエリパラメータ

パラメータ	型	必須	デフォルト	説明
`block_ms`	integer	いいえ	-	ロングポーリングの待機時間（ミリ秒）。1 から 999 の範囲でなければならない。非ブロッキングポーリングの場合は省略
`reclaim_older_than_ms`	integer	いいえ	5000	配信済みだが少なくともこのミリ秒数の間確認応答されていないキュー内アイテムを再配信する。0 以上でなければならない

リクエスト例

curl -X GET "https://api.qoder.com/api/v1/cloud/environments/env_019e64e01a137caf953ac2ac7b42ec5c/work/poll?block_ms=999" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Worker-ID: byoc-worker-01"

レスポンス例: work あり

HTTP 200 OK

{
  "id": "work_019f3be4fd2475d9a784bf2c739e1194",
  "type": "work",
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "data": {
    "type": "session",
    "id": "sess_019f3be3fa66750bb9a1fbcde85b5fe1"
  },
  "state": "queued",
  "created_at": "2026-07-01T08:15:01Z",
  "acknowledged_at": null,
  "started_at": null,
  "latest_heartbeat_at": null,
  "stop_requested_at": null,
  "stopped_at": null,
  "metadata": {}
}

レスポンス例: work なし

HTTP 200 OK

null

レスポンスフィールド

Work item オブジェクトを返します。利用可能なアイテムがない場合は null を返します。

エラー

HTTP	type	トリガー
400	`invalid_request_error`	`block_ms` が 1 から 999 の整数でない
400	`invalid_request_error`	`reclaim_older_than_ms` が 0 以上の整数でない
400	`invalid_request_error`	Environment が `self_hosted` でない
401	`authentication_error`	PAT が無効または期限切れ
403	`permission_error`	この操作の権限がない
404	`not_found_error`	Environment が存在しない

完全なエラーエンベロープについてはエラーリファレンスを参照してください。

備考

Worker-ID は worker が選択するビジネス識別子であり、認証クレデンシャルではありません。
poll と ack の両方が Worker-ID を指定し、値が一致しない場合、ack は 409 で失敗します。
ロングポーリングは最大でも block_ms の間 1 回だけ待機します。クライアントは null を受け取ったらポーリングを繰り返す必要があります。

クラウド環境

Agent が実行されるコンテナ、ネットワーク、依存関係を選択する。

​パスパラメータ

​リクエストヘッダー

​クエリパラメータ

​リクエスト例

​レスポンス例: work あり

​レスポンス例: work なし

​レスポンスフィールド

​エラー

​備考

​関連