MediaTailor パラメータリファレンス MediaTailor 設定エイリアス MediaTailor が ADS パラメータを渡す MediaTailor のトラブルシューティングエイリアス

MediaTailor 動的広告変数

AWS Elemental MediaTailor 広告決定サーバー (ADS) へのリクエストには、現在の表示セッションに関する情報が含まれます。この情報は、ADS がレスポンスで提供する最適な広告を選択するのに役立ちます。MediaTailor 設定で ADS テンプレートを設定するときは、マクロとしても知られる動的変数を含めることができます。動的変数は置き換え可能な文字列です。

動的変数は、以下の形態にすることができます。

静的値 - セッション間で変更されない値。例えば、MediaTailor が ADS に期待するレスポンスタイプなどです。
ドメイン変数 - URL ドメインに使用できる動的変数。http://my-ads-server.com という URL の my-ads-server.com 部分などです。詳細については、「MediaTailor ドメイン変数」を参照してください。
セッションデータ - セッションごとに MediaTailor から提供される動的値。例えば、セッション ID などです。詳細については、「MediaTailor セッション変数」を参照してください。
プレイヤーデータ - セッションごとにプレイヤーから提供される動的値。コンテンツ視聴者について説明するデータで、MediaTailor がストリームにステッチする必要がある広告を ADS が判断するために役立ちます。詳細については、「MediaTailor プレイヤー変数」を参照してください。

MediaTailor パラメータのリファレンスと制限事項

AWS Elemental MediaTailor は、マニフェストクエリパラメータと ADS パラメータの両方について、パラメータ文字の制限、長さの制限、サポートされている形式に関する包括的な情報を提供します。

マニフェストクエリパラメータの文字制限

マニフェストクエリパラメータは特定の文字をサポートし、長さの制限が定義されています。

サポートされている文字 (URL エンコードなし）

マニフェストクエリパラメータでは、次の文字を直接使用できます。

英数字 (A～Z、a～z、0～9)
期間 (.)
ハイフン (-)
アンダースコア (_)
バックスラッシュ (\)

URL エンコードでサポートされている文字

URL エンコードでは、次の特殊文字がサポートされています。

期間 (.) = %2E
ダッシュ (-) = %2D
アンダースコア (_) = %5F
パーセント (%) = %25
チルダ (~) = %7E
スラッシュ (/) = %2F
アスタリスク (*) = %2A
等号 (=) = %3D
質問 (?) = %3F

URL エンコードのサポート

MediaTailor は、URL エンコード (hello%20world = hello world など) で使用すると、パーセント (%) 記号をサポートします。HTTP 仕様に従って有効な URL エンコードである限り、任意の URL エンコード文字を使用できます。

サポートされていない文字

URL エンコードを使用しないマニフェストクエリパラメータで次の文字を使用することはできません: :、?、&、=%、、 / (スラッシュ）。

重要

MediaTailor は、%%% や == などの二重文字をサポートしていません。文字制限のため、マニフェストクエリパラメータ値として完全な URLs を使用することはできません。

長さの制限

すべてのマニフェストクエリパラメータ (キーと値の組み合わせ) の合計長は 2000 文字を超えることはできません。

ADS パラメータの長さの制限

ADS へのリクエストで使用されるパラメータには、次の長さ制限が適用されます。

ADS パラメータ名: 最大 10,000 文字
ADS パラメータ値: 最大 25,000 文字
ADS URL: 最大 25,000 文字

MediaTailor 設定エイリアスと動的変数置換

AWS Elemental MediaTailor 設定エイリアスは、URL ドメインやその他のサポートされているフィールドで動的変数置換を有効にします。この機能を使用して、複数のドメインを使用し、セッションの初期化中に URLs動的に設定します。

動的変数置換でサポートされているフィールド

動的変数は、次の設定フィールドで使用できます。

VideoContentSourceUrl
AdDecisionServerUrl
LivePreroll.AdDecisionServerUrl
AdSegmentUrlPrefix
ContentSegmentUrlPrefix
TranscodeProfileName
SlateAdUrl
StartUrl
EndUrl

ドメインレベルのパラメータルール

URLs のドメイン部分で動的変数を使用する場合、次の制限が適用されます。

ドメインで使用されるすべての動的変数は、として指定する必要があります。 ConfigurationAliases
はのみです player_params
エイリアス化された値のリストは網羅的である必要があります
エイリアスが無効または欠落している場合、HTTP 400 エラーが発生します。

ConfigurationAliases API パラメータ構造

ConfigurationAliases パラメータは、次の JSON 構造を使用します。


{
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc.mediapackage.us-west-2.amazonaws.com",
            "iad": "xyz.mediapackage.us-east-1.amazonaws.com"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        }
    }
}

