Yield Analytics API

概要

Yield Analytics API とサービスは、REST ベースのインターフェイスを介して公開されます。 Web 2.0、AJAX、REST、およびサービス指向の開発プラットフォームで経験した開発者がカスタム機能の開発を快適にすることを目的としています。 開発者は、Yield Analytics API とサービスを使用して開発を試みる前に、AJAX、XML、JSON、HTTP(S) プロトコルなどの Web ベースのアプリケーション パラダイムに精通している必要があります。

コンテンツ タイプ

Yield Analytics REST API には、現在、次の 2 つの応答 MIME コンテンツ タイプを使用してアクセスできます。

• XML - using Content-type: application/xml
• JSON - using Content-type: application/json

目的のコンテンツ タイプを選択することは、API 開発者がケースバイケースで行う必要がある選択です。 API 機能は、コンテンツ タイプ間で対称的です。 API 開発者は、HTTP GET または POST メソッド パラメーターで、または AJAX または HTTP クライアント ライブラリを使用して、目的のコンテンツ タイプを指定できます。

エラー チェックと状態コード

API 開発者は、サービス REST API から返される HTTP 応答コードをチェックして、API 呼び出しから伝達されたエラーを検出する必要があります。 サービスの呼び出しが成功すると、200 個の範囲応答コードが生成されます。 400 および 500 の範囲の http 応答はエラーを示します。 特定の応答コードとテキストは、API の BETA 開発中に変更される可能性がありますが、範囲は変更されません。

セキュリティ

サービス API は、セキュリティで保護された方法でアプリケーション データを公開します。 API 機能の使用は、認証されたユーザーに制限され、セキュリティで保護されたトランスポート プロトコル経由で公開されます。 API へのアクセスは、次のコンテキスト内で行う必要があります。

• cURL認証の例

  認証は、各要求で http ヘッダーを介して資格情報を渡すことによって行われます。

  - username: curl -H "username:username"
  - password: curl -H "password:password"
  - source: curl -H "source:client_id"        
  

• HTTPS 認証の例

  GET /api/v1/rest/
  HTTPS/1.1
  Host: yieldanalytics.xandr.com
  Accept: application/xml, application/json
  Content-Type: application/json
  username: {{username}}
  password: {{password}}
  source: {{client_id}}        
  

• POSTMAN 認証の例

  Postman のヘッダー設定の例を次に示します。

  注:

  • 'Authorization' が "No Auth" に設定されています。次の設定は、[ヘッダー] タブに配置します。
  • Postman の使用に関する詳細なチュートリアルについては、「 Yield Analytics API での Postman の使用」を参照してください。

  

機密性

機密性は、Secure Socket Layer ベースの通信を使用して Yield Analytics API と対話することで維持されます。 API 開発者は、可能な限り HTTP セキュリティで保護されていない通信よりも HTTPS の使用を好む必要があります。 Web ブラウザー コンテキストの外部で開発するときに、SSL 経由で HTTP を有効にする方法については、HTTP クライアント ライブラリを参照してください。

API サービス

• 属性サービス
• 製品および在庫サービス
• 挿入注文サービス
• 注文明細行サービス
• クエリ エンジン サービス
• 一括製品作成サービス
• Data Service

データ フィルター処理

Alias 関数

従量課金フィルター処理

従量課金フィルターをパス変数または要求オブジェクトとして受け入れる API 呼び出しの場合、可用性の計算をさらに制御できます。 可用性 = 容量 - 消費。 可用性要求に従量課金フィルターを追加すると、可用性を提供するために容量から消費を減算する消費が制御されます。 消費フィルターに一致するすべての注文明細行は、可用性を計算するときに、その消費を容量から減算します。

• 上のCONSUMPTION_TYPEと同じキーと = (EQUAL) 演算子を使用して複数のキーと値のペアが指定されている場合、値は OR ルールを使用して結合されます。 たとえば、CONSUMPTION_TYPEは DIRECT または CONTAINED のいずれかです

• 同じキーと != (NOT_EQUAL) 演算子 (例: EXTERNAL_ID!=223415を使用して複数のキーと値のペアが指定されている場合。EXTERNAL_ID!=223416)、値は AND ルールを使用して結合されます。

• 異なる演算子 (PRIORITY>=5 など) で複数のキーと値のペアが指定されている場合。PRIORITY<=10)、値は AND ルールを使用して結合されます。

