次の方法で共有


精選された 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 オブジェクトに依存しており、キュレーションされた取引明細を作成するときにオブジェクトを作成またはアクセスする際に従う必要がある順序があります。 たとえば、 advertiserinsertion-orderdealprofileの API オブジェクトの ID を指定する必要があります。 これらのオブジェクトの ID を取得するには、ID を作成するか、既にアクセスする必要があります。 このガイドの手順は、キュレーションされた取引明細を作成するために必要な一般的な操作順序に従います。

ベスト プラクティス

API を操作するときに従うベスト プラクティスの一般的な一覧については、「 API のベスト プラクティス」を参照してください。 次に示すベスト プラクティスは、キュレーションされた取引明細の設定に固有のものです。

  • 明細が完全に構成され、テストの準備が整うまで、キュレーションされた取引明細の state フィールドを "inactive" に設定します。
  • 作成するオブジェクトの ID をメモします。 作成したオブジェクトの ID は、要求の応答本文で返されます。 多くの場合、これらの ID は後で必要になるため、返されたときに ID をコピーすると、取得するために行う必要がある追加の GET 要求の数を減らすことができます。

セットアップ手順

次の手順では、一般的な構成で精選された取引明細項目を設定するプロセスについて説明します。

手順 1 - 承認トークンを取得する

まず、承認トークンを取得する必要があります。 その後、後続のすべての要求にこの承認トークンを含める必要があります (詳細については、「 認証サービス 」を参照してください)。 承認トークンを取得するには、次の操作を行います。

  1. ユーザー名とパスワードを含む JSON ファイルを作成します。

    {
        "auth": {
            "username" : "USERNAME",
            "password" : "PASSWORD"
        }
    }
    
  2. 要求本文にこの JSON ファイルを使用して、/auth エンドポイントにPOST要求を行います (詳細については、「認証サービス」を参照してください)。 以下の cURL 要求では、返される承認トークンは "cookies" ファイルに格納されます。

    curl -c cookies -X POST -d @authentication.json 'https://api.appnexus.com/auth'
    
  3. 要求の応答本文を確認します (後述の 応答例 を参照)。 要求が成功した場合は、"OK" の "status" が取得され、[token] フィールドに認証トークンの値が入力されます。

    応答の例

    {
       "response" : {
          "token" : "authn:225692:2d787d1838283:lax1",
          "status" : "OK"      
       }
    }
    

手順 2 - 広告主を作成またはアクセスする

精選された取引広告申込情報を作成するには、広告主を作成またはアクセスする必要があります。 精選された取引広告申込情報の広告主は、拡張広告申込情報の場合と同じ方法で設定します。

使用する広告主がまだない場合は、次の手順を実行して広告主を作成します (詳細については、「 広告主サービス 」を参照してください)。

  1. 広告主の JSON を作成する:

    $ cat advertiser.json
    {
        "advertiser": {
            "name": "Curated Deal Line Item Example Advertiser",
            "timezone": "US/Pacific"
        }
    }
    
  2. この広告主の 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'
    
  3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

  4. 手順 6 - キュレーションされた取引の広告申込情報を作成するでキュレーションされた取引の広告申込情報を作成するときに使用できるように、応答本文の広告主 ID をメモします。

広告主の JSON フィールド (必須および便利な省略可能なフィールド)

フィールド 種類 必須またはオプション 説明
name string 必須 広告主の名前
timezone 列挙 省略可能 広告主のタイムゾーン。 詳細と受け入れられる値については、「 API タイムゾーン 」を参照してください。
use_insertion_orders ブール値 必須 キュレーションされた取引明細を作成するには、このフィールドを true に設定する必要があります。

手順 3 - 挿入順序を作成またはアクセスする

精選された取引明細を作成するには、挿入注文を作成またはアクセスする必要があります。 精選された取引明細には、シームレスな挿入順序が必要です (下記 の必須 フィールドを参照してください)。