API の整合性

playerParams は、API の一貫性を向上させるadsParamsために、 adsおよびの代替としてサポートされるようになりました。

欠落しているエイリアスのフォールバック動作

設定エイリアスが見つからないか無効である場合、MediaTailor は次のフォールバック動作を実装します。

ドメイン変数： ドメイン変数エイリアスがないか無効の場合、リクエストは HTTP 400 ステータスコードで失敗します。すべてのドメイン変数には、有効なエイリアスが定義されている必要があります。
非ドメイン変数： URLs の非ドメイン部分 (パス要素やクエリパラメータなど) で使用される変数の場合、エイリアスがないと空の文字列置換になります。
設定の検証： MediaTailor は、設定の作成および更新オペレーション中に、必要なエイリアスがすべて存在することを確認します。

高度なマルチ設定のユースケース

設定エイリアスは、以下のシナリオで高度なマルチ設定アーキテクチャを有効にします。

地理的ルーティング： リージョン固有のエイリアスを使用して、ビューワーの場所に基づいて異なるオリジンまたは広告サーバーにリクエストをルーティングします。実装ガイダンスについては、CloudFront オリジンフェイルオーバー」を参照してください。
コンテンツベースのルーティング： さまざまなコンテンツタイプを特殊なオリジンまたは処理パイプラインに向けます。ルーティング動作の設定については、「」を参照してくださいMediaTailor の CDN ルーティング動作を設定する。
フェイルオーバーシナリオ： エイリアス切り替えを使用して、自動フェイルオーバーでバックアップオリジンと広告サーバーを実装します。詳細な実装については、MQAR を使用して MediaTailor のマルチリージョンレジリエンスを実装する「」および「」を参照してくださいの CDN 統合を計画する AWS Elemental MediaTailor。
A/B テスト： プレイヤーパラメータに基づいてトラフィックをルーティングして、さまざまな広告サーバー、オリジン、または設定をテストします。負荷テストのガイダンスについては、「実際のユーザーモニタリングを使用した Amazon CloudFront のパフォーマンステストの準備と実行」を参照してください。
デバイス固有の最適化： さまざまなデバイスタイプや機能に合わせてコンテンツ配信と広告配信を最適化します。包括的なガイダンスについては、MediaTailor、MediaPackage、CDN でマニフェストフィルタリングを設定する「」を参照してください。
ロードバランシング： 動的ルーティングを使用して、複数のオリジンまたは広告サーバーに負荷を分散します。実装ガイダンスについては、MQAR を使用して MediaTailor のマルチリージョンレジリエンスを実装する「」および「」を参照してくださいの CDN 統合を計画する AWS Elemental MediaTailor。

例エイリアスを使用して設定を完了する

次の例は、設定エイリアスと動的ドメイン変数を含む完全な設定を示しています。


PUT /playbackConfiguration
{
    "Name": "aliasedConfig",
    "AdDecisionServerUrl": "https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=[player_params.ad_type]",
    "VideoContentSourceUrl": "https://[player_params.origin_domain].mediapackage.[player_params.region].amazonaws.com/out/v1/[player_params.endpoint_id]",
    
    "AdSegmentUrlPrefix": "https://[player_params.ad_cdn_domain]/ads/",
    "ContentSegmentUrlPrefix": "https://[player_params.content_cdn_domain]/content/",
    "TranscodeProfileName": "[player_params.transcode_profile]",
    "SlateAdUrl": "https://[player_params.slate_domain]/slate/[player_params.slate_type].mp4",
    "StartUrl": "https://[player_params.tracking_domain]/start?session=[session.id]",
    "EndUrl": "https://[player_params.tracking_domain]/end?session=[session.id]",
    
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc",
            "iad": "xyz"
        },
        "player_params.region": {
            "pdx": "us-west-2",
            "iad": "us-east-1"
        },
        "player_params.endpoint_id": {
            "pdx": "abcd",
            "iad": "wxyz"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        },
        "player_params.ad_cdn_domain": {
            "pdx": "ads-west.cdn.example.com",
            "iad": "ads-east.cdn.example.com"
        },
        "player_params.content_cdn_domain": {
            "pdx": "content-west.cdn.example.com",
            "iad": "content-east.cdn.example.com"
        },
        "player_params.transcode_profile": {
            "mobile": "mobile_optimized",
            "desktop": "high_quality",
            "tv": "4k_profile"
        },
        "player_params.slate_domain": {
            "pdx": "slate-west.example.com",
            "iad": "slate-east.example.com"
        },
        "player_params.slate_type": {
            "standard": "default_slate",
            "branded": "brand_slate"
        },
        "player_params.tracking_domain": {
            "pdx": "tracking-west.example.com",
            "iad": "tracking-east.example.com"
        }
    }
}

