Dry-Run Mode

Audience

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

ほとんどの書き込みエンドポイントは?dry_run=trueを受け入れます。例外については、サポートされているエンドポイントの表を参照してください。Roktは完全なリクエスト（認証、ペイロードの形状、垂直マッピング、関係のチェック）を検証し、実際のコミットと同一のレスポンスを返しますが、状態は保持されません。レスポンスボディは実際の呼び出しと同一ですが、副作用はありません。

使用するタイミング

• コミット前にペイロードの形状を検証する。 状態に触れることなく、400、欠落している垂直マッピング、または関係403を表面化します。
• ステージに対する統合テスト。 サンドボックスアカウントデータを汚染することなく、ビルドがエンドツーエンドで機能することを確認します。
• オンボーディングUIでの事前チェック。 マーチャントに「保存」をクリックする前に、正確に何が起こるかを示します。

ドライランが行わないこと

ドライランは許可のバイパスでも高速パスでもありません。それは、状態を保持せずに返される完全な実際のリクエストです。

• 認証は依然として実行されます。 間違ったAPIトークンや取り消された関係は、実際の呼び出しと同様に401 / 403を返します。
• 垂直翻訳は依然として実行されます。 欠落している垂直マッピング行は、実際の呼び出しと同様に400を返します。
• 冪等性キーは依然として適用されます。 ドライランは冪等性キャッシュに記録され、あなたのIdempotency-Keyによってキー付けされます。

ドライランが抑制すること

ドライランは、永続的な状態の変更およびそれから広がるであろう副作用の両方を抑制します。具体的には、ドライランはしません:

• マーチャントやRoktオペレーターへのアウトバウンドメールを送信しません。
• サードパーティシステム上で状態を変化させる外部API呼び出しを行いません（例：payout-setupでのStripe Connectアカウント作成、これがそのエンドポイントがドライランを全くサポートしない理由です）。
• パートナープラットフォームや下流のRoktサービスへのWebhookを発行しません。
• 下流の処理パイプラインや通知をトリガーしません。
• ポールドオペレーションを作成しません：ドライランのレスポンスはX-Operation-Idを持ちません、なぜならポールするために永続された作業がないからです。

ドライランが残す唯一の永続的な痕跡は、あなたのIdempotency-Keyの下にキャッシュされたレスポンス（同じキーを再試行するとドライランを再生します）と、診断用にdry_run=trueタグが付けられたサーバー側の監査ログエントリです。どちらもAPIを通じてパートナーが観察することはできません。

警告

ドライランは冪等性キーを消費します。 キーKでドライランを行うと、サーバーはドライランのレスポンスをKの下にキャッシュします。その後、同じKで実際の書き込みを送信すると、キャッシュされたドライランのレスポンスが返され、コミットは行われません。実際の呼び出しには新しいIdempotency-Keyを使用してください。

サポートされているエンドポイント

エンドポイント	メソッド	ドライラン?
/v1/partnership/accounts/{account_id}/marketplacecontrolslists	PUT	はい
/v1/partnership/accounts/{account_id}/status	PUT	はい
任意のGET	該当なし	効果なし（無視される）
POST /v1/accounts/register/partnership	POST	いいえ
POST /v1/partnership/accounts/{account_id}/payout-setup	POST	いいえ

ウォークスルー: MCL PUTの検証、状態が変更されていないことを確認

1. 1
   GET current MCL state: capture the content_hash

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN"

   レスポンスには"content_hash": "h_abc123"（marketplace_controls_list内）とtranslated_verticals内の現在のブロックが含まれます。

2. 2
   Dry-run a PUT with a new blocked vertical

   curl

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

   python

   import requests, uuid
   
   resp = requests.put(
       f"https://accounts.rokt.com/v1/partnership/accounts/{account_id}/marketplacecontrolslists",
       params={"dry_run": "true"},
       headers={
           "Authorization": f"Bearer {token}",
           "Idempotency-Key": str(uuid.uuid4()),
       },
       json={
           "name": "Acme Network Controls",
           "blockedVerticals": [
               {"partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block"},
               {"partnerVerticalId": 1500, "partnerSubVerticalId": 1611, "policy": "Block"},
           ],
           "domains": [],
           "contentHash": "h_abc123",
       },
   )
   assert resp.status_code == 200, resp.json()

   node

   import { randomUUID } from "node:crypto";
   
   const resp = await fetch(
     `https://accounts.rokt.com/v1/partnership/accounts/${accountId}/marketplacecontrolslists?dry_run=true`,
     {
       method: "PUT",
       headers: {
         Authorization: `Bearer ${token}`,
         "Idempotency-Key": randomUUID(),
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         name: "Acme Network Controls",
         blockedVerticals: [
           { partnerVerticalId: 1500, partnerSubVerticalId: 1610, policy: "Block" },
           { partnerVerticalId: 1500, partnerSubVerticalId: 1611, policy: "Block" },
         ],
         domains: [],
         contentHash: "h_abc123",
       }),
     }
   );

   レスポンス: 200、完全なMarketplaceControlsResponseの形状で、コミットされたかのように。

3. 3
   GET again: confirm state is unchanged

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN"

   content_hashは依然としてh_abc123。translated_verticalsは依然として事前ドライランの状態を示しています。状態は保持されませんでした。

4. 4
   Real commit: use a FRESH Idempotency-Key

   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 Keys

なぜドライランには実際の呼び出しのために新しいキーが必要なのか。

Vertical Taxonomy

ドライランはコミット前に不足しているマッピングを表面化します。