どのようなときに使うか設定フィールドリクエストの処理方法レスポンスフィールド解析済み広告とフック出力の統合方法失敗動作例: セカンダリ広告サーバーから広告を取得する

VAST リクエスト

どのようなときに使うか

VAST_REQUEST 関数が Video Ad Serving Template (VAST) エンドポイントから広告を取得する必要がある場合に使用します。MediaTailor はリクエストを送信し、ラッパーリダイレクトが解決された VAST としてレスポンスを解析し、解析された広告を出力式で使用できるようにします。一般的なユースケースには、短いプライマリレスポンスを補完するためのセカンダリ広告サーバーからの広告の取得、不足している広告時間枠に挿入するための住宅広告またはプロモーションの取得などがあります。

VAST_REQUEST 関数は、 POST_ADS_RESPONSEおよび PRE_MANIFEST_INSERTIONライフサイクルフックで、単独で、またはエグゼキュター内のステップとしてサポートされます。VAST_REQUEST 関数によって解析された広告は、完全な忠実度でそれらのフックの出力と統合されます。詳細については、「解析済み広告とフック出力の統合方法」を参照してください。

設定フィールド

VAST_REQUEST 関数には次のフィールドがあります。

ランタイム — 式言語。これをに設定しますJSONATA。
MethodType — HTTP メソッド。サポートされている値は GET (デフォルト) とですPOST。
URL — リクエストを送信する VAST エンドポイント。静的 URL または URL を動的に構築する JSONata 式を使用できます。静的 URL は httpsスキームを使用する必要があります。
ヘッダー — リクエストに含める HTTP ヘッダー。ヘッダー名と値のペアとして指定されます。動的ヘッダー値には{%...%}式構文を使用します。
本文 — 送信するリクエスト本文。OpenRTB 入札POSTリクエストを送信するなど、リクエストで使用されます。JSONata 式を使用して、本文を動的に構築できます。
RequestTimeoutMilliseconds (必須) — レスポンスを待機する時間。
出力 — 呼び出しの完了後に生成する値を定義します。各エントリは、出力キーを、を含む response オブジェクトを参照できる式にマッピングしますresponse.parsedAds。

HTTP_REQUEST 関数に適用される HTTP リクエストの制限もここで適用されます。詳細については、「制限」を参照してください。

リクエストの処理方法

リクエストを構築する — MediaTailor はHeaders、Url、、および Body式を現在のセッション状態と照らし合わせて評価し、リクエストを送信します。 POST リクエストは application/jsonコンテンツタイプで送信されます。
レスポンスの解析 — MediaTailor はレスポンス本文を VAST として解析します。広告が VAST ラッパーの場合、MediaTailor はリダイレクトチェーンに従い、最終的なインライン広告に解決します。VAST 仕様で必要とされるようにGET、ラッパーリダイレクトリクエストは常にで送信されます。エンドポイントが VAST 自体ではなく VAST URL を含むドキュメントを返す場合 (一部の入札者と同様）、URL を取得するHTTP_REQUESTステップをチェーンし、その後に URL を取得するVAST_REQUESTステップをチェーンします。
解析された広告の処理 — MediaTailor は出力ブロック内の式を評価します。これらの式は、元のセッション状態と response オブジェクトを参照できます。

レスポンスフィールド

呼び出しが完了したら、出力式で次のフィールドを参照できます。

フィールド	タイプ	説明
`response.parsedAds`	配列	ラッパーリダイレクトが解決された解析済み広告。各広告の形状は、`POST_ADS_RESPONSE`フックの`adsResponse.ads`エントリと同じです: `adId`、`durationSeconds`、、`adSystem`、`adTitle`、`creativeIdsequencemediaFiles`、、および `trackingEvents`。呼び出しが失敗するか、レスポンスが有効な VAST でない場合、空の配列に設定します。
`response.statusCode`	整数	エンドポイントによって返される HTTP ステータスコード。ネットワーク障害`null`時にをに設定します。

解析された広告はと同じシェイプを使用するためadsResponse.ads、フィールド参照を書き換えることなく 2 つの表面間で式を移動できます。

解析済み広告とフック出力の統合方法

VAST_REQUEST 関数が解析するすべての広告は、フック呼び出しの期間中、広告の VAST 広告 ID によってキー指定された MediaTailor によって内部的に保持されます。これにより、解析された広告がフック出力でファーストクラス処理されます。

でPOST_ADS_RESPONSE、解析された広告をそのadsResponse.ads広告によってに追加すると、完全なメディアファイルリストや追跡イベントなど、広告の完全な解析された VAST データがadId復元されます。
でPRE_MANIFEST_INSERTION、のみを使用して広告を挿入vastAdIdすると、MediaTailor は最適なメディアファイルを選択し、トランスコード登録を自動的に処理できます。

重要

保持された広告は、フック呼び出し間で引き継がれません。で行われたVAST_REQUEST呼び出しPOST_ADS_RESPONSEは、後のPRE_MANIFEST_INSERTION呼び出しでは利用できません。結果を使用するのと同じフックの関数チェーンVAST_REQUESTでを呼び出します。

失敗動作

ネットワークエラーまたはタイムアウトが原因で呼び出しが失敗した場合、エンドポイントが HTTP エラーを返した場合、またはレスポンスを VAST として解析できない場合、 response.parsedAdsは空の配列であり、関数チェーンは続行されます。HTTP 障害と、実際に広告が含まれていない VAST レスポンスを区別response.statusCodeするには、をチェックします。

ヒント

RequestTimeoutMilliseconds きつく保ちます。VAST ラッパー解決には複数のネットワークラウンドトリップが含まれる場合があり、それらはすべてフックのタイムアウトと共有フックの予算にカウントされます。

例: セカンダリ広告サーバーから広告を取得する

次の関数は、バックアップ広告サーバーから広告を取得し、解析された広告を一時データに保存します。同じシーケンスの後のCUSTOM_OUTPUTステップでは、それらをに追加できますadsResponse.ads。POST_ADS_RESPONSE ライフサイクルフック用に設計されています。


{
    "FunctionId": "fetchBackupAds",
    "FunctionType": "VAST_REQUEST",
    "VastRequestConfiguration": {
        "Runtime": "JSONATA",
        "MethodType": "GET",
        "Url": "{%'https://backup-ads.example.com/vast?sid=' & session.uuid%}",
        "Headers": {
            "Accept": "application/xml"
        },
        "RequestTimeoutMilliseconds": 1000,
        "Output": {
            "temp.backupAds": "{%response.parsedAds%}"
        }
    }
}

代わりに OpenRTB 入札リクエストを送信するには、 MethodType をに設定POSTし、で入札リクエストを指定しますBody。入札者はレスポンス本文で VAST を返す必要があります。

同様の例の完全なチュートリアルについては、「」を参照してください関数の例。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

HTTP リクエスト

シーケンシャルエグゼキュター