SET セマンティクス

Audience

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

PUTは、ControlsとStatusルートで完全な状態を置き換えます。マージも差分もPATCHもありません。最も一般的な統合バグは、パートナーがPUTを増分更新として扱うことです。 putMarketplaceControlsやputPartnershipStatusに触れる前にこのページを読んでください。

警告

PUTは置き換えます。 blockedVerticals: [{partnerVerticalId: 1500, ...}]を送信すると、その1つのカテゴリだけがブロックされます。以前にブロックしていたが含まれていないカテゴリは今は許可されています。domainsも同様です。常にGET → 修正 → PUTで完全なリストを送信してください。

なぜPUTは置き換えるのか

PUTは「これが現在の商人の完全な望ましい制御状態です」と言います。サーバーは保存された状態をあなたの状態に一致させます。リクエストボディに含まれていないものは、定義上、望ましい状態にないため削除されます。

正しいワークフローは常に:

GET /…/marketplacecontrolslists      ──▶  current full list + content_hash
       │
       ▼
modify locally (add/remove/change)
       │
       ▼
PUT /…/marketplacecontrolslists      ──▶  send the full modified list

間違いと正解

現在、商人は1500と1502のカテゴリをブロックしています。パートナーは1504のブロックを追加したいと考えています。

wrong.json

{
  "name": "Acme Network Controls",
  "blockedVerticals": [
    { "partnerVerticalId": 1504, "partnerSubVerticalId": 1612, "policy": "Block" }
  ]
}

right.json

{
  "name": "Acme Network Controls",
  "blockedVerticals": [
    { "partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block" },
    { "partnerVerticalId": 1502, "partnerSubVerticalId": 1620, "policy": "Block" },
    { "partnerVerticalId": 1504, "partnerSubVerticalId": 1612, "policy": "Block" }
  ],
  "contentHash": "h_abc123"
}

wrong.jsonは1500と1502のブロックを解除します。 サーバーはあなたが送信したものに忠実に状態を置き換えます。エラーも警告もなく、商人は翌日、以前ブロックされていた2つのカテゴリがライブになっていることに気づきます。

right.jsonはパートナーが意図したことを実行します: 1504をブロックセットに追加し、1500と1502を保持し、楽観的同時実行性の安全のために以前のGETからのcontentHashを含めます。

SETセマンティクスに従うエンドポイント

エンドポイント	SETされるもの
PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists	blockedVerticals, domains
PUT /v1/partnership/accounts/{account_id}/status	すべての非アーカイブされたバリアントのアクティブ/一時停止状態

ステータスについて: PUT status=pausedは、すべての非アーカイブされたページバリアントを一時停止します。「バリアントXのみを一時停止する」ということはありません。それは部分的な状態であり、SETモデルでは禁じられています。バリアントごとの制御が必要な場合、それは現在のPartnerships APIサーフェスにはありません。

contentHashを用いた楽観的同時実行性

すべてのGETレスポンスにはmarketplace_controls_list.content_hashが含まれています。PUTのcontentHashフィールドとして返すことで、同時編集を安全に検出できます。別の呼び出し元（またはRokt側の管理ツール）がGETとPUTの間に行を更新した場合、サーバーは競合としてPUTを拒否します。contentHashがない場合、最後に書き込んだものが勝ちます。

{
  "name": "Acme Network Controls",
  "blockedVerticals": [...],
  "contentHash": "h_abc123"
}

以下の場合に使用します:

• ダッシュボード内で複数の人間が同じ商人を同時に編集する可能性がある場合。
• 長時間実行されるバッチジョブとリアルタイムUIが同じアカウントで競合する可能性がある場合。

以下の場合はスキップします:

• 単一のライターで一度だけの移行をスクリプト化している場合。

ウォークスルー: ドメインブロックを追加

1. 1
   GET the current MCL state

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

   レスポンス data (省略):

   {
     "marketplace_controls_list": {
       "domains": [
         { "domain": "competitor.example.com", "policy": "Block" }
       ],
       "content_hash": "h_abc123"
     },
     "translated_verticals": [
       { "vertical_id": 1610, "policy": "Block", "position_1_policy": "Block" }
     ]
   }

2. 2
   Append the new domain block locally

   { "domain": "competitor-two.example.com", "policy": "Block" }をdomains配列に追加します。他のすべてを保持します。

3. 3
   PUT the FULL modified state back

   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 '{
       "name": "Acme Network Controls",
       "blockedVerticals": [
         {"partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block"}
       ],
       "domains": [
         {"domain": "competitor.example.com", "policy": "Block"},
         {"domain": "competitor-two.example.com", "policy": "Block"}
       ],
       "contentHash": "h_abc123"
     }'

   両方のドメインが現在ブロックされています。1500/1610のカテゴリブロックは、送信したため保持されています。

Related

Vertical Taxonomy

パートナーの垂直IDがPUTでRoktの分類法にどのように変換されるか。

Operation Polling

ボディを再送信せずに失われたPUTレスポンスから回復する方法。