例エイリアスを使用したセッションの初期化

上記の設定を使用して、プレイヤー変数とエイリアスを指定するセッション初期化リクエストを作成します。


POST master.m3u8
{
    "playerParams": {
        "origin_domain": "pdx",
        "region": "pdx", 
        "endpoint_id": "pdx",
        "ad_type": "customized",
        "ad_cdn_domain": "pdx",
        "content_cdn_domain": "pdx",
        "transcode_profile": "mobile",
        "slate_domain": "pdx",
        "slate_type": "branded",
        "tracking_domain": "pdx"
    }
}

例パラメータ処理フロー

MediaTailor は、エイリアス文字列を設定エイリアスのマッピングされた値に置き換えます。処理の結果、次のリクエストが発生します。

ADS リクエスト：


https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345

VideoContentSource リクエスト：


https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd

AdSegmentUrlPrefix:
```
https://ads-west.cdn.example.com/ads/
```

ContentSegmentUrlPrefix:


https://content-west.cdn.example.com/content/

TranscodeProfileName:
```
mobile_optimized
```

SlateAdUrl:


https://slate-west.example.com/slate/brand_slate.mp4

StartUrl:


https://tracking-west.example.com/start?session=[session.id]

EndUrl:


https://tracking-west.example.com/end?session=[session.id]

MediaTailor が ADS にパラメータを渡す

AWS Elemental MediaTailor は、次の手順を使用して ADS への MediaTailor リクエストで動的変数の設定をサポートします。

クエリパラメータでサポートされているフォーマットについては、「」を参照してくださいMediaTailor パラメータのリファレンスと制限事項。
設定エイリアスとドメイン変数については、「」を参照してくださいMediaTailor 設定エイリアスと動的変数置換。
ADS リクエストのその他のカスタマイズについては、「」を参照してください高度な使用法。

セッションの初期化方法

MediaTailor は、セッションの初期化とパラメータの受け渡しに複数の方法をサポートしています。

リクエスト本文を含む POST:


POST <master>.m3u8
{
    "adsParams": {"param1": "value1", "param2": "value2"},
    "playerParams": {"param3": "value3"}
}

URL のクエリパラメータ：


GET <master>.m3u8?ads.param1=value1&ads.param2=value2&playerParams.param3=value3

重要

初期化時に指定できるパラメータは 1 回のみです。設定エイリアスは、転送前に実際の値に解決されます。

セッションとプレイヤーの情報を ADS に渡す

ADS と連携して、広告クエリに応答するために必要な情報を決定します AWS Elemental MediaTailor。
MediaTailor で、ADS 要件を満たすテンプレート ADS リクエスト URL を使用する設定を作成します。URL に、静的パラメータを含め、動的パラメータのプレースホルダーを含めます。設定の [Ad decision server (広告決定サーバー)] フィールドにテンプレートの URL を入力します。

以下のテンプレート URL の例では、correlation からセッションデータが渡され、deviceType からプレイヤーデータが渡されます。
```
https://my.ads.server.com/path?correlation=[session.id]&deviceType=[player_params.deviceType]
```
プレーヤーで、プレーヤーデータのパラメータを渡すように AWS Elemental MediaTailor のセッション開始リクエストを設定します。セッション開始リクエストにお客様のパラメータを含め、セッションに対する後続のリクエストからそれらのパラメータを省きます。