• 異なるファンクション キーを持つペアは、AND ルールを使用して結合されます。

特定の Analytics インストールで使用可能なすべての関数キー値 (顧客によって異なる場合があります) を確認するには、REST クエリをクエリ エンジンに送信すると、すべての関数キーの一覧が返されます。 関数キーを一覧表示する REST クエリの形式を次に示します。

データ モデル

キー オブジェクト

順序

注文は広告申込情報のコンテナーであり、注文管理システム (OMS) または広告サーバーで直接作成された後、処理中に注文のインポート手順中に毎晩 Yield Analytics に取り込まれます。 オンライン広告業界の直接販売された保証された部分の注文は、特定の用語を組み込んだ相互に合意された挿入注文を指し、パブリッシャーは代理店または広告主の利益のためにサイトに広告(注文明細行)を配信します。

Yield Analytics で注文を参照する場合は、注文明細行または注文明細行のグループに関連付けられている注文の名前を参照します。

注文明細

注文明細行は、特定のフライト日のセットとクリエイティブが関連付けられている広告または配置であり、挿入注文の一部として購入されます。 広告申込情報とも呼ばれることもありますが、これらの注文明細行には、CPM (レート) などの配信契約契約や、ターゲット設定や予定インプレッション数などの広告配信契約を記述するのに役立つメタデータが関連付けられます。

製品

製品は、パブリッシャーが実際に広告主に販売するものと考えてください。 すべての製品は一意の名前を持ち、ターゲットへのポインターと考えることができます。 しかし、注意してください! 製品とターゲットを混同する傾向があります。 複数の製品をターゲットに関連付けることができるので、これは誤った問題です。 ターゲットに関連付けられるだけでなく、製品には名前などの追加のメタデータが添付され、場合によってはレートと製品グループが関連付けられます。 繰り返しになります。ターゲットは一意です。多くの製品が 1 つのターゲットに関連付けられている可能性があります。

製品はクライアントによって非アクティブ化できますが、削除することはできません。 ターゲットに関連付けられているアクティブな製品がない場合、Yield Analytics はターゲットに対して処理を行いませんが、その履歴は保持されます。

Yield Analytics には、次の 4 種類の製品があります。

• レート表 - 発行元の販売チームが販売するカタログ内の製品を表します

• レポート - Yield Analytics で分析するインベントリ。 これは、クライアントが最も制御できる製品のクラスであり、履歴データの蓄積に使用される製品のクラスであるため、最も重要な種類の製品です。 履歴データの基礎となるこの最後の部分は、多くの場合、最終的にデータを収集する必要があるすべての製品を考慮する必要があるため、実装中にクライアントが把握するのが最も難しい概念の 1 つです。 予測は、製品を報告せずに実行できますが、履歴レポート (予想どおり) はできません。

• カスタム - 注文明細行に対応する製品。 Yield Analytics は、注文明細行をインポートするたびに、注文明細行の有効期間中にのみ存在するカスタム注文明細行製品を作成します。 これらの製品は、Yield Analytics によって完全に管理されます (作成、管理、非アクティブ化)。 多くの場合、クライアントが製品のクリーンを行いたい場合は、カスタム製品を削除しようと試み、サービス チームによって再教育する必要があります。

• 季節性 - 特定の季節モデルの影響を受ける在庫を定義するために使用します。 Yield Analytics を使用すると、パブリッシャーのインプレッション数に季節的なビジネス変動が既知である場合に、季節モデルを在庫領域に適用できます (たとえば、ESPN のようなスポーツパブリッシャーは、1 月下旬にスーパーボウルに対応する年に 1 回急増する可能性があります)。

Target

ターゲットは、属性値ペアの組み合わせによって記述されたインベントリの一意のプールを表します。これは、インベントリ プールを一意に識別します。 この一意の説明的な組み合わせは、ターゲット式と言います。 ターゲットは、任意のレベルの粒度 ('スポーツ'、'エンターテイメント'、'300x250'、'シカゴ' など) で定義できます。 "スポーツ" と "エンターテイメント" は、パブリッシャーの Web サイトのセクション、またはバックエンドのインベントリを分類するために使用されるタグ (広告販売の場合) に対応している可能性があります。 '300x250' は広告タグのサイズに対応します。 "シカゴ" は、ユーザーの IP アドレスを参照する可能性があります。

上記のターゲットを使用して、ターゲット式の例を次に示します。

• adunit in ('sports')

