Deal Line Item API のセットアップ ガイド

取引を対象とする Deal Line Item の API 実装を設定するには、さまざまな API オブジェクトに対してさまざまなプロパティを構成する必要があります。 このガイドでは、API を使用して取引明細を作成および構成するプロセスについて説明します。

概要

取引明細は、ネットワーククライアントとパブリッシャークライアントが、パッケージ化されたユーザーフレンドリーな購入ツールを提供することで、バイヤーをより適切にサポートできる強力な機能です。

通常、取引明細を設定するには、対応する API オブジェクトにアクセスまたは作成するために、次の API サービス エンドポイントに要求を行う必要があります。

このガイドでは、すべての要求に cURL の例を使用します。 他の API 要求ツール ( Postman など) を使用できますが、それに応じて例を調整する必要があります。

前提条件

このセットアップを開始する前に、「 API の概要」を必ずお読みください。 テスト環境、使用制約、API セマンティクス (コマンドの実行、フィルター処理、並べ替えなど)、ベスト プラクティスに関する情報を提供します。

操作の順序

API オブジェクトは、多くの場合、他の API オブジェクトに依存しており、取引明細を作成するときにオブジェクトの作成またはアクセスに従う必要がある順序があります。 たとえば、次の API オブジェクトの ID を指定する必要があります。
- advertiser
- insertion-order
- deal
- profile.

これらのオブジェクトの ID を取得するには、ID を作成するか、既にアクセスする必要があります。 このガイドの手順は、取引明細を作成するために必要な一般的な操作順序に従います。

ベスト プラクティス

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

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

セットアップ手順

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

• 手順 1 - 承認トークンを取得する
• 手順 2 - 広告主を作成またはアクセスする
• 手順 3 - 挿入順序を作成またはアクセスする
• 手順 4 - 取引を作成する
• 手順 5 - 取引明細プロファイルを作成する
• 手順 6 - 取引明細を作成する

認証

手順 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 - 広告主を作成またはアクセスする

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

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

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

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

   $ cat advertiser.json
   {
       "advertiser": {
           "name": "Deal Line Item Example Advertiser",
           "timezone": "US/Pacific"
       }
   }
   

2. この広告主の JSON と適切なmember_idを使用して、https://api.appnexus.com/advertiser endpointにPOST要求を行います。

   $ curl -b cookies -c cookies -X POST -d @advertiser.json 'https://api.appnexus.com/advertiser?member_id=2378'
   

3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

4. 応答本文の広告主 ID をメモして、手順 6 - 取引の広告申込情報を作成するで取引明細を作成するときに使用できるようにします。

挿入順序

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

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

シームレスな挿入順序の JSON フィールド (必須および便利な省略可能なフィールド)

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

1. 挿入順序 JSON を作成します (次の 2 つの例を示します)。

   JSON の例: 終了日なし、予算なし

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "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 の例: フライト、インプレッションの予算

   $ cat insertion-order-flights.json
   {
       "insertion-order": {
           "name": "Deal Line Item Example IO",
           "budget_intervals": [
   
               {
                   "start_date": "2019-10-10 00:00:00",
                   "end_date": "2019-10-12 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 980,
                   "lifetime_pacing": false
               },
               {
                   "start_date": "2019-10-13 00:00:00",
                   "end_date": "2019-10-18 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 100,
                   "lifetime_pacing": false
               }
           "budget_type": "impression"
           ]
       }
   }
   

2. この挿入順序 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.appnexus.com/insertion-order?advertiser_id=2605036&member_id=2378'
   

   要求の例: フライト、インプレッションの予算

   $ curl -b cookies -c cookies -X POST -d @insertion-order-flights.json 'https://api.appnexus.com/insertion-order?advertiser_id=2605036&member_id=2378'
   

3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

4. 手順 6 - 取引明細を作成するで取引明細を作成するときに使用できるように、応答本文の挿入順序 ID をメモします。

対処する

手順 4 - 取引を作成する

取引明細に関連付ける取引を作成する必要があります。

取引の JSON フィールド

便利な省略可能な JSON フィールド

許可されたクリエイティブの JSON フィールド

ブランド ( 「ブランド サービス」を参照)

ブランドの例

"brand_restrict": true,
            "brands": [
                {
                    "id": 2,
                    "name": "1800Flowers",
                    "override": true
                },
                {
                    "id": 4,
                    "name": "Acura",
                    "override": false
                }
            ] 

言語 ( 言語サービスを参照)

言語の例

"language_restrict": true,
            "languages": [
                {
                    "id": 1,
                    "name": "English",
                    "override": false
                },
                {
                    "id": 2,
                    "name": "Chinese",
                    "override": true
                }
            ]

信頼レベル

信頼レベルの例

"audit_status_option": "max_trust" 

クリエイティブ カテゴリ

クリエイティブ カテゴリの例