プレイヤーがセッションを開始するために行う呼び出しのタイプによって、プレイヤー (クライアント) または MediaTailor (サーバー) のどちらがセッションの広告追跡レポートを提供するかが決まります。これらの 2 つのオプションについては、「広告追跡データの報告」を参照してください。

サーバー側とクライアント側のどちらの広告追跡レポートが必要かどうかに応じて、以下のいずれかのタイプの呼び出しを行います。どちらの例の呼び出しでも、userID は ADS を対象とし、auth_token はオリジンを対象としています。
- (オプション) サーバー側の広告追跡レポートの呼び出し - MediaTailor が ADS に送信するパラメータの前に ads を付けます。MediaTailor がオリジンサーバーに送信するパラメータの前には何も付けません。
  
  次の例は、への HLS および DASH の受信リクエストを示しています AWS Elemental MediaTailor。MediaTailor は、ADS に対するリクエストでは deviceType、オリジンサーバーに対するリクエストでは auth_token を使用します。
  
  HLS の例:
```
GET master.m3u8?ads.deviceType=ipad&auth_token=kjhdsaf7gh
```
  DASH の例:
```
GET manifest.mpd?ads.deviceType=ipad&auth_token=kjhdsaf7gh
```
- (オプション) クライアント側の広告追跡レポートの呼び出し - adsParams オブジェクト内の ADS のパラメータを提供します。
  
  HLS の例:
```
POST master.m3u8
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }
```
  DASH の例:
```
POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }
```

プレイヤーがセッションを開始すると、はテンプレート ADS リクエスト URL の変数をセッションデータとプレイヤーのadsパラメータ AWS Elemental MediaTailor に置き換えます。プレイヤーからの残りのパラメータは、オリジンサーバーに渡されます。

例広告変数を使用した MediaTailor リクエスト

以下の例では、前のプレーヤーのセッション開始呼び出しの例に対応する、 AWS Elemental MediaTailor から ADS とオリジンサーバーへの呼び出しを示しています。

MediaTailor は、セッションデータとプレイヤーのデバイスタイプを使用して ADS を呼び出します。
```
https://my.ads.server.com/path?correlation=896976764&deviceType=ipad
```
MediaTailor は、プレイヤーの認可トークンを使用してオリジンサーバーを呼び出します。
- HLS の例:
```
https://my.origin.server.com/master.m3u8?auth_token=kjhdsaf7gh
```
- DASH の例:
```
https://my.origin.server.com/manifest.mpd?auth_token=kjhdsaf7gh
```

高度な使用法

プレイヤーとセッションのデータを使用して、さまざまな方法で ADS リクエストをカスタマイズできます。ADS ホスト名のみを含める必要があります。

以下の例では、リクエストをカスタマイズできるいくつかの方法を示しています。

プレイヤーパラメータとセッションパラメータを連結して新しいパラメータを作成します。例:
```
https://my.ads.com?key1=[player_params.value1][session.id]
```
パス要素の一部としてプレイヤーパラメータを使用します。例:
```
https://my.ads.com/[player_params.path]?key=value
```
プレイヤーパラメータを使用して、値だけではなくパス要素とキー自体の両方を渡します。例:
```
https://my.ads.com/[player_params.path]?[player_params.key1]=[player_params.value1]
```

MediaTailor 設定エイリアスのトラブルシューティング

AWS Elemental MediaTailor は、一般的な設定エイリアスの問題とエラーシナリオに関する体系的なトラブルシューティングガイダンスを提供します。

設定エイリアスの検証エラー

設定エイリアスがないか無効である場合、MediaTailor は問題の特定に役立つ特定のエラーレスポンスを返します。

一般的なエラーシナリオ

次の表に、一般的な設定エイリアスエラーとその解決手順を示します。

