精選された Deal Line Item API のセットアップ ガイド
取引を対象とする精選取引明細の API 実装を設定するには、さまざまな API オブジェクトに対してさまざまなプロパティを構成する必要があります。 このガイドでは、API を使用してキュレーションされた取引明細項目を作成および構成するプロセスについて説明します。
概要
キュレーションされた取引は、キュレーターの専有資産とXandr Marketplaceの供給を組み合わせたバイヤーとキュレーターの間で交渉された契約を表します。 これらの専有資産には、対象ユーザーデータ、優先在庫アクセス、特別に交渉されたレート、最適化人材、投資戦略、および取引供給を強化し、ユニークなオファリングを作成するその他の機能が含まれます。 取引キュレーターは、Xandr Platform に独自のメンバーシートを持ち、供給と自分の資産をバイヤー向けのキュレーションされた取引 ID にパッケージ化するために使用します。 Xandr取引所に統合されたDSPは、キュレーションされた取引を購入することができます。
通常、キュレーションされた取引行項目を設定するには、対応する API オブジェクトにアクセスまたは作成するために、次の API サービス エンドポイントに要求を行う必要があります。
API エンドポイント | API オブジェクト | 詳細なリファレンス |
---|---|---|
https://api.appnexus.com/advertiser |
広告 主 | 広告主サービス |
https://api.appnexus.com/insertion-order |
insertion-order | 挿入注文サービス |
https://api.appnexus.com/deal |
対処する | Deal Service |
https://api.appnexus.com/profile |
profile | Profile Service |
https://api.appnexus.com/line-item |
line-item (ALI) | 明細 - ALI サービス |
このガイドでは、すべての要求に cURL の例を使用します。 他の API 要求ツール ( Postman など) を使用できますが、それに応じて例を調整する必要があります。
前提条件
このセットアップを開始する前に、「 API の概要」を必ずお読みください。 テスト環境、使用制約、API セマンティクス (コマンドの実行、フィルター処理、並べ替えなど)、ベスト プラクティスに関する情報を提供します。
操作の順序
API オブジェクトは、多くの場合、他の API オブジェクトに依存しており、キュレーションされた取引明細を作成するときにオブジェクトを作成またはアクセスする際に従う必要がある順序があります。 たとえば、 advertiser
、 insertion-order
、 deal
、 profile
の API オブジェクトの ID を指定する必要があります。 これらのオブジェクトの ID を取得するには、ID を作成するか、既にアクセスする必要があります。 このガイドの手順は、キュレーションされた取引明細を作成するために必要な一般的な操作順序に従います。
ベスト プラクティス
API を操作するときに従うベスト プラクティスの一般的な一覧については、「 API のベスト プラクティス」を参照してください。 次に示すベスト プラクティスは、キュレーションされた取引明細の設定に固有のものです。
- 明細が完全に構成され、テストの準備が整うまで、キュレーションされた取引明細の
state
フィールドを"inactive"
に設定します。 - 作成するオブジェクトの ID をメモします。 作成したオブジェクトの ID は、要求の応答本文で返されます。 多くの場合、これらの ID は後で必要になるため、返されたときに ID をコピーすると、取得するために行う必要がある追加の
GET
要求の数を減らすことができます。
セットアップ手順
次の手順では、一般的な構成で精選された取引明細項目を設定するプロセスについて説明します。
- 手順 1 - 承認トークンを取得する
- 手順 2 - 広告主を作成またはアクセスする
- 手順 3 - 挿入順序を作成またはアクセスする
- 手順 4 - 取引を作成する
- 手順 5 - 厳選された取引明細プロファイルを作成する
- 手順 6 - キュレーションされた取引明細を作成する
手順 1 - 承認トークンを取得する
まず、承認トークンを取得する必要があります。 その後、後続のすべての要求にこの承認トークンを含める必要があります (詳細については、「 認証サービス 」を参照してください)。 承認トークンを取得するには、次の操作を行います。
ユーザー名とパスワードを含む JSON ファイルを作成します。
{ "auth": { "username" : "USERNAME", "password" : "PASSWORD" } }
要求本文にこの JSON ファイルを使用して、
/auth
エンドポイントにPOST
要求を行います (詳細については、「認証サービス」を参照してください)。 以下の cURL 要求では、返される承認トークンは "cookies
" ファイルに格納されます。curl -c cookies -X POST -d @authentication.json 'https://api.appnexus.com/auth'
要求の応答本文を確認します (後述の 応答例 を参照)。 要求が成功した場合は、"
OK
" の "status
" が取得され、[token
] フィールドに認証トークンの値が入力されます。
応答の例{ "response" : { "token" : "authn:225692:2d787d1838283:lax1", "status" : "OK" } }
手順 2 - 広告主を作成またはアクセスする
精選された取引広告申込情報を作成するには、広告主を作成またはアクセスする必要があります。 精選された取引広告申込情報の広告主は、拡張広告申込情報の場合と同じ方法で設定します。
使用する広告主がまだない場合は、次の手順を実行して広告主を作成します (詳細については、「 広告主サービス 」を参照してください)。
広告主の JSON を作成する:
$ cat advertiser.json { "advertiser": { "name": "Curated Deal Line Item Example Advertiser", "timezone": "US/Pacific" } }
この広告主の JSON と適切な
member_id
を使用して、https://api.appnexus.com/advertiser
エンドポイントにPOST
要求を行います。$ curl -b cookies -c cookies -X POST -d @advertiser.json 'https://api.appnexus.com/advertiser?member_id=2378'
要求の応答本文を確認します。 要求が成功した場合は、"
OK
" の "status
" が表示され、行った更新が表示されます。手順 6 - キュレーションされた取引の広告申込情報を作成するでキュレーションされた取引の広告申込情報を作成するときに使用できるように、応答本文の広告主 ID をメモします。
広告主の JSON フィールド (必須および便利な省略可能なフィールド)
フィールド | 種類 | 必須またはオプション | 説明 |
---|---|---|---|
name |
string | 必須 | 広告主の名前 |
timezone |
列挙 | 省略可能 | 広告主のタイムゾーン。 詳細と受け入れられる値については、「 API タイムゾーン 」を参照してください。 |
use_insertion_orders |
ブール値 | 必須 | キュレーションされた取引明細を作成するには、このフィールドを true に設定する必要があります。 |
手順 3 - 挿入順序を作成またはアクセスする
精選された取引明細を作成するには、挿入注文を作成またはアクセスする必要があります。 精選された取引明細には、シームレスな挿入順序が必要です (下記 の必須 フィールドを参照してください)。
使用する挿入順序がまだない場合は、次の手順を実行して挿入順序を作成します (詳細については、「 挿入順序サービス 」を参照してください)。
挿入順序 JSON を作成します。
JSON の例: 終了日なし、予算なし
$ cat insertion-order-noenddate.json { "insertion-order": { "name": "Curated Deal Line Item Example IO", "budget_intervals": [{ "start_date": "2019-10-10 00:00:00", "end_date": null, "daily_budget": null, "daily_budget_imps": null, "enable_pacing": true, "lifetime_budget": null, "lifetime_budget_imps": null, "lifetime_pacing": false }], "budget_type": "impression" } }
この挿入順序 JSON と適切な
advertiser_id
とmember_id
を使用して、https://api.appnexus.com/insertion-order
エンドポイントにPOST
要求を行います。要求の例: 終了日なし、予算なし
$ curl -b cookies -c cookies -X POST -d @insertion-order-noenddate.json 'https://api..com/insertion-order?advertiser_id=2605036&member_id=2378'
要求の応答本文を確認します。 要求が成功した場合は、"
OK
" の "status
" が表示され、行った更新が表示されます。手順 6 - キュレーションされた取引明細項目を作成するでキュレーションされた取引明細を作成するときに使用できるように、応答本文の挿入順序 ID をメモします。
シームレスな挿入順序の JSON フィールド
フィールド | 種類 | 必須またはオプション | 説明 |
---|---|---|---|
budget_intervals |
オブジェクトの配列 | 必須 | API を介して作成された挿入順序をシームレスにするには、 budget_intervals フィールドを使用する必要があります。 |
name |
string | 必須 | 広告主の名前 |
手順 4 - 取引を作成する
キュレーションされた取引明細に関連付ける取引を作成する必要があります。
取引を作成するには、次の操作を行います (詳細については、「 Deal Service 」を参照してください)。
取引 JSON を作成します。
$ cat deal.json { "deal": { "name": "Curated Deal", "buyer": { "id": 2379 }, "type": { "id": 5, "name": "Curated" }, "version": 2 } }
この取引 JSON と適切な
member_id
を使用して、https://api.appnexus.com/deal
エンドポイントにPOST
要求を行います。$ curl -b cookies -c cookies -X POST -d @deal.json 'https://api.appnexus.com/deal?member_id=2378'
要求の応答本文を確認します。 要求が成功した場合は、"
OK
" の "status
" が表示され、行った更新が表示されます。手順 6 - キュレーションされた取引明細項目を作成するで取引明細を作成するときに使用できるように、応答本文の取引 ID をメモします。
取引の JSON フィールド
フィールド | 種類 | 必須またはオプション | 説明 |
---|---|---|---|
auction_type |
object | 省略可能 | 取引のオークションの種類 (Standard/Fixed/Market)。 この値は、( revenue_type /min_revenue_value /revenue_value を介して) キュレーションされた取引明細項目に設定されているものと一致する必要があります。 |
buyer |
string | 必須 | 取引の購入者メンバー ID。 このフィールドは、作成後は変更できません。 |
name |
string | 必須 | 取引の名前。 注: 購入者には、この名前が表示されます。 |
type |
object | 必須 | 取引の種類。 このフィールドは、キュレーションされた取引の "5" に設定する必要があります。 |
version |
int | 必須 | このフィールドは、キュレーションされた取引明細に取引を関連付けるために "2" に設定する必要があります。 |
便利な省略可能な JSON フィールド
許可されたクリエイティブの JSON フィールド
ブランド ( 「ブランド サービス」を参照)
フィールド | 種類 | 説明 |
---|---|---|
brand_restrict |
ブール値 |
-
True :取引はリストされたブランドにのみ制限されています- False : その他のブランドのサービスが許可されています |
brands |
オブジェクトの配列 | 対象となるブランドの配列 |
id |
int |
brands 内のフィールド: 取引の対象となるブランドの ID |
name |
string |
brands 内のフィールド: 取引の対象となるブランドの名前 |
override |
ブール値 |
brands 内のフィールド: 広告品質プロファイルでブロックされた可能性がある場合でも、特定のブランドが取引に対してサービスを提供できるようにするには、true に設定します。 |
ブランドの例
"brand_restrict": true,
"brands": [
{
"id": 2,
"name": "1800Flowers",
"override": true
},
{
"id": 4,
"name": "Acura",
"override": false
}
]
メディアの種類 ( メディア サブタイプ サービス と メディア タイプ サービスを参照)
フィールド | 種類 | 説明 |
---|---|---|
allowed_media_subtypes |
オブジェクトの配列 | 取引で許可されるメディア サブタイプ。 |
id |
int |
allowed_media_subtypes 内のフィールド: 取引で許可されるメディア サブタイプの ID |
allowed_media_types |
オブジェクトの配列 | 取引で許可されるメディアの種類 |
id |
int |
allowed_media_types 内のフィールド: 取引で許可されるメディアの種類の ID |
メディアの種類の例
"allowed_media_subtypes": [
{
"id": 2,
"last_modified": "2015-09-17 19:19:21",
"media_type": {
"id": 2,
"media_type_group_id": 2,
"name": "Pop",
"uses_sizes": "sometimes"
},
"name": "Popup",
"native_assets": null,
"permitted_sizes": null
}
],
"allowed_media_types": [
{
"id": 1,
"last_modified": "2012-03-16 21:36:10",
"media_type_group_id": 1,
"name": "Banner",
"uses_sizes": "always"
},
{
"id": 4,
"last_modified": "2016-08-22 16:23:12",
"media_type_group_id": 1,
"name": "Video",
"uses_sizes": "never"
}
]
手順 5 - 厳選された取引明細プロファイルを作成する
次に、キュレーションされた取引広告申込情報のターゲティングに使用する、精選された取引明細プロファイルを作成します。 後で使用するために、このプロファイルの ID を必ず書き留めておいてください。 詳細については、「 プロファイル サービス 」を参照してください。
注:
次の配列を使用して、キュレーションされた取引広告申込情報で販売者の発行元、配置、カテゴリをターゲットにすることができます。
platform_publisher_targets
platform_placement_targets
-
platform_content_category_targets
.
placement_targets
、publisher_targets
、またはcontent_category_targets
をキュレーションされた取引明細で使用することはできません。 詳細については、「 プロファイル サービス 」を参照してください。
精選された取引明細プロファイルを作成するには、次の操作を行います (詳細については、「 プロファイル サービス 」を参照してください)。
キュレーションされた取引明細プロファイル JSON を作成します。
例: 国と表示レートの完了率のしきい値を使用したプロファイルの作成
$ cat profile.json { "profile": { "country_action": "include", "country_targets": [{ "active": true, "code": "US", "id": 233, "name": "United States" }], "engagement_rate_targets": [{ "engagement_rate_pct": 25, "engagement_rate_type": "video_completion" }, { "engagement_rate_pct": 50, "engagement_rate_type": "predicted_iab_video_view_rate" } ], "platform_publisher_targets": [{ "action": "include", "deleted": false, "id": 1238721, "name": "test_publisher" }], "platform_placement_targets": [{ "action": "include", "deleted": false, "id": 5126395 }, { "action": "include", "deleted": false, "id": 5301719 } ], "platform_content_category_targets": [{ "action": "include", "deleted": false, "id": 19062, "is_system": false, "name": "1" }] } }
例: ターゲットを設定せずにプロファイルを作成する
> cat profile.json { "profile": { } }
このキュレーションされた取引プロファイル JSON と適切な
advertiser_id
を使用して、https://api.appnexus.com/profile
エンドポイントにPOST
要求を行います。例: 国と表示レートの完了率のしきい値を使用したプロファイルの作成
> curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
例: ターゲットを設定せずにプロファイルを作成する
> curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
要求の応答本文を確認します。 要求が成功した場合は、"
OK
" の "status
" が表示され、行った更新が表示されます。手順 6 - キュレーションされた取引明細項目を作成するでキュレーションされた取引明細を作成するときに使用できるように、応答本文のプロファイル ID をメモします。
取引明細プロファイルのオプションの JSON フィールド
キュレーションされた取引明細プロファイルには、キュレーションされた取引明細項目を対象にするための多くのオプションフィールドがあります。 たとえば、インベントリ、インベントリの種類、許可リスト、ブロックリスト、デバイスの種類などに関連付けられているプロパティをターゲットにすることができます。 使用可能なフィールドの詳細については、 プロファイル サービス を参照してください。
手順 6 - キュレーションされた取引明細を作成する
最後に、「手順 5 - キュレーションされた取引明細プロファイルを作成する」で作成した取引 ID とキュレーションされた取引明細プロファイルを関連付けるために、 精選された取引明細項目を作成する必要があります。
精選された取引明細を作成するには、次の操作を行います (詳細については、「 明細サービス 」を参照してください)。
精選された取引広告申込情報 JSON を作成します (既存の広告主 ID、挿入注文 ID、取引 ID、プロファイル ID が必要です)。
JSON の例: 予算のない精選された取引の行項目
> cat curated_deal_line_item.json { "line-item": { "ad_types": ["video"], "auction_event": { "kpi_auction_type_id": 1, "payment_auction_type_id": 1, "revenue_auction_type_id": 1 }, "budget_intervals": [{ "start_date": "2019-10-11 12:00:00" }], "deals": [{ "id": 628539 }], "insertion_orders": [{ "id": 1363850 }], "line_item_subtype": "standard_curated", "name": "Curated Deal Line Item Example Line Item", "revenue_type": "vcpm", "revenue_value": null, "supply_strategies": { "managed": false, "deals": true, "rtb": false }, "profile_id": 113067333, "valuation": { "min_revenue_value": 10 } } }
JSON の例: 精選された取引明細の 1 日あたりの収益予算
> cat curated_deal_line_item_daily.json { "line-item": { "ad_types": ["video"], "auction_event": { "kpi_auction_type_id": 1, "payment_auction_type_id": 1, "revenue_auction_type_id": 1 }, "budget_intervals": [{ "daily_budget_imps": 270, "end_date": "2019-10-18 23:59:59", "start_date": "2019-10-11 12:00:00", "timezone": "US/Pacific" }], "deals": [{ "id": 618159 }], "insertion_orders": [{ "id": 1363850 }], "line_item_subtype": "standard_curated", "name": "Curated Deal Line Item Example Line Item", "revenue_type": "vcpm", "revenue_value": null, "supply_strategies": { "managed": true, "deals": true, "rtb": false }, "profile_id": 113067333, "valuation": { "min_revenue_value": 10 } } }
この取引明細 JSON と適切な
advertiser_id
を使用して、https://api.appnexus.com/line-item
エンドポイントに対してPOST
要求を行います。要求の例: 予算のない精選された取引明細
> curl -b cookies -c cookies -X POST -d @curated_deal_line_item.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
要求の例: 精選された取引明細の 1 日あたりの収益予算
> curl -b cookies -c cookies -X POST -d @curated_deal_line_item_daily.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
要求の応答本文を確認します。 要求が成功した場合は、"
OK
" の "status
" が表示され、行った更新が表示されます。応答本文の行項目 ID をメモして、このキュレーションされた取引明細項目を後で識別して、その
state
(active
またはinactive
) を変更したり、変更したりできます。
精選された取引明細の JSON フィールド
フィールド | 種類 | 説明 |
---|---|---|
insertion_orders |
配列 | この精選された取引の行項目を関連付ける挿入順序 ID を含む配列 |
name |
string | キュレーションされた取引明細項目の名前 (注: 購入者はこれを表示しません) |
ad_types |
配列 | このキュレーションされた取引広告申込情報に使用されるクリエイティブの種類。 使用可能な値: - "banner" - "video" (オーディオの種類も含まれます)- "native" |
line_item_subtype |
列挙 | 明細サブタイプ。 精選された取引明細の場合、このフィールドの値は "standard_curated" する必要があります。
このフィールドのメモを参照してください。 |
profile_id |
integer | 精選された取引明細に関連付けられているプロファイル ID ( 「手順 5 - キュレーションされた取引明細プロファイルを作成する」を参照) |
budget_intervals |
オブジェクトの配列 | 常に start_date を含めます。 終了日のない取引明細については、 end_date null のままにします。 |
deals |
オブジェクトの配列 | 取引内の id フィールドは、 手順 4 - 取引の作成で作成した取引の ID である必要があります。 |
supply_strategies |
object | ターゲットにする在庫供給ソースを指定するために使用される、いくつかのブール値フィールドを含むオブジェクト。 キュレーションされた取引明細の場合、 managed フィールドを false に設定する必要があります (この値は、 "line_item_subtype" が "standard_curated" に設定されている場合に割り当てられます)注: rtb フィールドまたは deals フィールドは、 true に設定する必要があります ( "line_item_subtype" が "standard_curated" に設定されている場合、これらのフィールドは割り当てません)、それに応じてこれらの値を割り当てる必要があります。用語注: - rtb は、Open Exchange Inventory Aggregation を参照します。- deals は、ロールアップ 取引を参照します |
revenue_type |
列挙 |
cpm 固定価格 (CPM) 取引の場合は、標準価格 (動的 CPM) 取引の vcpm 。 |
revenue_value |
double |
revenue_type を cpm (固定) に設定した場合は、revenue_value を使用して固定価格を設定します。 Standard を使用している場合は、この値を null に設定します。 |
valuation |
object | キュレーション取引の場合は、次の評価対象フィールドを使用します。 - min_revenue_value - revenue_type を vcpm (Standard) に設定した場合は、フロア価格を min_revenue_value に設定します。- revenue_type を cpm (固定) に設定した場合は、 min_revenue_value の値を null に設定します。 - min_margin_cpm - 余白の種類として CPM を使用する場合は、 min_margin_cpm で余白の値を設定します。- min_margin_pct - 余白の種類としてパーセンテージを使用する場合は、 min_margin_pct で余白の値を設定します。注: min_margin_cpm フィールドと min_margin_pct フィールドの両方を同時に設定することはできません。 1 つが設定されている場合は、もう一方を null する必要があります。 |
auction_event |
object | オークション イベントの種類のプロパティのオブジェクト: auction_event オブジェクトの kpi_auction_type_id 、 payment_auction_type_id 、および revenue_auction_type_id フィールドはすべて、 1 に設定する必要があります。 |
line_item_subtype
フィールドに関する注意
フィールド line_item_subtype
を "standard_curated"
に設定すると、これらの関連フィールドに次の値が自動的に割り当てられます。
"line_item_type": "standard_v2",
"bid_object_type": "deal",
"delivery_model_type": "standard",
"supply_strategies": {
"managed": false,
"programmatic_guaranteed": false
}
行項目の作成後、 line_item_subtype
フィールド (および関連するフィールド/配列) を変更することはできません。
精選された取引の行項目に便利なオプションの JSON フィールド
フィールド | 種類 | 説明 |
---|---|---|
budget_intervals |
オブジェクトの配列 |
daily_budget 、daily_budget_imps 、lifetime_budget 、lifetime_budget_imps など、budget_intervals 内のフィールドを使用して、取引に予算を設定します。 キュレーションされた取引明細に収益予算タイプがある場合は imp なしのフィールドを使用し、取引明細に収益タイプのインプレッションがある場合は最後に _imp フィールドを使用します。 両方ではなく、1 日または一生の予算を使用できます。 フライト間に配置される有効期間の予算は、API を介して各フライトで分割されます。 取引に終了日がない場合は、予算を設定できないことに注意してください。 |
state |
列挙 | キュレーションされた取引明細の状態。 既定値は active であるため、取引をすぐに公開したくない場合は、 inactive に設定します。 |