"categories": [
                 {
                     "id": 1,
                     "name": "Airlines",
                     "override": false
                 },
                 {
                     "id": 2,
                     "name": "Apparel",
                     "override": true
                 }
             ],
             "category_restrict": true

特定のクリエイティブ

特定のクリエイティブの例

"creatives": [
                {
                    "id": 161501729,
                    "status": "banned"
                },
                {
                    "id": 161501882,
                    "status": "approved"
                }
            ]

メディアの種類 ( メディア サブタイプ サービス と メディア タイプ サービスを参照)

メディアの種類の例

"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"
                 }
             ]

技術属性 ( 技術属性サービスを参照)

技術属性の例

"technical_attribute_restrict": false,
             "technical_attributes": [
                 {
                     "id": 1,
                     "name": "Image",
                     "override": true
                 }
             ]

取引データ保護用の JSON フィールド ( 可視性プロファイル サービスを参照)

ユーザー ID とデバイス ID

ユーザー ID とデバイス ID の保護の例

手順 1: 可視性プロファイルを作成する

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_device_id_default": false,
        "expose_user_id_default": false,
        "name": "Deal Visibility Profile"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

手順 2: 可視性プロファイルを取引に関連付け、データ保護を有効にする

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

IP アドレス

IP アドレスの保護の例

手順 1: 可視性プロファイルを作成する

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_ip_default": false,
        "ip_exposure_default": "truncated",
        "name": "Deal Visibility Profile - Hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

手順 2: 可視性プロファイルを取引に関連付け、データ保護を有効にする

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

URL

ドメインの保護の例

手順 1: 可視性プロファイルを作成する

> cat visibility_profile.json
{
    "visibility-profile": {
        "name": "Deal Visibility Profile - Hidden",
        "url_exposure_default": "hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

手順 2: 可視性プロファイルを取引に関連付け、データ保護を有効にする

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

セグメントに追加する ( 取引サービスを参照)

クリックまたはビューの例でセグメントへの追加を禁止する

> cat add_segment.json
{
    "deal": {
        "allow_creative_add_on_click": false,
        "allow_creative_add_on_view": false
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @add_segment.json 'https://api.appnexus.com/deal?id=123456'

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

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

   $ cat deal.json
   {
       "deal": {
           "name": "Deal Line Item Example Deal",
           "buyer": {
               "id": 2379
           },
           "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 をメモします。

プロファイル

手順 5 - 取引明細プロファイルを作成する

次に、取引明細のターゲティングで使用する取引明細プロファイルを作成します。 後で使用するために、このプロファイルの ID を必ず書き留めておいてください。 詳細については、「 プロファイル サービス 」を参照してください。

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

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

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

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"
               }
           ],
           "max_day_imps": 10,
           "min_minutes_per_imp": 300
       }
   }
   

   例: ターゲットを設定せずにプロファイルを作成する

   > 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 をメモします。

行項目

手順 6 - 取引明細を作成する

最後に、取引 ID と、手順 5 - 取引明細プロファイルの作成で作成した取引明細プロファイルを関連付けるために 、取引明細を作成する必要があります。

取引明細の JSON フィールド

便利な省略可能な JSON フィールド

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

1. 取引広告申込情報 JSON を作成します (既存の広告主 ID、挿入注文 ID、取引 ID、プロファイル ID が必要です)。

   JSON の例: 予算を含めずにアイテムを処理する

   > cat 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
           },
           "bid_object_type": "deal",
           "budget_intervals": [{
               "start_date": "2019-10-11 12:00:00"
           }],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   JSON の例: 広告申込情報の有効期間のインプレッション予算を処理する

   > cat deal_line_item_lifetime.json
   {
       "line-item": {
           "ad_types": ["video"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [
                   {
                       "end_date": "2019-10-18 23:59:59",
                       "lifetime_budget_imps": 2586,
                       "start_date": "2019-10-11 12:00:00",
                       "timezone": "US/Pacific"
                   },
                   {
                       "end_date": "2019-10-25 23:59:59",
                       "lifetime_budget_imps": 2414,
                       "start_date": "2019-10-19 00:00:00",
                       "timezone": "US/Pacific"
                   }
               ],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   JSON の例: 取引明細の 1 日あたりの収益予算

   > cat 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
           },
           "bid_object_type": "deal",
           "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_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

2. この取引行項目 JSON と適切なadvertiser_idとmember_idを使用して、https://api.appnexus.com/line-item エンドポイントにPOST要求を行います。

     要求の例: 予算を含めずに明細を処理する

   > curl -b cookies -c cookies -X POST -d @deal_line_item.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

     要求の例: 広告申込情報の有効期間のインプレッション予算を処理する

   > curl -b cookies -c cookies -X POST -d @deal_line_item_lifetime.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

     要求の例: 取引明細の日次収益予算

   > curl -b cookies -c cookies -X POST -d @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) を変更したりすることができます。

関連項目

• API の概要
• API のベスト プラクティス
• API セマンティクス
• Deal Service
• 明細サービス (ALI)
• Profile Service