エラー	原因	解決方法
HTTP 400: 無効なプレイヤーパラメータエイリアス	ConfigurationAliases にプレイヤーパラメータ値が見つかりません	対応する ConfigurationAliases マッピングにプレイヤーパラメータ値がキーとして存在することを確認します。
HTTP 400: 必要な設定エイリアスがありません	対応する ConfigurationAliases エントリなしで使用されるドメイン変数	必要なすべてのエイリアスマッピングを使用して、欠落しているプレイヤーパラメータを ConfigurationAliases に追加する
HTTP 400: 設定の検証に失敗しました	ConfigurationAliases 構造が正しくないか、不完全です	JSON 構造を検証し、すべてのドメイン変数に対応するエイリアスがあることを確認する
URLs の空の文字列置換	ドメイン以外の変数エイリアスが見つかりません	ConfigurationAliases で欠落しているエイリアスマッピングを追加するか、デフォルト値を指定する

検証チェックリスト

次のチェックリストを使用して、設定エイリアスの設定を検証します。

ドメイン変数カバレッジ： URLs のドメイン部分で使用されるすべての変数に、対応する ConfigurationAliases エントリがあることを確認します。
エイリアスの完全性： 可能なすべてのプレイヤーパラメータ値がエイリアスマッピングのキーとして含まれていることを確認します。
JSON 構造： ConfigurationAliases JSON が正しくフォーマットされ、ネストされていることを確認する
パラメータの命名： すべてのプレイヤーパラメータで player_params. プレフィックスが使用されていることを確認します。
値の整合性： エイリアス値が意図した用途 (URLs、プロファイル名など) に対して有効であることを確認します。

設定エイリアスの解決のデバッグ

この体系的なアプローチに従って、設定エイリアス解決の問題をデバッグします。

Step-by-stepのデバッグ方法

設定エイリアスの問題を特定して解決するには、次の手順に従います。

設定エイリアスのデバッグ手順

設定構造の検証： 再生設定に正しくフォーマットされた ConfigurationAliases が含まれていることを確認します。


{
    "ConfigurationAliases": {
        "player_params.example_param": {
            "alias1": "value1",
            "alias2": "value2"
        }
    }
}

プレイヤーパラメータの形式を確認する： セッションの初期化に正しくフォーマットされたプレイヤーパラメータが含まれていることを確認します。
```
{
    "playerParams": {
        "example_param": "alias1"
    }
}
```
エイリアスマッピングの検証： プレイヤーパラメータ値 ("alias1") が ConfigurationAliases マッピングのキーとして存在することを確認します。
シンプルな設定でテストする： 最小限の設定から始めて問題を分離する
エラーレスポンスのモニタリング： 特定の検証メッセージの MediaTailor エラーレスポンスを確認する
解決URLs の検証： 最終的な解決済み URLsが有効でアクセス可能であることを確認します。

設定エイリアスのベストプラクティス

次のベストプラクティスに従って、信頼性の高い設定エイリアスの実装を確保します。

セキュリティに関する考慮事項

設定エイリアスを使用する場合は、次のセキュリティ対策を実装します。

入力検証： エイリアス解決で使用する前に、すべてのプレイヤーパラメータ値を検証する
エイリアス値のサニタイズ： エイリアス値に想定される文字と形式のみが含まれていることを確認します。
ドメインの制限： ドメインエイリアスを信頼できる制御されたドメインに制限する
アクセスコントロール： 承認された担当者のみに設定変更を制限する

パフォーマンスの最適化

次の推奨事項を使用して、設定エイリアスのパフォーマンスを最適化します。

エイリアス数を最小限に抑える： 必要なエイリアスのみを使用して処理オーバーヘッドを削減する
効率的な命名： エイリアスとパラメータに明確で一貫した命名規則を使用する
デフォルト値： 一般的なユースケースに適したデフォルトエイリアスを指定します。
設定キャッシュ： MediaTailor の設定キャッシュを活用してパフォーマンスを向上させる

メンテナンスとモニタリング

以下のプラクティスを使用して、信頼性の高い設定エイリアスオペレーションを維持します。

定期的な検証： すべてのエイリアスマッピングが最新で機能していることを定期的に検証する
エラーモニタリング： 欠落または無効なエイリアスに関連する HTTP 400 エラーをモニタリングする
ドキュメント： すべてのエイリアスマッピングとその目的を明確に文書化する
テスト手順： すべてのエイリアスの組み合わせに対して包括的なテストを実装する

動的ドメイン、セッション、およびプレイヤー変数の使用に関する詳細については、該当するトピックを選択してください。

トピック

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

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

ドキュメントの表記規則

前提条件付き広告

MediaTailor パラメータのトラブルシューティング