Skip to main content
idempotencyKey は呼び出し側が任意で指定する文字列で、送信を重複排除の対象にします。同じキーで2回送信すると、 2回目は新しい作業をキューに入れず、1回目が作成したタスクに解決されます。
省略すると重複排除は行われず、送信のたびに新しいタスクが作られます。単発の問い合わせなら妥当な選択ですが、 cronや再試行するワーカーが2回送信しうるものには向きません。
よいキーは試行ではなく作業そのものから決定的に作られます。作業単位を定める識別子を "{jobId}:{promptId}:{engine}" のように組み合わせると、再試行でも自然に同じキーが再現されます。

​
単発とバッチは意図的に異なります

2つのエンドポイントが異なる唯一の箇所で、つまずきやすいポイントです。
単発エンドポイントは明示的な作成のセマンティクスを保ちます。タスクの作成を求めたのに既に存在するなら、 それは競合であり、呼び出し側が知るべきことです。 バッチエンドポイントは重複を成功として吸収します。呼び出し側は通常、再起動後にジョブ全体を再送信する ワーカーであり、キー1つが既にキューにあるからといって500件のバッチを失敗にしては冪等キーの意味がありません。 返ってくる results[i].task は既存のタスクなので、タスクの対応付けはそのまま解決されます。

​
結果と送信を対応付ける

独立した2つのハンドルがあり、両方が必要です。
​
integer
入力配列と位置で1:1に対応します。バッチのレスポンスを送信したタスクと突き合わせるのに使います。
​
string
送信した値がそのまま返ります。数分後に順不同で届き、元の配列を参照しないWebhookを突き合わせるのに使います。
idempotencyKey を指定しなかった場合、このフィールドは null として返されず、タスクオブジェクトから 省略されます。内部ではタスク自身のuuidをキーとして使い、これは構造上一意なので重複排除は起きません。

​
キーの有効期間

永久保持されるタスクのキーは、完了、失敗、24時間の公開ポーリング期間を過ぎても予約されたままです。 ポーリングが404を返してもキーは解放されません。1回の送信の通信再試行には同じキーを使い、別の実行には 新しい実行キー(例: :r1 サフィックスを追加)を使ってください。UUID形式である必要はありません。永久保持が 有効になる前にレガシー履歴へ移されたレコードは、遡ってキーを予約しません。