マーケットプレイスコントロールの更新

Audience

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

このレシピは、すでにオンボードされたマーチャントのマーケットプレイスコントロールの継続的な編集について説明します。パターンは次のとおりです：GET、ローカルで修正、完全な結果をPUT。

警告

PUTは完全な状態を置き換えます。 コントロールエンドポイント（MCL、ステータス）はPUT-置換を使用します。この表面にはPATCHやマージはありません。常に最初にGETし、ローカルで修正し、修正された完全なリストをPUTします。PUTから省略したものはすべてブロック解除されます。レイアウト編集エンドポイント (PATCH /v1/partnership/accounts/{id}/layouts/{layout_id}) は、パートナーシップAPIで唯一のPATCHエンドポイントであり、コントロールには適用されません。SETセマンティクスを参照してください。

GET the current state

現在のMCLを取得し、ステップ3で楽観的同時実行制御のためにmarketplace_controls_list.content_hashをキャプチャします。

curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT"

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...",
  "data": {
    "account_id": "<your-account-id>",
    "marketplace_controls_list": {
      "marketplace_controls_list_id": "8c6f2a1e-...",
      "domains": [ { "domain": "competitor.example.com", "policy": "Block" } ],
      "content_hash": "v7-1a9e3f4c"
    },
    "translated_verticals": [
      { "vertical_id": 1610, "policy": "Block", "position_1_policy": "Block" },
      { "vertical_id": 1611, "policy": "Allow", "position_1_policy": "Allow" }
    ]
  }
}

translated_verticalsは、あなたの分類法でマッピングされたすべてのサブバーティカルに対する有効なポリシーを保持します。vertical_idはRoktのIDではなく、あなたのサブバーティカルIDです。

Modify locally

新しいブロックされたバーティカルを追加し、既に持っていたものを保持します。GETレスポンスのtranslated_verticalsを基にリクエストボディを構築します：policyがBlockであるエントリを保持します。レスポンスはあなたのサブバーティカルID (vertical_id) をエコーします。PUTボディには完全な{partnerVerticalId, partnerSubVerticalId}ペアが必要なので、各IDをあなた自身の分類法から親バーティカルIDに解決します。

javascript
python

const envelope = await getMcl(accountId); // GET above
const current = envelope.data;            // unwrap the envelope

const next = {
  name: "Acme Network Controls",
  blockedVerticals: [
    ...current.translated_verticals
      .filter(v => v.policy === "Block")
      .map(v => ({
        partnerVerticalId: parentVerticalOf(v.vertical_id), // your taxonomy lookup
        partnerSubVerticalId: v.vertical_id,
        policy: "Block",
        position1Policy: v.position_1_policy ?? "Block",
      })),
    // append the new one
    { partnerVerticalId: 1500, partnerSubVerticalId: 1612, policy: "Block", position1Policy: "Block" },
  ],
  domains: current.marketplace_controls_list.domains,
  contentHash: current.marketplace_controls_list.content_hash, // pass back for optimistic concurrency
};

envelope = get_mcl(account_id)  # GET above
current = envelope["data"]      # unwrap the envelope

next_body = {
    "name": "Acme Network Controls",
    "blockedVerticals": [
        {
            "partnerVerticalId": parent_vertical_of(v["vertical_id"]),  # your taxonomy lookup
            "partnerSubVerticalId": v["vertical_id"],
            "policy": "Block",
            "position1Policy": v.get("position_1_policy") or "Block",
        }
        for v in current["translated_verticals"]
        if v["policy"] == "Block"
    ] + [
        {"partnerVerticalId": 1500, "partnerSubVerticalId": 1612, "policy": "Block", "position1Policy": "Block"}
    ],
    "domains": current["marketplace_controls_list"]["domains"],
    "contentHash": current["marketplace_controls_list"]["content_hash"],
}

3
PUT the modified list
完全な望ましい状態を送信します。contentHashを含めて、GETとPUTの間に誰かが行を更新した場合にサーバーが書き込みを拒否できるようにします。
curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d @next.json
サーバーがcontentHashエラーを返した場合、GETとPUTの間に誰かが行を変更しました。再度GETし、最新の状態に変更を再適用して再試行します。同じキーで安全に再試行できる理由については冪等性キーを参照してください。
注記
エンドツーエンドの古いハッシュ拒否はプレビューグレードです：スキーマを通じて検証されていますが、このパートナーサーフェスではまだライブで観察されていません。409パスはGAまで最善の努力として扱ってください。
4
Optionally dry-run first
?dry_run=trueを追加して、ペイロードを検証します（完全な検証と分類法の翻訳）。状態は保存されません。
curl -X PUT 'https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists?dry_run=true' \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d @next.json
注記
実際の書き込みのためにdry_runなしで再呼び出すときは、新しい冪等性キーを使用してください。ドライランキーは現在キャッシュされています。ドライランモードを参照してください。

Verify

再度GETし、新しいバーティカルが存在し、以前のブロックがまだあり、domainsが変更されていないことを確認します。

curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT"

一般的な注意点一般的な注意点への直接リンク

新しいバーティカルを1つ送信したら、以前のすべてのブロックが失われた

SETセマンティクス。PUTは望ましい状態であり、パッチではありません。常にGET-修正-PUTで完全なリストを操作してください。サーバー上でのマージはありません。もし[{ vertical: 1612 }]だけを送信した場合、それはサーバーに「1612がリスト全体である」と伝え、他のすべてをブロック解除したことになります。

PUTが409を返し、contentHashエラーが発生

他の誰か（またはあなたのサービスの別のインスタンス）が、あなたのGETとPUTの間に行を変更しました。送信したcontentHashが、サーバーの現在の状態と一致しなくなっています。

解決策: 再度GETし、新しい状態に変更を適用し、PUTを再試行してください。同じIdempotency-Keyを保持することができます。前回の試行が拒否され、コミットされなかったため、サーバーは新しいペイロードを新しい操作として扱います。

サーバーが400を返す: '次のパートナーバーティカルに対するバーティカルマッピングが見つかりません'

あなたのpartnerVerticalId / partnerSubVerticalIdペアの1つ以上がRoktのバーティカルマッピングテーブルに存在しません。PUTはアトミックに拒否されます：部分的な書き込みはありません。

メッセージにはマッピングされていないすべてのペアが名前付きで示されるため、一度に修正できます:

No vertical mapping found for the following partner vertical(s):
(partner_vertical_id=1500, partner_sub_vertical_id=1610). Call GET
/v1/partnership/vertical-mappings to see which verticals are currently
mapped, and contact smb-partnerships@rokt.com to request additions. The
MCL write was rejected atomically; no partial update was applied.

解決策: GET /v1/partnership/vertical-mappings?parent_account_id=<your-parent>を呼び出して現在のセットを確認し（マッピングされているものを確認を参照）、マッピングされていないIDをsmb-partnerships@rokt.comにメールで送信してください。私たちが行を追加します。その間、あなたのPUTからマッピングされていないバーティカルを省略してください。

すべてのブロックをクリアしたい

blockedVerticals: []とdomains: []を送信してください。サーバーは空の配列を「ブロックなし」として扱います。それがSETセマンティクスの固定点です。

一般的な注意点一般的な注意点 への直接リンク

一般的な注意点一般的な注意点への直接リンク