上記のターゲット式では、"adunit" がターゲット属性であり、"sports" が属性値です。

より複雑なターゲット式は次のようになります。

• adunit in ('sports', 'entertainment') と size in ('300x250') or placement in ('business') and size in ('300x250','300x600','1x1') と pos in ('top')

重要な用語

Allocation

Yield Analytics が広告サーバー ロジックをエミュレートして、予測日付範囲の各日の個々の製品に対して個々の注文明細行がどのように消費されるかを予測するプロセス。

• このプロセスでは、同じ在庫に対して競合する複数の注文明細行が考慮されます

• このプロセスでは、製品間の重複が考慮されます。 1 つの注文明細行が、1 つのインプレッションで一度に多くの製品に対して消費される場合があります。 オーダラインのターゲットと製品の目標との関係によっては、製品に対するオーダラインの消費タイプが間接、直接、または包含である場合があります (以下を参照)。

割り当てプロセス

• 特定の日に、特定のレベル (優先順位セット) に対して、注文明細行のセットがインプレッションの一部を要求します

• 部分は、フライティング、注文明細行の目標 (目標ベースの場合)、音声の共有 (CPD 回線の場合) によって定義されます

• インプレッションの量は、使用可能なものによって制限されます

• 注文明細行を処理すると、可用性が低下します

• 重複するターゲットから消費が取得されるため、可用性はターゲットに対してさらに減少します

• Yield Analytics の目標は、これらの合計とそれらの間のリレーションシップを維持することです (反復プロセス)

リスクの高いメトリック

Yield Analytics では、割り当て結果を使用して、配信不足のリスクが保証されている注文明細行を広告運用で理解し、適切な介入を行うことができるように、リスクの高いメトリックをいくつか生成します。

指標	式	説明
ペーシング	消費インプレッション – スケジュールされたインプレッション	出荷中または超過配送中の注文明細行のリスクの測定値。 このメトリックには、配信不足と過剰配信の両方が含まれており、両方を測定するために使用する必要があります。
ペーシング (有効期間)	消費インプレッション – スケジュールされたインプレッション	これはペーシング メトリックと同じですが、このメトリックは注文明細行の有効期間にわたって集計され、期間によってバインドされないことを除きます。 有効期間メトリックを使用する場合、期間フィルターは、選択した期間に配信される注文明細行にフィルター処理するためにのみ使用されます。
従量課金制 %	(使用済みイベント/スケジュールされたイベント) x 100	スケジュールごとのペースの測定値。 将来の期間、この数値では、配分予測に基づいて予想される消費量が考慮されます。 価格タイプ CPM、CPD、および CPC を含む保証注文明細行は、この計算の対象となります。 C:S% はイベントに依存しません。つまり、インプレッションとクリックは、注文明細行の価格の種類によって同じ意味で使用されます。
従量課金制の % (有効期間)	(使用済みイベント/スケジュールされたイベント) x 100	これは従量課金制の % メトリックと同じですが、このメトリックは、すべての注文明細行の有効期間にわたって集計され、期間によってバインドされないことを除きます。 有効期間メトリックを使用する場合、期間フィルターは、選択した期間に配信される注文明細行にフィルター処理するためにのみ使用されます。
目標に対する収益	獲得収益 - 契約収益	不足のリスクがある収益の測定値。 このメトリックには、不足分と超過分の両方が含まれており、両方を測定するために使用する必要があります。
目標に対する収益 (有効期間)	獲得収益 - 契約収益	これは目標に対する収益メトリックと同じですが、このメトリックは、すべての注文明細行の有効期間にわたって集計され、期間に制約されないことを除きます。 有効期間メトリックを使用する場合、期間フィルターは、選択した期間に配信される注文明細行にフィルター処理するためにのみ使用されます。

Availability

容量 – (保証) 消費

• 製品の容量は、保証された注文明細行とプリエンプティブ注文明細行の組み合わせによって完全に消費される場合があります。 プリエンプティブ注文明細行による消費は使用可能と見なされます。

• パブリッシャーの目標は、通常、保証された (直接販売された) 注文明細行でプリエンプティブな消費を "売り越す" ことで、これらの明細行は通常、レートが高く、他の保証された需要を危険にさらしていないためです。

キャパシティ

特定の製品で配信できるインプレッションの最大数。

消費

過去に配信された、または将来配信される予測されるインプレッションの数。

従量課金の種類