使用する挿入順序がまだない場合は、次の手順を実行して挿入順序を作成します (詳細については、「 挿入順序サービス 」を参照してください)。

  1. 挿入順序 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"
        }
    }
    
  2. この挿入順序 JSON と適切なadvertiser_idmember_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'
    
  3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

  4. 手順 6 - キュレーションされた取引明細項目を作成するでキュレーションされた取引明細を作成するときに使用できるように、応答本文の挿入順序 ID をメモします。

シームレスな挿入順序の JSON フィールド

フィールド 種類 必須またはオプション 説明
budget_intervals オブジェクトの配列 必須 API を介して作成された挿入順序をシームレスにするには、 budget_intervals フィールドを使用する必要があります。
name string 必須 広告主の名前

手順 4 - 取引を作成する

キュレーションされた取引明細に関連付ける取引を作成する必要があります。

取引を作成するには、次の操作を行います (詳細については、「 Deal Service 」を参照してください)。

  1. 取引 JSON を作成します。

    $ cat deal.json
    {
        "deal": {
            "name": "Curated Deal",
            "buyer": {
                "id": 2379
            },
            "type": {
                "id": 5,
                "name": "Curated"
            },
            "version": 2
        }
    }
    
  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'
    
  3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

  4. 手順 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_targetspublisher_targets、またはcontent_category_targetsをキュレーションされた取引明細で使用することはできません。 詳細については、「 プロファイル サービス 」を参照してください。

精選された取引明細プロファイルを作成するには、次の操作を行います (詳細については、「 プロファイル サービス 」を参照してください)。

  1. キュレーションされた取引明細プロファイル 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": {
        }
    }
    
  2. このキュレーションされた取引プロファイル 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'
    
  3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

  4. 手順 6 - キュレーションされた取引明細項目を作成するでキュレーションされた取引明細を作成するときに使用できるように、応答本文のプロファイル ID をメモします。

取引明細プロファイルのオプションの JSON フィールド

キュレーションされた取引明細プロファイルには、キュレーションされた取引明細項目を対象にするための多くのオプションフィールドがあります。 たとえば、インベントリ、インベントリの種類、許可リスト、ブロックリスト、デバイスの種類などに関連付けられているプロパティをターゲットにすることができます。 使用可能なフィールドの詳細については、 プロファイル サービス を参照してください。

手順 6 - キュレーションされた取引明細を作成する

最後に、「手順 5 - キュレーションされた取引明細プロファイルを作成する」で作成した取引 ID とキュレーションされた取引明細プロファイルを関連付けるために、 精選された取引明細項目を作成する必要があります。

精選された取引明細を作成するには、次の操作を行います (詳細については、「 明細サービス 」を参照してください)。

  1. 精選された取引広告申込情報 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
                    }
            }
    }
    
  2. この取引明細 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'
    
  3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

  4. 応答本文の行項目 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_datenull のままにします。
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_typecpm (固定) に設定した場合は、revenue_valueを使用して固定価格を設定します。 Standard を使用している場合は、この値を null に設定します。
valuation object キュレーション取引の場合は、次の評価対象フィールドを使用します。
- min_revenue_value
- revenue_typevcpm (Standard) に設定した場合は、フロア価格を min_revenue_value に設定します。
- revenue_typecpm (固定) に設定した場合は、 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_idpayment_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_budgetdaily_budget_impslifetime_budgetlifetime_budget_impsなど、budget_intervals内のフィールドを使用して、取引に予算を設定します。 キュレーションされた取引明細に収益予算タイプがある場合は imp なしのフィールドを使用し、取引明細に収益タイプのインプレッションがある場合は最後に _imp フィールドを使用します。 両方ではなく、1 日または一生の予算を使用できます。 フライト間に配置される有効期間の予算は、API を介して各フライトで分割されます。 取引に終了日がない場合は、予算を設定できないことに注意してください。
state 列挙 キュレーションされた取引明細の状態。 既定値は activeであるため、取引をすぐに公開したくない場合は、 inactive に設定します。