冪等性キー

Audience

このAPIは、Roktネットワーク上で構築する統合パートナー向けです。自社のチェックアウトに配置を統合するRoktのeコマースパートナーは、代わりにRokt Ecommerce開発者ドキュメントを使用してください。

Partnerships APIへのすべての書き込み呼び出しには、Idempotency-Keyヘッダーが必要です。サーバーは(parent_account_id, account_id, idempotency_key)をUNIQUE制約として保存し、キャッシュウィンドウの存続期間中に最初の呼び出しのキャッシュされた応答を返します。論理操作ごとに新しいUUIDを使用し、同じキーを再送信してリトライします。

契約

• ヘッダーはすべての書き込みで必須です。 これが欠落していると400が返されます。
• フォーマットはUUIDです。 任意のRFC 4122バリアントを使用できます。UUIDv4で問題ありません。高エントロピーのものを選び、異なる論理書き込みにキーを再利用しないでください。
• スコープは管理されたアカウントごとです。 異なるaccount_idで同じキーを使用しても衝突しません。
• TTLは約24時間です。 冪等性キャッシュ保持ウィンドウと一致します。期限切れ後、同じキーは新しいリクエストとして扱われます。

Key hygiene

Idempotency-Keyをサーバーサイドの重複排除トークンとして扱い、データとして扱わないでください：

• 論理書き込みごとに1つのキー。同じ論理書き込みの新しいリトライは同じキーを再利用しますが、新しいマーチャント操作には新しいキーを取得します。
• キーにPII（メール、名前、注文ID）を埋め込まないでください。キーはサーバーログや監査トレイルに表示されます。
• キーは秘密ではありませんが、認証でもありません：キーの所持は書き込みアクセスを許可しません。トークン + account_idは呼び出しをゲートします。
• 異なるエンドポイントや異なるaccount_idでキーを再利用しないでください。スコープガードによって安全ですが、スコープを混在させるとリトライログのデバッグが難しくなります。

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
  -H "Authorization: Bearer $ROKT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @mcl.json

同じキー、異なるボディ

異なるボディでキーを再利用すると、サーバーは最初の呼び出しの応答を返します。新しいボディで再処理は行いません。これは設計上の意図です：Idempotency-Keyはリトライをまとめ、編集のバージョン管理を行いません。

警告

ペイロードを変更し、同じキーで再送信すると、黙って無視されます。新しい書き込みを有効にしたい場合は、新しいキーを使用してください。

結果テーブル

シナリオ	HTTP	返されるもの
最初の呼び出し	200 / 201	新しい応答
リトライ、元の完了済み	200 / 201	キャッシュされた応答（バイト同一のボディ）
リトライ、元の一時的な失敗	元の失敗と一致	キャッシュされた失敗；サーバーは内部で最大3回リトライ
リトライ、元の4xxで失敗	元の失敗と一致	キャッシュされた失敗；内部リトライなし（クライアントはペイロードを修正し、新しいキーを使用する必要があります）
同じキー、同じボディ、24時間TTL後	200 / 201	新しいリクエストとして扱われ、新しい書き込みが実行されます。元の応答はもはやキャッシュされていません。
Idempotency-Keyヘッダーが欠落	400	以下のエラーエンベロープ
同じキーが進行中、異なるボディ	409	IdempotencyConflictエラーエンベロープ

キーが欠落している場合のエラーエンベロープ：

{
  "error": "Idempotency-Key header is required",
  "request_id": "req_01HX9F2J7M3K8N5VYBQZP4R6T2"
}

ウォークスルー：同じキーでのリトライ

これは推奨されるリトライパターンです。キーを一度生成し、ローカルに保存し、すべてのリトライで送信します。

1. 1
   Generate and persist the key

   IDEM_KEY=$(uuidgen)
   echo "$IDEM_KEY" > /tmp/last-mcl-key

2. 2
   First call: server processes, returns 200

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "Idempotency-Key: $IDEM_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"Acme Network Controls","blockedVerticals":[{"partnerVerticalId":1500,"partnerSubVerticalId":1610,"policy":"Block"}]}'

   応答：新しいmarketplace_controls_list_idとcontent_hashを含む200。

3. 3
   Network blip: your client never sees the response

   HTTPクライアントがタイムアウトをスローします。サーバーが書き込みを処理したかどうかはわかりません。

4. 4
   Replay with the same key

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "Idempotency-Key: $(cat /tmp/last-mcl-key)" \
     -H "Content-Type: application/json" \
     -d '{"name":"Acme Network Controls","blockedVerticals":[{"partnerVerticalId":1500,"partnerSubVerticalId":1610,"policy":"Block"}]}'

   応答：ステップ2と同じmarketplace_controls_list_idとcontent_hashを含む200。安全：重複書き込みは発生していません。

ネットワークがレスポンスを失った場合、操作のポーリングを優先する

冪等性キー (Idempotency-Key) のリプレイは機能しますが、リクエストボディを毎回検証に通します。元のレスポンスヘッダーから X-Operation-Id を取得した場合（またはクライアントがタイムアウトする前にログを記録した場合）、操作のポーリング によってボディを再検証することなくレスポンスを直接回復できます。

関連

Operation Polling

タイムアウトからの回復には X-Operation-Id を使用します。

Dry-Run Mode

ドライランでも冪等性キーを消費します。