これにより、Yield Analytics は、特定の注文明細行が特定の製品に対してどのように消費されているかを分類する方法であり、注文明細行のターゲットと製品のターゲットの間の関係の関数です。

• 直接: 注文明細行と製品が同じターゲットを共有する

• 含まれている: 注文明細行は、製品内で配信する必要があります。 注文明細行のターゲットは、製品のターゲットの子です。

• 間接: 注文明細行は、製品の内外で配信できます。 注文明細行のターゲットは、製品のターゲットの親または兄弟です。

フライティング方法

注文明細行の日付範囲に対するインプレッションの分布の理想的な形状を示します (ペーシングとも呼ばれます)。

一般的なフライティング方法は次のとおりです。

• 均等

• フロントロード

• できるだけ早く

インベントリ クラス

Yield Analytics のすべての注文明細行の属性。注文明細行のコントラクト型から派生します。 インベントリ クラスの値は 3 つあります。

インベントリ クラス	説明
保証	パブリッシャーは、広告主に対して、目標ベースの行に対して特定の量のインプレッションを配信するか、1 日あたりのコストラインに対して特定の音声共有 (SOV) を配信することを保証しています。 SOV とは、特定の製品の特定の注文ラインが消費するインプレッションの割合を指します。 - APAS コントラクトの種類: 保証された排他的、保証された標準 - DFP コントラクトの種類: スポンサー、Standard - OAS コントラクトの種類: Dynamic、Dynamic Monthly、Exclusive、Fixed、Open
Preemptible	これらの注文明細行は、保証された注文明細行によって先取りできます。 - APAS コントラクトの種類: インプレッション数、割合 - DFP コントラクトの種類: AdMob、AdSense、Advertising Exchange、Bulk、Click Tracking、House、Network、Price Priority - OAS コントラクトの種類: House、および "Preemptible" という単語を含む任意のコントラクト型
Unspecified	Yield Analytics にインポートされていない注文明細行によって配信され、したがって "不明" である未入力のインプレッションとインプレッションに対応します。

優先度

容量を消費する最初の注文明細行を決定します (広告サーバーで設定)。

C:S %

スケジュールごとのペースの測定値。 将来の期間、この数値では、配分予測に基づいて予想される消費量が考慮されます。 価格タイプ CPM、CPD、および CPC を含む保証注文明細行は、この計算の対象となります。

ペーシング

出荷中または超過配送中の注文明細行のリスクの測定値。 このメトリックには、配信中と超過配信の両方が含まれており、両方を測定するために使用する必要があります。

ピボット属性

ピボット属性を使用すると、同じターゲット属性に対して異なる値を 1 つのターゲット式にまとめることができます。 Yield Analytics のターゲット設定では、同じ属性に属する 2 つの値間で AND ロジックを使用することはできません。 これは問題です。これは意味のある場合があるためです。 たとえば、キーワード (keyword)'バスケットボール' と '野球' の両方をターゲットにするターゲット設定です。 たとえば、目的の式が次の場合です。

• kw in ('basketball') と kw in ('baseball')

許可されず、ピボットを使用する必要があります。 ピボットを使用すると、元の属性と値を連結した新しい属性を作成することで、1 つの式の両方をターゲットにできます。 例:

• ('true') でkw_basketballし、('true') にkw_baseballします

ピボットされた属性は除外することもできます。 たとえば、DFP で adunit 1 があるとします。これには、adunit 2_a、adunit 2_b、adunit 2_cが含まれます。 adunit 2_b以外のすべてをターゲットにする場合は、次の式を使用します。

• adunit in ('adunit 1') と adunit exclude !in ('adunit 2_b')

DFP には adunit_only という属性もあります。これにより、指定された adunit のみを選択でき、その子は選択できません。 ただし、これはすべての広告サーバーに共通するわけではありませんので、上記の式の構文を利用できます。

ゾンビ注文ライン

過去の開始日を含む保留中の状態の注文明細行。 注文明細行は実際には配信されませんが、Yield Analytics は保留中の状態であるため、将来割り当てます。 保留中で開始日を過ぎた注文明細行は、状態が変更されていないと仮定して、Yield Analytics で在庫を予約するため、"ゾンビ" 注文明細行と呼ばれます。

関連項目

• 属性サービス
• 製品および在庫サービス
• 挿入注文サービス
• 注文明細行サービス
• クエリ エンジン サービス
• 一括製品作成サービス
• Data Service