{
'streamId': 'myStreamId',
'reportingMode': 'client'
}
```
1. **プリフェッチタイプ**では、選択し、対応するセクションを選択して、追加のフィールドについてサポートします。
+ イベントで 1 つの広告時間枠に対して 1 つのプリフェッチスケジュールを作成する場合は、**シングル** を選択します。
+ イベントの各広告ブレークの前に広告を自動的にプリフェッチするスケジュールを作成する場合は、**繰り返し**を選択します。
## 単一のプリフェッチスケジュール
イベントで 1 つの広告表示の前に広告をプリフェッチするスケジュールを作成するには。
1. **[Retrieval]** (取得) ペインで、使用する取得設定を指定します。これらの設定は、MediaTailor が ADS から広告をプリフェッチするタイミングを決定します。また、ADS へのリクエストに含める動的セッション変数があれば決定します。
+ **[Start time]** (開始時間) には、MediaTailor がこの広告ブレーク用のプリフェッチ取得を開始できる時刻を入力します。MediaTailor は、この時刻以降にクライアントによって行われるマニフェストリクエストのための広告のプリフェッチを試みます。デフォルト値は現在の時刻です。値を指定しない場合、サービスは可能な限り速やかにプリフェッチ取得を開始します。
+ **[End time]** (終了時間) には、MediaTailor がこの広告ブレーク用のプリフェッチ取得を停止する時刻を入力します。MediaTailor は、この時刻以前に行われるマニフェストリクエストのための広告のプリフェッチを試みます。取得時間枠は、消費時間枠と重複させることができます。
+ 必要に応じて、一度に ADS へのリクエスト数を制限するようにトラフィックシェーピングを設定します。次のいずれかのアプローチを選択します。
*タイムウィンドウアプローチ*: **トラフィックシェーピングウィンドウ期間**には、MediaTailor が ADS にリクエストを配信する秒数を入力します。詳細については、[「シングルプリフェッチスケジュールの取得の説明](understanding-prefetching.md#avail-matching-criteria-retr)」を参照してください。
*TPS ベースのアプローチ*: **ピーク TPS** と**ピーク同時ユーザー**を設定し、1 秒あたりのトランザクションと同時ユーザーに基づいてリクエストを制限します。詳細については、「[TPS ベースのトラフィックシェーピング](tps-traffic-shaping.md)」を参照してください。
+ [**動的変数**](variables.md) セクションに、最大 100 個の動的セッション変数を入力します。MediaTailor は、ADS に送信するプリフェッチリクエストでの代入にこれらの変数を使用します。動的セッション変数を入力しない場合、MediaTailor は [ADS URL ](configurations-create.md#configurations-create-main)に含まれる動的変数の値を補間するよう最善を尽くします。
+ **[Add dynamic variable]** (動的変数を追加) をクリックします。
+ Key には****、 などの動的セッション変数キーを入力します`scte.event_id`。これには、MediaTailor がサポートする任意の動的変数を使用できます。動的セッション変数の詳細については、「」を参照してください[ADS リクエストの MediaTailor セッション変数](variables-session.md)。
+ **[Value]** (値) には、*my-event* などの動的変数値を入力します。
+ 別の動的変数を追加するには、**[Add dynamic variable]** (動的変数を追加) をクリックします。
1. **[Consumption]** (消費) ペインで、消費時間枠に使用する設定を指定します。これらの設定は、MediaTailor が広告ブレークに広告を配置するタイミングを決定します。また、使用する avail 使用条件も決定します。
+ **[Start time]** (開始時間) には、MediaTailor がプリフェッチされた広告の広告ブレークへの配置を開始する時刻を入力します。デフォルト値は現在の時刻です。時刻を指定しない場合、サービスは可能な限り速やかにプリフェッチ消費を開始します。
+ **[End time]** (終了時間) には、MediaTailor がプリフェッチされた広告の広告ブレークへの配置を停止する時刻を入力します。MediaTailor は、この時刻以前に行われるクライアントのマニフェストリクエストのための広告のプリフェッチを試みます。終了時刻は、開始時刻の後、かつ現時点から 1 日未満の時刻にする必要があります。消費時間枠は、取得時間枠と重複させることができます。
+ [**[Avail matching criteria]**](variables.md) (Avail 一致条件) セクションで **[Add avail criteria]** (avail 条件を追加) をクリックし、スケジュールに最大 5 個の avail 一致条件を追加します。その後、**[Dynamic variable key]** (動的変数キー) で、`scte.event_id` などの動的変数キーを追加します。MediaTailor は、クライアントが MediaTailor に渡す動的変数値、または MediaTailor がセッションデータなどの情報から推測する動的変数値で定義された基準を満たしている*場合にのみ*MediaTailor 、プリフェッチされた広告を広告ブレークに配置します。広告時間枠が指定された一致基準を満たしていない場合、MediaTailor はその時間枠のプリフェッチをスキップします。詳細については、[「 Single prefetch schedule consumption explanation](understanding-prefetching.md#avail-matching-criteria)」を参照してください。
1. **[Add avail criteria]** (Avail 条件を追加) をクリックします。
プリフェッチスケジュールは、消費時間枠の終了時間後、自動的に期限が切れます。これらは、診断目的のために少なくとも 7 日間表示された後、MediaTailor によって自動的に削除されます。また、プリフェッチスケジュールはいつでも手動で削除できます。プリフェッチスケジュールを手動で削除する方法については、以下の「[プリフェッチスケジュールの削除](deleting-prefetch-schedules.md)」セクションを参照してください。
### クライアントが CreatePrefetchSchedule API を呼び出す頻度の決定
広告ブレークが配信される正確なタイミングをユーザーが把握している場合、クライアントは 1 日 1 回 [CreatePrefetchSchedule](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_CreatePrefetchSchedule.html) API をプログラム的に呼び出して、取得と消費をセットアップできます。クライアントは、一日中何度も API を呼び出して、取得と消費を定義することもできます。API コールの頻度を選択するときは、[アクティブなプリフェッチスケジュールの最大数](quotas.md#prefetch-schedules-limit)と、プリフェッチスケジュールの作成後に広告時間枠スケジュールが変更される可能性を考慮してください (複数可）。プリフェッチスケジュールの作成後に広告ブレークスケジュールが変更される可能性が高い場合は、API をより頻繁に呼び出すことをお勧めします。
## 定期的なプリフェッチスケジュール
イベントの各広告表示の前に広告をプリフェッチするスケジュールを作成するには。
1. **定期的な取得**ペインで、使用する取得設定を指定します。これらの設定は、MediaTailor が ADS から広告をプリフェッチするタイミングを決定します。また、ADS へのリクエストに含める動的セッション変数があれば決定します。
+ **定期的なプリフェッチウィンドウ**には、MediaTailor がこの広告時間枠のプリフェッチ取得を開始できる時間を入力します。MediaTailor は、この時刻以降にクライアントによって行われるマニフェストリクエストのための広告のプリフェッチを試みます。デフォルト値は現在の時刻です。値を指定しない場合、サービスは可能な限り速やかにプリフェッチ取得を開始します。
+ **表示終了後の遅延**には、次の表示の広告をプリフェッチする前に MediaTailor が表示終了後に待機する秒数を入力します。値を指定しない場合、MediaTailor はデフォルトで遅延なしになります。
+ 必要に応じて、一度に ADS へのリクエスト数を制限するようにトラフィックシェーピングを設定します。次のいずれかのアプローチを選択します。
*タイムウィンドウアプローチ*: **トラフィックシェーピングウィンドウ期間**には、MediaTailor が ADS にリクエストを配信する秒数を入力します。詳細については、[「定期的なプリフェッチスケジュールの取得の説明](understanding-prefetching.md#avail-matching-criteria-recurring-retr)」を参照してください。
*TPS ベースのアプローチ*: **ピーク TPS** と**ピーク同時ユーザー**を設定し、1 秒あたりのトランザクションと同時ユーザーに基づいてリクエストを制限します。詳細については、「[TPS ベースのトラフィックシェーピング](tps-traffic-shaping.md)」を参照してください。
+ [**動的変数**](variables.md)セクションには、最大 100 個の動的セッション変数を入力します。MediaTailor は、ADS に送信するプリフェッチリクエストでの代入にこれらの変数を使用します。動的セッション変数を入力しない場合、MediaTailor は [ADS URL ](configurations-create.md#configurations-create-main)に含まれる動的変数の値を補間するよう最善を尽くします。
+ **[Add dynamic variable]** (動的変数を追加) をクリックします。
+ **Key** には、 などの動的セッション変数キーを入力します`scte.event_id`。これには、MediaTailor がサポートする任意の動的変数を使用できます。動的セッション変数の詳細については、「」を参照してください[ADS リクエストの MediaTailor セッション変数](variables-session.md)。
+ **[Value]** (値) には、*my-event* などの動的変数値を入力します。
+ 別の動的変数を追加するには、**[Add dynamic variable]** (動的変数を追加) をクリックします。
1. **[Consumption]** (消費) ペインで、消費時間枠に使用する設定を指定します。これらの設定は、MediaTailor が広告ブレークに広告を配置するタイミングを決定します。また、使用する avail 使用条件も決定します。
+ **取得済み広告の有効期限**については、取得後広告を挿入できる期間を指定します。
+ [**[Avail matching criteria]**](variables.md) (Avail 一致条件) セクションで **[Add avail criteria]** (avail 条件を追加) をクリックし、スケジュールに最大 5 個の avail 一致条件を追加します。その後、**[Dynamic variable key]** (動的変数キー) で、`scte.event_id` などの動的変数キーを追加します。MediaTailor は、クライアントが MediaTailor に渡す動的変数値、または MediaTailor がセッションデータなどの情報から推測する動的変数値で定義された基準を満たしている*場合にのみ*MediaTailor 、プリフェッチされた広告を広告ブレークに配置します。広告時間枠が指定された一致基準を満たしていない場合、MediaTailor はその時間枠のプリフェッチをスキップします。詳細については、[「定期的なプリフェッチスケジュールの消費の説明](understanding-prefetching.md#avail-matching-criteria-recur)」を参照してください。
1. **[Add avail criteria]** (Avail 条件を追加) をクリックします。
プリフェッチスケジュールは、消費時間枠の終了時間後、自動的に期限が切れます。これらは、診断目的のために少なくとも 7 日間表示された後、MediaTailor によって自動的に削除されます。また、プリフェッチスケジュールはいつでも手動で削除できます。プリフェッチスケジュールを手動で削除する方法については、以下の「[プリフェッチスケジュールの削除](deleting-prefetch-schedules.md)」セクションを参照してください。
# TPS ベースのトラフィックシェーピング
AWS Elemental MediaTailor には、一度に ADS へのリクエスト数を制限するための 2 つのオプションのトラフィックシェーピングアプローチが用意されています。TPS ベースのトラフィックシェーピングは、プリフェッチスケジュールのタイムウィンドウベースのトラフィックシェーピングに代わる方法を提供します。このアプローチでは、時間計算ではなく、1 秒あたりのトランザクション (TPS) と予想される同時ユーザー数の観点から広告決定サーバー (ADS) 容量を指定できるため、より直感的な設定が可能になります。
## TPS ベースのトラフィックシェーピングの仕組み
取得ウィンドウの期間を指定する代わりに、次のパラメータを指定します。
ピーク TPS
ADS が処理できる 1 秒あたりのリクエストの最大数。このパラメータにはデフォルト値はありません。
ピーク同時ユーザー
コンテンツの同時ビューワーの予想されるピーク数。このパラメータにはデフォルト値はありません。
MediaTailor は、同時セッションの数に関係なく、指定した TPS 制限内に収まるように、プリフェッチリクエストを一定期間にわたって自動的に分散します。
**Example TPS ベースの設定例**
ADS は 500 TPS を処理でき、ピーク時に 100,000 人の同時視聴者を想定します。以下を設定します。
+ ピーク TPS: 500
+ ピーク同時ユーザー: 100,000
MediaTailor は、同時セッションの数に関係なく、指定した TPS 制限内に収まるように、プリフェッチリクエストを一定期間にわたって自動的に分散します。
# プリフェッチスケジュールの削除
以下は、MediaTailor コンソールを使用してプリフェッチスケジュールを削除する方法を説明する手順です。MediaTailor API を使用してプログラムでプリフェッチスケジュールを削除する方法については、 API *AWS Elemental MediaTailor リファレンス*の[DeletePrefetchSchedule](https://docs.aws.amazon.com/mediatailor/latest/apireference/API_DeletePrefetchSchedule.html)」を参照してください。
**注記**
削除はリアルタイムでは行われません。MediaTailor がプリフェッチスケジュールを削除する間に遅延が発生する場合があり、その間はプリフェッチの取得と消費がバックグラウンドで引き続き実行されます。
**コンソールを使用してスケジュールされたアクションを削除する**
1. MediaTailor コンソール ([https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/)) を開きます。
1. ナビゲーションペインで **[Configurations]** (設定) をクリックします。削除するプリフェッチスケジュールが含まれている再生設定を選択します。
1. **[Prefetch schedules]** (プリフェッチスケジュール) タブで、削除するプリフェッチスケジュールを選択します。その後、**[Delete]** (削除) をクリックします。
# での前提条件付き広告の使用 AWS Elemental MediaTailor
[一般的な広告挿入ワークフロー](what-is-flow.md)では、MediaTailor はコンテンツストリームに合わせて広告を動的にトランスコードし、保存して、ライブストリームに広告をステッチします。このプロセスは、MediaTailor が広告決定サーバー (ADS) から VAST レスポンスで広告を受信した後にのみ行われるため、広告がスティッチング可能になるまでに遅延が発生します。広告ステッチングワークフローに追加のレイテンシーが発生した場合 (ADS タイムアウトやその他のコンテンツやネットワークの問題が原因）、MediaTailor は部分的に表示を埋めたり、広告時間枠を完全に見逃したりする可能性があります。
コンテンツに広告をステッチするのに必要な時間を短縮するために、前提条件付き広告を使用できます。前提条件付き広告は、MediaTailor 広告挿入で使用する前にトランスコードする広告です。ADS に無条件広告URLs を提供する代わりに、前提条件付き広告の URLs を指定します。MediaTailor リクエストに対する VAST レスポンスで、ADS には前提条件付き広告への直接リンクが含まれています。広告ステッチングのトランスコード部分を削除することで、MediaTailor は広告を保存してコンテンツストリームにステッチするだけで済みます。事前条件付き広告を使用した広告ステッチングプロセスにより、MediaTailor が VAST レスポンスを通じて広告を認識してから、広告がコンテンツにステッチされるまでの時間が短縮されます。
または、広告プリフェッチを使用することもできます。これは、広告時間枠が必要になる前に、スケジュールされた時刻に広告ステッチングプロセスを実行するように MediaTailor を設定する場合です。広告プリフェッチの詳細については、「」を参照してください[広告のプリフェッチ](prefetching-ads.md)。
## 前提条件付き広告の要件
以下は、前提条件付き広告で広告ステッチングワークフローを設定する際に考慮すべき要件です。
### `MediaFiles` の要件
広告サーバーが MediaTailor に送信する VAST レスポンスには`MediaFiles`、以下の要件を満たすものを含める必要があります。
広告 (`Creative`) には、コンテンツストリームのビットレートバリアントに準拠するバリアントが必要です。*VAST レスポンスで適切な広告バリアントを使用してテンプレートマニフェストを照合するのはお客様の責任です。 *
前提条件付き広告を使用すると、広告挿入の効率を高めることができますが、MediaTailor では、広告のメディアファイルがコンテンツマニフェスト仕様と互換性があることを保証するトランスコードプロセスを管理する機能はありません。広告がコンテンツストリームと一致しない場合、MediaTailor が挿入を見逃したり、一致しないと再生デバイスがエラーになる可能性があります。
さらに、MediaTailor トランスコードなしでコンテンツストリームにステッチインするには、 が次の要件を満たしている`MediaFile`必要があります。
+ MediaTailor がダウンロードできるようにするには、パブリックインターネットでアクセス可能である必要があります。
+ VAST レスポンス`delivery="streaming"`で として示されているストリーミング配信を使用する必要があります。
+ (HLS `.m3u8`の場合) または `.mpd` (DASH の場合) ファイルである必要があります。
**Example VAST レスポンス**
次の VAST レスポンスの例から、MediaTailor は次の URL `MediaFile`で を挿入します。 URLs
+ HLS ストリームの場合、MediaTailor は を使用します`https://example-ad-origin.amazonaws.com/ad1/index_low.m3u8`。これは、ストリーミング配信とサポートされているファイル拡張子 (.`m3u8`) `MediaFile`を持つ最初の です。
+ DASH ストリームの場合、MediaTailor は を使用します`https://example-ad-origin.amazonaws.com/ad1/index.mpd`。これは、ストリーミング配信とサポートされているファイル拡張子 (.`mpd`) `MediaFile`を持つ最初の です。
```
ExampleAdSystem
ad1
de8e0d33-9c72-4d77-bb3a-f7e566ffc605
00:00:30
```
### 広告マニフェストの要件
前提条件付き広告を使用するには、親広告マニフェストと子広告マニフェストが次の要件を満たしている必要があります。
+ VAST レスポンスの `Creative`セクションにリンクされているマニフェストは、親広告マニフェストである必要があります。
+ 子広告マニフェストURLs は相対パスである必要があります。
+ 子広告マニフェストは、親マルチバリアントプレイリストと同じディレクトリに同じレベルで存在する必要があります。子マニフェストをサブディレクトリやその他の場所に配置することはできません。
**Example サポートされている親多変量プレイリスト**
次の親広告マルチバリアントプレイリストには、子広告メディアプレイリストの相対 URLs が含まれています。子プレイリストも親マルチバリアントプレイリストと同じディレクトリにあります。
```
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=150000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
index_1.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
index_2.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,CODECS="avc1.42e00a,mp4a.40.2"
index_3.m3u8
```
**Example サポートされていない親マルチバリアントプレイリスト: サブディレクトリ**
次の親広告多変量プレイリストには、親多変量プレイリストに関連するサブディレクトリにある子プレイリストが含まれています。これは、前提条件付き広告でサポートされているプレイリストではありません。
```
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=150000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
child/index_1.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
child/index_2.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,CODECS="avc1.42e00a,mp4a.40.2"
child/index_3.m3u8
```
**Example サポートされていない親多変量プレイリスト: URLs**
次の親広告マルチバリアントプレイリストには、絶対 URLs を持つ子プレイリストが含まれています。これは、前提条件付き広告でサポートされているプレイリストではありません。
```
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=150000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
https://example.mediatailor.us-west-2.amazonaws.com/index_1.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=440000,RESOLUTION=416x234,CODECS="avc1.42e00a,mp4a.40.2"
https://example.mediatailor.us-west-2.amazonaws.com/index_2.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,CODECS="avc1.42e00a,mp4a.40.2"
https://example.mediatailor.us-west-2.amazonaws.com/index_3.m3u8
```
## 前提条件付き広告ワークフロー
以下は、MediaTailor での広告ステッチングワークフローにおける前提条件付き広告の仕組みの基本的な説明です。ワークフローの最初の部分は、前提条件付き広告を使用するようにセットアップするために実行する必要があるアクションです。2 番目のパートでは、MediaTailor が広告を処理する方法について説明します。
**パート 1: 前提条件付き広告のセットアップ**
MediaTailor で前提条件付き広告を使用するワークフローを設定するには、次のステップを実行します。
1. などのトランスコーダーサービスを使用して、テンプレートマニフェストのさまざまなビットレート、解像度、コーデックをサポートするバリアントにクリエイティブを AWS Elemental MediaConvert条件付けします。
1. VAST レスポンスで使用するため、事前にトランスコードされたメディアファイルの URLs を ADS に提供します。
1. MediaTailor [で再生設定を作成します](configurations-create.md)。事前条件付き広告を使用するには、設定のストリーミングメディアファイルの条件設定で**「なし**」を選択します。 ****
1. 通常どおり、コンテンツ配信のセットアップを続行します。
**パート 2: MediaTailor 広告処理**
MediaTailor の広告ステッチングは、「」の説明に従って完了します[MediaTailor 広告挿入の仕組み](what-is-flow.md)。MediaTailor は、ADS から VAST レスポンスを受信すると、次のロジックを使用して、広告に対して実行するアクションを決定します。このロジックは、再生設定の**ストリーミングメディアファイルの条件**設定によって決まります。
+ **ストリーミングメディアファイルのコンディショニング**が **Transcode** に設定されている場合、MediaTailor はメディアファイルを`progressive`配信でトランスコードし、マニフェストにステッチします。`progressive` 配信メディアファイルを含む十分な広告がない場合、MediaTailor はそれらをトランスコードして`streaming`配信に使用します。
+ **ストリーミングメディアファイルのコンディショニング**を **None** に設定すると、MediaTailor は`streaming`、配信メディアファイルをトランスコードせずにマニフェストに広告をステッチします。`streaming` 配信メディアファイルを含む十分な広告がない場合、MediaTailor はそれらをトランスコードして`progressive`配信に使用します。
# ADS リクエストの MediaTailor 動的広告変数
AWS Elemental MediaTailor は動的広告変数を使用して、表示セッションから広告決定サーバー (ADS) に情報を渡します。この情報は、ADS がビューワーに最も関連性の高い広告を選択するのに役立ちます。
このセクションでは、動的広告変数の概要と、特定の実装ガイドへのリンクについて説明します。step-by-stepの設定手順については、以下の個々のトピックを参照してください。
**動的変数タイプ**
MediaTailor は、次の 4 種類の動的変数をサポートしています。
+ **セッション変数** – セッション ID や SCTE-35 データなど、自動的に生成された値。「[ADS リクエストの MediaTailor セッション変数](variables-session.md)」を参照してください。
+ **プレイヤー変数** – ビデオプレイヤーによって送信されるカスタムパラメータ。「[ADS リクエストの MediaTailor プレイヤー変数](variables-player.md)」を参照してください。
+ **設定エイリアス**を持つ**ドメイン変数** – マルチオリジン設定の動的 URL ドメイン。
+ **設定エイリアス** – 動的変数置換の事前定義されたマッピング。「[設定エイリアス](configuration-aliases-overview.md)」を参照してください。
**一般的なユースケース**
動的広告変数を使用して以下を行います。
+ ビューワーの属性と設定を ADS に渡す
+ 地理的位置に基づいて異なるオリジンにリクエストをルーティングする
+ MediaPackage 統合でタイムシフト表示を有効にする
+ A/B テストとフェイルオーバーのシナリオを実装する
以下のセクションでは、MediaTailor での動的広告変数の使用について詳しく説明します。
**Topics**
+ [セッション変数](variables-session.md)
+ [プレイヤー変数](variables-player.md)
+ [ドメイン変数](variables-domains.md)
+ [設定エイリアス](configuration-aliases-overview.md)
+ [ADS パラメータを渡す](passing-paramters-to-the-ads.md)
+ [パラメータルーティング](parameter-routing-behavior.md)
+ [MediaPackage の統合](mediapackage-integration-param.md)
+ [セッションの動作](parameter-session-behavior.md)
+ [パラメータリファレンス](parameter-comprehensive-reference.md)
+ [パラメータのトラブルシューティング](parameter-troubleshooting.md)
+ [エイリアスのトラブルシューティング](configuration-aliases-troubleshooting.md)
パラメータのフォーマット要件とトラブルシューティングについては、[MediaTailor パラメータのリファレンスと制限事項](parameter-comprehensive-reference.md)「」および「」を参照してください[MediaTailor パラメータのトラブルシューティングガイド](parameter-troubleshooting.md)。
# ADS リクエストの MediaTailor セッション変数
AWS Elemental MediaTailor テンプレート ADS URL のこのセクションに記載されている 1 つ以上の変数を指定する AWS Elemental MediaTailor ように を設定すると、 はセッションデータを広告決定サーバー (ADS) に送信します。個々の変数を使用する、および複数の変数を連結して単一の値を作成することが可能です。MediaTailor は一部の値を生成し、マニフェスト、およびプレイヤーのセッション開始リクエストといったソースから残りの値を取得します。
次の表は、テンプレート ADS リクエスト URL 設定で使用できるセッションデータ変数を示しています。表に記載されているセクション番号は、米国ケーブル電気通信技術者協会 (SCTE)-35 仕様の 2019 年版、[デジタルプログラム挿入キューイングメッセージに対応しています。広告プリフェッチの詳細については、](https://account.scte.org/standards/library/catalog/scte-35-digital-program-insertion-cueing-message/)「」を参照してください[広告のプリフェッチ](prefetching-ads.md)。
| 名前 | 広告プリフェッチに使用可能 | SCTE-35 仕様セクション | [Description] (説明) |
| --- | --- | --- | --- |
| [avail.index] | はい | | インデックス内の広告表示の位置を表す数値。再生セッションの開始時に、MediaTailor はマニフェスト内のすべての ad avail のインデックスを作成し、セッションが継続する間そのインデックスを保存します。MediaTailor が avail を埋めるために ADS に対してリクエストを行うときは、そのリクエストに ad avail インデックス番号を含めます。このパラメータにより、ADS は、競合相手の除外や頻度の上限設定などの機能を使用して広告の選択を改良できます。 |
| [avail.random] | はい | | MediaTailor が ADS へのリクエストごとに生成する 0～10,000,000,000 の乱数。競合する会社から広告を切り離すなどの機能を有効にするために、このパラメータを使用する広告サーバーもあります。 |
| [scte.archive\$1allowed\$1flag] | はい | 10.3.3.1 | オプションのブール値。この値が 0 の場合、記録制限はセグメントでアサートされます。この値が 1 の場合、記録の制限はセグメントでアサートされません。 |
| [scte.avail\$1num] | はい | 9.7.2.1 | 長い数値としてavail\$1num、SCTE-35 フィールド から MediaTailor によって解析された値。MediaTailor はこの値を使用して、リニア ad avail 番号を指定できます。値は整数である必要があります。 |
| [scte.avails\$1expected] | はい | 9,7.2.1 | 現在のイベント内の予想可用性数を指定するオプションのロング値。 |
| [scte.delivery\$1not\$1restricted\$1flag] | はい | 10.3.3.1 | オプションのブール値。この値が 0 の場合、次の 5 ビットが予約されます。この値が 1 の場合、SCTE-35 仕様で説明されているように、次の 5 ビットが意味を持ちます。 |
| [scte.device\$1restrictions] | はい | 10.3.3.1 | デバイスの 3 つの事前定義された独立した非階層グループにシグナルを送信するオプションの整数値。この変数の詳細については、SCTE-35 仕様の segments\$1expected の説明を参照してください。 |
| [scte.event\$1id] | はい | 9.1 および 9.7.2.1 | 長い数値としてsplice\$1event\$1id、SCTE-35 フィールド から MediaTailor によって解析された値。MediaTailor はこの値を使用して、リニア ad avail 番号の指定や、広告ポッドの位置などの広告サーバークエリ文字列の入力を行います。値は整数である必要があります。 |
| [scte.no\$1regional\$1blackout\$1flag] | はい | 10.3.3.1 | オプションのブール値。この値が 0 の場合、リージョンのブラックアウト制限がセグメントに適用されます。この値が 1 の場合、リージョンのブラックアウト制限はセグメントには適用されません。 |
| [scte.segment\$1num] | はい | 10.3.3.1 | セグメントのコレクション内のセグメントに番号を付けるオプションの整数値。この変数の詳細については、SCTE-35 仕様の segment\$1num の説明を参照してください。 |
| [scte.segmentation\$1event\$1id] | はい | 10.3.3.1 | MediaTailor はこの変数を として公開します[scte.event_id](#scte.event_id)。 |
| [scte.segmentation\$1type\$1id] | はい | 10.3.3.1 | セグメンテーションタイプを指定するオプションの 8 ビット整数値。この変数の詳細については、SCTE-35 仕様の segmentation\$1type\$1id の説明を参照してください。 |
| [scte.segmentation\$1upid] | `segmentation_upid_type`: はい `private_data`: はい | **segmentation\$1upid**: 10.3.3.1 マネージドプライベート UPID: 10.3.3.3 | SCTE-35 `segmentation_upid`要素に対応します。`segmentation_upid` 要素には、`segmentation_upid_type` と `segmentation_upid_length` が含まれます。 MediaTailor は以下の `segmentation_upid` タイプをサポートします。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/mediatailor/latest/ug/variables-session.html) |
| [scte.segmentation\$1upid.assetId] | はい | | ポッドバスターワークフローsegmentation\$1 upid\$1type用の Managed Private UPID (0xC) と組み合わせて使用します。MediaTailor は、この値を MPU の private\$1data JSON 構造内の assetId パラメータから取得します。詳細については、「[Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow)」を参照してください。 |
| [scte.segmentation\$1upid.cueData.key] | はい | | ポッドバスターワークフローsegmentation\$1 upid\$1type用の Managed Private UPID (0xC) と組み合わせて使用します。MediaTailor は、この値を MPU の private\$1data JSON 構造内の cueData.key パラメータから取得します。詳細については、「[Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow)」を参照してください。 |
| [scte.segmentation\$1upid.cueData.value] | はい | | ポッドバスターワークフローsegmentation\$1 upid\$1type用の Managed Private UPID (0xC) と組み合わせて使用します。MediaTailor は、この値を MPU の private\$1data JSON 構造内の cueData.key パラメータから取得します。詳細については、「[Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow)」を参照してください。値は文字列にすることができます。 |
| [scte.segmentation\$1upid.private\$1data.\$1index\$1] | はい | | ターゲットを絞った広告ワークフローsegmentation\$1upid\$1typeの Managed Private UPID (0xC) と組み合わせて使用します。MediaTailor は、コロン区切りのセグメンテーション UPID トークンを分割し、インデックス付きセッション変数を作成します。インデックスはコロン区切りリスト内の位置に対応し、最初のコロンの先頭の空白は無視されます。たとえば、 の場合`segmentation_upid = ":3213214:2313321/5:3943"`、次のようになります。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/mediatailor/latest/ug/variables-session.html) 値は文字列にすることができます。 |
| [scte.segments\$1expected] | はい | 10.3.3.1 | セグメントのコレクション内の個々のセグメントの予想数を指定するオプションの整数値。この変数の詳細については、SCTE-35 仕様の segments\$1expected の説明を参照してください。 |
| [scte.sub\$1segment\$1num] | はい | 10.3.3.1 | サブセグメントのコレクション内の特定のサブセグメントを識別するオプションの整数値。この変数の詳細については、SCTE-35 仕様の sub\$1segment\$1num の説明を参照してください。 |
| [scte.sub\$1segments\$1expected] | はい | 10.3.3.1 | サブセグメントのコレクション内の個々のサブセグメントの予想数を指定するオプションの整数値。この変数の詳細については、SCTE-35 仕様の sub\$1segments\$1expected の説明を参照してください。 |
| [scte.unique\$1program\$1id] | はい | 9.7.2.1 | SCTE-35 splice\$1insertフィールド から MediaTailor によって解析された整数値unique\$1program\$1id。ADS は、一意のプログラムID (UPID) を使用して、ライブリニアストリームにプログラムレベルの広告ターゲティングを提供します。SCTE-35 コマンドがスプライス挿入ではない場合、MediaTailor はこれを空の値に設定します。値は整数である必要があります。 |
| [session.avail\$1duration\$1ms] | はい | | 広告可用性スロットのミリ秒単位の期間。デフォルト値は 300,000 ms です。次のように入力マニフェストから期間値 AWS Elemental MediaTailor を取得します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/mediatailor/latest/ug/variables-session.html) |
| [session.avail\$1duration\$1secs] | はい | | 最も近い秒に丸められた、広告可用性スロットまたは広告表示の秒単位の期間。MediaTailor は、[session.avail\$1duration\$1ms] を判断するときと同じ方法でこの値を判断します。 |
| [session.client\$1ip] | いいえ | | MediaTailor リクエストの送信元のリモート IP アドレス。X-forwarded-for ヘッダーが設定されている場合、その値は MediaTailor が client\$1ip に使用する値です。 |
| [session.id] | いいえ | | 現在の再生セッションの一意の数値識別子。プレイヤーがセッションに対して行うリクエストにはすべて同じ ID が割り当てられるため、その ID は同一の視聴に対するリクエストを関連付けるための ADS フィールドに使用できます。 |
| [session.referer] | いいえ | | 通常、動画プレーヤーをホストしているページの URL。MediaTailor はこの変数を、プレイヤーが MediaTailor に対するリクエストで使用した Referer ヘッダーの値に設定します。プレイヤーがこのヘッダーを提供しない場合、MediaTailor は [session.referer] を空のままにしておきます。マニフェストエンドポイントの前にコンテンツ配信ネットワーク (CDN) またはプロキシを使用し、この変数を表示する場合は、ここでプレイヤーから正しいヘッダーをプロキシします。 |
| [session.user\$1agent] | いいえ | | MediaTailor がプレイヤーのセッション初期化リクエストから受け取ったUser-Agentヘッダー。マニフェストエンドポイントの前で CDN またはプロキシを使用している場合は、ここでプレイヤーからの正しいヘッダーをプロキシする必要があります。 |
| [session.uuid] | いいえ | | の代わりに を使用します**[session.id]**。これは、以下のような現在の再生セッションの一意の識別子です。 e039fd39-09f0-46b2-aca9-9871cc116cde
|
| [avail.source\$1content\$1time\$1epoch\$1ms] | いいえ | | HLS の場合、値は表示を開始したオリジンセグメントの PDT です。DASH の場合、値は ``を含む ` urn:scte:dash:utc-time` の です``。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/mediatailor/latest/ug/variables-session.html) |
**Example**
ADS で一意のセッション識別子を付けて渡される `deviceSession` というクエリパラメータが必要な場合、 AWS Elemental MediaTailor のテンプレート ADS URL は以下のようになります。
```
https://my.ads.server.com/path?deviceSession=[session.id]
```
AWS Elemental MediaTailor は、ストリームごとに一意の識別子を自動的に生成し、 の代わりに識別子を入力します`session.id`。識別子が `1234567` である場合、MediaTailor が ADS に対して行う最終リクエストは、以下のようになります。
```
https://my.ads.server.com/path?deviceSession=1234567
```
ADS で複数のクエリパラメータを渡す必要がある場合、 のテンプレート ADS URL は次の AWS Elemental MediaTailor ようになります。
```
https://my.ads.server.com/sample?e=[scte.avails_expected]&f=[scte.segment_num]&g=[scte.segments_expected]&h=[scte.sub_segment_num]&j=[scte.sub_segments_expected]&k=[scte.segmentation_type_id]
```
次の DASH マーカーの XML フラグメントの例は、 の使用方法を示しています`scte35:SpliceInsert`。
```
```
次の DASH マーカーの XML フラグメントの例は、 の使用方法を示しています`scte35:TimeSignal`。
```
0100
```
次の DASH マーカーの XML フラグメントの例は、 の使用方法を示しています`scte35:Binary`。
```
/DAhAAAAAAAAAP/wEAUAAAHAf+9/fgAg9YDAAAAAAAA25aoh
QW5vdGhlciB0ZXN0IHN0cmluZyBmb3IgZW5jb2RpbmcgdG8gQmFzZTY0IGVuY29kZWQgYmluYXJ5Lg==
```
次の HLS タグの例は、 の使用方法を示しています`EXT-X-DATERANGE`。
```
#EXT-X-DATERANGE:ID="splice-6FFFFFF0",START-DATE="2014-03-05T11:
15:00Z",PLANNED-DURATION=59.993,SCTE35-OUT=0xFC002F0000000000FF0
00014056FFFFFF000E011622DCAFF000052636200000000000A0008029896F50
000008700000000
```
次の HLS タグの例は、 の使用方法を示しています`EXT-X-CUE-OUT`。
```
#EXT-OATCLS-SCTE35:/DA0AAAAAAAAAAAABQb+ADAQ6QAeAhxDVUVJQAAAO3/PAAEUrEoICAAAAAAg+2UBNAAANvrtoQ==
#EXT-X-ASSET:CAID=0x0000000020FB6501
#EXT-X-CUE-OUT:201.467
```
次の HLS タグの例は、 の使用方法を示しています`EXT-X-SPLICEPOINT-SCTE35`。
```
#EXT-X-SPLICEPOINT-SCTE35:/DA9AAAAAAAAAP/wBQb+uYbZqwAnAiVDVUVJAAAKqX//AAEjW4AMEU1EU05CMDAxMTMyMjE5M19ONAAAmXz5JA==
```
次の例は、`scte35:Binary`デコードの使用方法を示しています。
```
{
"table_id": 252,
"section_syntax_indicator": false,
"private_indicator": false,
"section_length": 33,
"protocol_version": 0,
"encrypted_packet": false,
"encryption_algorithm": 0,
"pts_adjustment": 0,
"cw_index": 0,
"tier": "0xFFF",
"splice_command_length": 16,
"splice_command_type": 5,
"splice_command": {
"splice_event_id": 448,
"splice_event_cancel_indicator": false,
"out_of_network_indicator": true,
"program_splice_flag": true,
"duration_flag": true,
"splice_immediate_flag": false,
"utc_splice_time": {
"time_specified_flag": false,
"pts_time": null
},
"component_count": 0,
"components": null,
"break_duration": {
"auto_return": false,
"duration": {
"pts_time": 2160000,
"wall_clock_seconds": 24.0,
"wall_clock_time": "00:00:24:00000"
}
},
"unique_program_id": 49152,
"avail_num": 0,
"avails_expected": 0
"segment_num": 0,
"segments_expected": 0,
"sub_segment_num": 0,
"sub_segments_expected": 0
},
"splice_descriptor_loop_length": 0,
"splice_descriptors": null,
"Scte35Exception": {
"parse_status": "SCTE-35 cue parsing completed with 0 errors.",
"error_messages": [],
"table_id": 252,
"splice_command_type": 5
}
}
```
# ADS リクエストの MediaTailor プレイヤー変数
AWS Elemental MediaTailor テンプレート ADS URL で`player_params.`変数を指定する AWS Elemental MediaTailor ように を設定すると、 はプレイヤーから受信したデータを ADS に送信します。例えば、プレイヤーが MediaTailor に対するリクエストで `user_id` という名前のクエリパラメータを送信する場合、ADS リクエストでそのデータを渡すには、ADS URL 設定に `[player_params.user_id]` を含めます。
これにより、ADS リクエストに含まれるクエリパラメータを制御できます。通常、ADS が認識する特殊なクエリパラメータを ADS リクエスト URL に追加し、そのパラメータの値としてキーと値のペアを指定します。
この後の手順で使用されている例では、以下のキーと値のペアを使用しています。
+ *param1* と値 *value1:*
+ *param2* と値 *value2:*
**クエリパラメータをキーバリューペアとして追加する**
1. で AWS Elemental MediaTailor、パラメータを参照するように ADS リクエストテンプレート URL を設定します。以下の URL では、サンプルパラメータが含まれていることがわかります。
```
https://my.ads.com/path?param1=[player_params.param1]¶m2=[player_params.param2]
```
1. (オプション) サーバー側の広告追跡レポートの場合は、プレイヤーのキーバリューペアを URL でエンコードします。MediaTailor がセッション開始リクエストを受信すると、値を URL で 1 回エンコードしてから、それらを ADS リクエスト URL に代入します。
**注記**
ADS が URL でエンコードされた値を必要とする場合は、プレイヤーでこの値を 2 回 URL エンコードします。そうすることで、MediaTailor によって行われたデコードから、ADS のために 1 回エンコードされた値が得られます。
例えば、ADS に送信された値のデコードされた表現が `param1=value1:¶m2=value2:` である場合、URL でエンコードされた表現は `param1=value1%3A¶m2=value2%3A` です。
1. プレイヤーからのセッション開始呼び出しで、キーバリューペアを単一のクエリパラメータの値として MediaTailor に渡します。以下のサンプルの呼び出しでは、サーバー側とクライアント側の広告追跡レポートに使用されるキーと値のペアの例を示しています。
+ サーバー側の広告追跡レポートのリクエスト例 - URL エンコードペアを使用する
HLS:
```
.m3u8?ads.param1=value1%3A&ads.param2=value2%3A
```
DASH:
```
.mpd?ads.param1=value1%3A&ads.param2=value2%3A
```
+ クライアント側の広告追跡レポートのリクエスト例 - URL エンコードを使用しない
HLS:
```
POST .m3u8
{
"adsParams": {
"param1": "value1:",
"param2": "value2:"
}
}
```
DASH:
```
POST .mpd
{
"adsParams": {
"param1": "value1:",
"param2": "value2:"
}
}
```
サーバー側のレポートの場合、MediaTailor はプレイヤーリクエストを受信したときにパラメータをデコードします。クライアント側のレポートの場合、MediaTailor は JSON ペイロードで受信したパラメータを変更しません。MediaTailor は以下のリクエストを ADS に送信します。
```
https://my.ads.com/?param1=value1:¶m2=value2:
```
そうすることで、`param1` と `param2` のキーバリューペアが第 1 クラスのクエリパラメータとして ADS リクエストに含まれます。
# 複数のコンテンツソースの MediaTailor ドメイン変数
AWS Elemental MediaTailor 動的ドメイン変数を使用すると、URL **my-ads-server.com** の http://my-ads-server.com 部分など、設定内のプレイヤーパラメータで複数のドメインを使用できます。これにより、単一の設定内で複数のコンテンツソースまたは広告決定サーバー (ADS) を使用することが可能になります。
ドメイン変数は、URI が含まれる任意のパラメータで使用できます。
+ `AdDecisionServerUrl`
+ `AdSegmentUrlPrefix`
+ `ContentSegmentUrlPrefix`
+ `LivePreroll.AdDecisionServerUrl`
+ `VideoContentSourceUrl`
ドメイン変数は、動的変数置換を実行するために、*設定のエイリアス*と共に使用されます。設定エイリアスは、動的ドメイン設定に使用されるプレイヤーパラメータに一連のエイリアスと値をマップします。セットアップ手順については、「」を参照してください[MediaTailor での設定エイリアスの作成と使用](creating-configuration-aliases.md)。詳細なリファレンス情報については、「」を参照してください[MediaTailor 設定エイリアスの概要](configuration-aliases-overview.md)。
# MediaTailor 設定エイリアスの概要
AWS Elemental MediaTailor 設定エイリアスは、URL ドメインやその他のサポートされているフィールドで動的変数置換を有効にします。この機能を使用して、複数のドメインを使用し、セッションの初期化中に URLs動的に設定します。
## ユースケース
設定エイリアスは、以下のシナリオで高度なマルチ設定アーキテクチャを有効にします。
+ **地理的ルーティング:** リージョン固有のエイリアスを使用して、ビューワーの場所に基づいて異なるオリジンまたは広告サーバーにリクエストをルーティングします。実装ガイダンスについては、[CloudFront オリジンフェイルオーバー](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/high_availability_origin_failover.html)」を参照してください。
+ **コンテンツベースのルーティング:** さまざまなコンテンツタイプを特殊なオリジンまたは処理パイプラインに向けます。ルーティング動作の設定については、「」を参照してください[MediaTailor の CDN ルーティング動作を設定する](cdn-routing-behaviors.md)。
+ **フェイルオーバーシナリオ:** エイリアス切り替えを使用して、自動フェイルオーバーでバックアップオリジンと広告サーバーを実装します。詳細な実装については、[MQAR を使用して MediaTailor のマルチリージョンレジリエンスを実装する](media-quality-resiliency.md)「」および「」を参照してください[の CDN 統合を計画する AWS Elemental MediaTailor](planning-cdn-integration.md)。
+ **A/B テスト:** プレイヤーパラメータに基づいてトラフィックをルーティングすることで、さまざまな広告サーバー、オリジン、または設定をテストします。負荷テストのガイダンスについては、[「実際のユーザーモニタリングを使用した Amazon CloudFront のパフォーマンステストの準備と実行](https://aws.amazon.com/blogs/networking-and-content-delivery/prepare-and-run-performance-tests-for-amazon-cloudfront-with-real-user-monitoring/)」を参照してください。
+ **デバイス固有の最適化:** さまざまなデバイスタイプや機能に合わせてコンテンツ配信と広告配信を最適化します。包括的なガイダンスについては、「」を参照してください[MediaTailor、MediaPackage、CDN でマニフェストフィルタリングを設定する](cdn-emp-manifest-filtering.md)。
+ **ロードバランシング:** 動的ルーティングを使用して、複数のオリジンまたは広告サーバーに負荷を分散します。実装ガイダンスについては、[MQAR を使用して MediaTailor のマルチリージョンレジリエンスを実装する](media-quality-resiliency.md)「」および「」を参照してください[の CDN 統合を計画する AWS Elemental MediaTailor](planning-cdn-integration.md)。
## サポートされているフィールド
動的変数は、次の設定フィールドで使用できます。
+ `VideoContentSourceUrl`
+ `AdDecisionServerUrl`
+ `LivePreroll.AdDecisionServerUrl`
+ `AdSegmentUrlPrefix`
+ `ContentSegmentUrlPrefix`
+ `TranscodeProfileName`
+ `SlateAdUrl`
+ `StartUrl`
+ `EndUrl`
以下のセクションでは、設定エイリアスを使用する方法について説明します。
**Topics**
+ [ユースケース](#configuration-aliases-use-cases)
+ [サポートされているフィールド](#configuration-aliases-supported)
+ [の作成と使用](creating-configuration-aliases.md)
+ [フローの例](configuration-aliases-examples.md)
# MediaTailor での設定エイリアスの作成と使用
ドメイン変数の使用を開始する前に、設定のための設定エイリアスを作成します。設定エイリアスは、セッション開始時のドメイン置換変数として使用します。
**制限事項**
設定エイリアスの使用時は、以下の制限に注意してください。
+ ドメインで使用される動的変数は、すべて `ConfigurationAliases` 動的変数として定義される必要があります。
+ プレイヤーパラメータ変数の前に `player_params.` を付ける必要があります。例えば、`player_params.origin_domain` などです。
+ エイリアスされた値のリストは、重要な URLs のドメイン変数 (`VideoContentSourceUrl`、`AdSegmentUrlPrefix`、) に対して包括的である必要があります`ContentSegmentUrlPrefix`。
+ 動的変数を指定しないか、無効なエイリアスを使用する重要な URLs のドメイン変数に対してリクエストが行われた場合、リクエストは HTTP `400`ステータスコードで失敗します。重要でないフィールド (`SlateAdUrl`、、バンパー URLs) は警告をログに記録しますが`TranscodeProfileName`、リクエストは失敗しません。
**欠落しているエイリアスのフォールバック動作**
設定エイリアスが見つからないか無効である場合、MediaTailor は次のフォールバック動作を実装します。
+ **ドメイン変数:** ドメイン変数エイリアスがないか無効の場合、リクエストは HTTP 400 ステータスコードで失敗します。すべてのドメイン変数には、有効なエイリアスが定義されている必要があります。
+ **非ドメイン変数:** URLs の非ドメイン部分 (パス要素やクエリパラメータなど) で使用される変数の場合、エイリアスがないと空の文字列置換になります。
+ **設定の検証:** MediaTailor は、設定の作成および更新オペレーション中にすべての必要なエイリアスが存在することを検証します。
## ステップ 1: 設定エイリアスを作成する
MediaTailor コンソールを使用してドメイン置換に使用する設定エイリアスを作成するには、以下の手順を実行します。
------
#### [ Console ]
**コンソールを使用して設定エイリアスを作成する**
1. MediaTailor コンソール ([https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/)) を開きます。
1. **[Configurations]** (設定) ページの **[Configuration aliases]** (設定エイリアス) ページで、**[Add player parameter]** (プレイヤーパラメータを追加) をクリックします。
1. **Player パラメータ**には、動的変数として使用するプレイヤーパラメータの名前を入力します。例えば、`player_params.origin_domain`。
1. **エイリアス**には、プレイヤーパラメータに使用するエイリアスとその値を入力します。
1. [**OK**] を選択してください。
AWS Elemental MediaTailor は、**設定エイリアス**セクションのテーブルに新しいパラメータを表示します。
1. 上記のステップを繰り返して、プレイヤーパラメータを追加します。
1. **[保存]** を選択します。
------
#### [ API ]
**API を使用して設定エイリアスを作成するには**
MediaTailor 設定を作成または更新するときは、次の JSON 構造で `ConfigurationAliases`パラメータを使用します。
```
{
"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"
}
}
}
```
------
## ステップ 2: セッション初期化で設定エイリアスを使用する
設定エイリアスをセットアップしたら、セッション開始リクエスト内のドメイン用の置換変数としてそれらを使用できます。これは、セッションのドメインを動的に設定することを可能にします。
**Example 基本設定エイリアスの例**
設定エイリアスと動的ドメイン変数を含む設定の基本的な例を次に示します。
```
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]",
"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"
}
}
}
```
**Example エイリアスによるセッションの初期化**
上記の設定を使用すると、プレイヤー変数とエイリアスを使用したセッション初期化リクエストは次のようになります。
```
POST index.m3u8
{
"playerParams": {
"origin_domain": "pdx",
"region": "pdx",
"endpoint_id": "pdx",
"ad_type": "customized"
}
}
```
MediaTailor は、エイリアス文字列を、設定エイリアスの設定内のマップされた値に置き換えます。
ADS へのリクエストは次のようになります。
```
https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345
```
マニフェストのオリジンへのリクエストは次のようになります。
```
https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd
```
# MediaTailor を使用した設定エイリアスの使用例
次の例は、設定エイリアスを含む完全な MediaTailor 設定、エイリアスを含むセッション初期化リクエスト、およびエイリアスの処理フローを示しています。
**Example エイリアスを使用して設定を完了する**
次の例は、設定エイリアスと動的ドメイン変数を含む完全な設定を示しています。
```
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"
}
}
}
```
**Example エイリアスによるセッションの初期化**
次の例は、プレイヤー変数とエイリアスを指定するセッション初期化リクエストを示しています。
```
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"
}
}
```
**Example パラメータ処理フロー**
次の例では、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 パラメータのリファレンスと制限事項](parameter-comprehensive-reference.md)。
+ 設定エイリアスとドメイン変数については、「」を参照してください[MediaTailor 設定エイリアスの概要](configuration-aliases-overview.md)。
+ ADS リクエストのその他のカスタマイズについては、「」を参照してください[高度な使用法](#variables-advanced-usage)。
**セッションの初期化方法**
MediaTailor は、セッションの初期化とパラメータの受け渡しに複数の方法をサポートしています。
1. **リクエスト本文を含む POST:**
```
POST .m3u8
{
"adsParams": {"param1": "value1", "param2": "value2"},
"playerParams": {"param3": "value3"}
}
```
1. **URL のクエリパラメータ:**
```
GET .m3u8?ads.param1=value1&ads.param2=value2&playerParams.param3=value3
```
**重要**
初期化時に指定できるパラメータは 1 回のみです。設定エイリアスは、転送前に実際の値に解決されます。
**セッションとプレイヤーの情報を ADS に渡す**
1. ADS と連携して、広告クエリに応答するために必要な情報を決定します AWS Elemental MediaTailor。
1. 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]
```
1. プレーヤーで、プレーヤーデータのパラメータを渡すように AWS Elemental MediaTailor のセッション開始リクエストを設定します。セッション開始リクエストにお客様のパラメータを含め、セッションに対する後続のリクエストからそれらのパラメータを省きます。
プレイヤーがセッションを開始するために行う呼び出しのタイプによって、プレイヤー (クライアント) または MediaTailor (サーバー) のどちらがセッションの広告追跡レポートを提供するかが決まります。これらの 2 つのオプションについては、「[広告追跡データの報告](ad-reporting.md)」を参照してください。
サーバー側とクライアント側のどちらの広告追跡レポートが必要かどうかに応じて、以下のいずれかのタイプの呼び出しを行います。どちらの例の呼び出しでも、`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 に置き換えます。プレイヤーからの残りのパラメータは、オリジンサーバーに渡されます。
**Example 広告変数を使用した 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]
```
# ADS およびオリジンの MediaTailor パラメータルーティング
AWS Elemental MediaTailor は、プレフィックスと目的に基づいてクエリパラメータをさまざまな宛先にルーティングします。MediaPackage でのタイムシフト表示などのオリジン固有の機能を実装するには、パラメータルーティングを理解することが重要です。
**パラメータルーティングルール**
MediaTailor は、クエリパラメータに次のルーティングルールを使用します。
+ **オリジンパラメータ (プレフィックスなし):** 特定のプレフィックスのないパラメータは、オリジン固有の機能のためにオリジンサーバーに渡されます。
+ **ADS パラメータ (`ads.` プレフィックス):** プレフィックスが付いたパラメータ`ads.`が広告決定サーバーに送信されます
+ **マニフェストパラメータ (`manifest.` プレフィックス):** プレフィックス が付いたパラメータ`manifest.`が CDN ルーティングと認可に使用されます
**Example パラメータルーティングの例**
次のセッション初期化は、パラメータルーティングを示しています。
```
POST /v1/session/123456789/originId/index.m3u8
{
"adsParams": {
"param1": "value1",
"param2": "value2"
},
"manifestParams": {
"auth_token": "abc123"
}
}
```
この例では、以下のようになっています：
+ `param1` と `param2`は ADS に送信されます。
+ `auth_token` は CDN ルーティングと認可に使用されます
+ プレフィックスのないパラメータはオリジンサーバーに渡されます
## オリジンサーバーパラメータの動作
オリジンサーバーに渡されるパラメータは、タイムシフト表示、コンテンツフィルタリング、認証などのオリジン固有の機能を有効にします。
**一般的なオリジンパラメータのユースケース**
オリジンパラメータは一般的に以下に使用されます。
+ **タイムシフト表示:** MediaPackage タイムシフトコンテンツの `start`および `end`パラメータ
+ **コンテンツ認証:** オリジンサーバーに必要な認証トークン
+ **コンテンツフィルタリング:** 返されるコンテンツバリアントを制御するパラメータ
+ **オリジン固有の機能:** オリジンサーバーがコンテンツ処理に使用するパラメータ
**重要**
パラメータはセッションの初期化時に処理され、セッション全体を通して維持されます。タイムシフトウィンドウなどのパラメータを変更するには、更新された値で新しいセッションを作成する必要があります。
# MediaTailor と MediaPackage のタイムシフト表示統合
AWS Elemental MediaTailor は、タイムシフト表示パラメータを MediaPackage オリジンに渡し、スタートオーバーおよびキャッチアップ表示機能を有効にできます。この統合により、ビューワーは以前の時点からライブコンテンツの視聴を開始できます。
**MediaPackage のタイムシフト表示パラメータ**
MediaPackage は、MediaTailor を介して渡すことができる次のタイムシフト表示パラメータをサポートしています。
+ `start`: タイムシフトされたマニフェストの先頭を定義するエポックまたは ISO 8601 タイムスタンプ
+ `end`: タイムシフトマニフェストの終了を定義するエポックまたは ISO 8601 タイムスタンプ
+ `time_delay`: 指定した秒数でコンテンツの可用性を遅らせる
+ `manifest_window_seconds`: 設定されたウィンドウより短いマニフェストをリクエストする
**Example MediaPackage のタイムシフトされたパラメータを使用した MediaTailor MediaTailor セッションの初期化**
次の例は、タイムシフト表示パラメータを使用してセッションを初期化する方法を示しています。
```
GET /v1/master/123456789/originId/index.m3u8?start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z
```
または、明示的なセッション初期化を使用します。
```
POST /v1/session/123456789/originId/index.m3u8
{
"adsParams": {
"param1": "value1"
}
}
```
追加のクエリパラメータを使用する場合:
```
?start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z
```
**セッション中のパラメータ動作**
タイムシフト表示パラメータには特定の動作特性があります。
+ **セッションの初期化:** セッションの作成時にパラメータが処理されます
+ **パラメータの永続性:** パラメータは再生中もセッションに関連付けられ続けます
+ **初期化後のイミュータブル:** アクティブなセッション中にパラメータを変更することはできません
+ **新しいセッションが必要:** タイムシフトウィンドウを変更するには、更新されたパラメータ値を使用して新しいセッションを作成します。
**MediaPackage のスタートオーバーウィンドウの要件**
MediaPackage でタイムシフト表示を使用するには、以下を確認してください。
1. MediaPackage エンドポイントでスタートオーバーウィンドウを設定する (最大 24 時間)
1. CDN が必要なクエリパラメータを MediaPackage に転送することを確認する
1. CDN キャッシュを改善するために、プレイヤーセッション間で一貫した再生ウィンドウを使用する
1. 開始時刻と終了時刻が設定されたスタートオーバーウィンドウ内に収まることを確認する
**重要**
タイムシフト表示を使用する場合は、各ビューワーに一意の開始時刻または終了時刻を生成するのではなく、プレイヤーセッション間で一貫した再生ウィンドウを使用します。これにより、CDN でのキャッシュが改善され、スロットリングの可能性を回避できます。
MediaPackage のタイムシフト表示設定とパラメータの詳細については、*AWS Elemental MediaPackage 「 ユーザーガイド*」の「 [でのタイムシフト表示 AWS Elemental MediaPackage](https://docs.aws.amazon.com/mediapackage/latest/ug/time-shifted.html)」を参照してください。
# MediaTailor パラメータセッションの動作と永続性
AWS Elemental MediaTailor はセッションの初期化時にパラメータを処理し、セッションライフサイクルを通じてパラメータを維持します。動的パラメータシナリオを実装するには、セッションの動作を理解することが不可欠です。
**セッションの初期化方法**
MediaTailor は、パラメータを使用してセッションを初期化するための複数の方法をサポートしています。
1. **暗黙的なセッション初期化:** 最初のマニフェストリクエストに含まれるパラメータ
```
GET /v1/master/123456789/originId/index.m3u8?manifest.auth_token=abc123&start=2024-08-26T10:00:00Z
```
1. **明示的セッション初期化 (POST):** リクエスト本文で提供されるパラメータ
```
POST /v1/session/123456789/originId/index.m3u8
{
"adsParams": {"param1": "value1"},
"manifestParams": {"auth_token": "abc123"}
}
```
1. **明示的セッション初期化 (GET):** クエリパラメータとして提供されるパラメータ
```
GET /v1/session/123456789/originId/index.m3u8?ads.param1=value1&manifestParams.auth_token=abc123
```
**パラメータの永続性とイミュータビリティ**
MediaTailor パラメータの動作は、次のルールに従います。
+ **1 回限りの仕様:** パラメータはセッションの初期化時に 1 回のみ指定できます
+ **セッション全体の永続性:** パラメータはセッション全体で維持されます
+ **初期化後にイミュータブル:** セッションの作成後にパラメータを変更することはできません
+ **設定エイリアス解決:** エイリアスは送信先に転送する前に実際の値に解決されます
**パラメータ変更シナリオ**
再生中にパラメータを変更するには:
+ **新しいセッションを作成する:** 更新されたパラメータ値を使用して新しいセッションを初期化する
+ **プレイヤーの移行:** プレイヤーを新しいセッションにシームレスに移行する
+ **パラメータ継承:** 変更されていないパラメータを転送して整合性を維持する
**Example タイムシフトパラメータの変更**
を 1 時間のウィンドウから 2 時間のウィンドウに変更するには:
1. 現在のセッション: `start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z`
1. 新しいセッションを作成する: `start=2024-08-26T10:00:00Z&end=2024-08-26T12:00:00Z`
1. プレイヤーを新しいセッション URL に移行する
**重要**
1 つのセッションに対する複数のマルチバリアントプレイリストリクエストは、最初のリクエストの後にパラメータを更新しません。パラメータはセッション期間中変更できません。
# MediaTailor パラメータのリファレンスと制限事項
動的広告変数を設定する前に、すべての MediaTailor 設定に適用されるパラメータフォーマットの要件と制限を理解してください。
AWS Elemental MediaTailor は、マニフェストクエリパラメータと ADS パラメータの両方でパラメータ文字の制限、長さの制限、サポートされている形式に関する包括的な情報を提供します。
## マニフェストクエリパラメータの文字制限
マニフェストクエリパラメータは特定の文字をサポートし、長さの制限が定義されています。
**サポートされている文字 (URL エンコードなし)**
マニフェストクエリパラメータでは、次の文字を直接使用できます。
+ 英数字 (A～Z、a～z、0～9)
+ 期間 (.)
+ ハイフン (-)
+ アンダースコア (\$1)
+ バックスラッシュ (\$1)
**URL エンコードでサポートされている文字**
URL エンコードでは、次の特殊文字がサポートされています。
+ 期間 (.) = %2E
+ ダッシュ (-) = %2D
+ アンダースコア (\$1) = %5F
+ パーセント (%) = %25
+ チルダ (\$1) = %7E
+ スラッシュ (/) = %2F
+ アスタリスク (\$1) = %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 エンコードの問題、設定エイリアスエラーなど、MediaTailor の一般的なパラメータ関連の問題をトラブルシューティングするためのガイダンスを提供します。
## 文字制限エラー
サポートされていない文字を含むパラメータ値は、エラーや予期しない動作を引き起こす可能性があります。
**一般的な症状**
次の症状は、文字制限の問題を示している可能性があります。
+ マニフェスト URLsに表示されないパラメータ
+ セッションの初期化中の HTTP 400 エラー
+ 切り捨てられたパラメータ値または破損したパラメータ値
+ 不正な形式の URLs が原因で ADS リクエストが失敗する
**解決の手順**
文字制限エラーを解決するには:
1. サポートされていない文字のパラメータ値を確認する: `:`、`?`、`&`、`=`、`%`、 `/`
1. 特殊文字に適切な URL エンコードを適用する (「」を参照[MediaTailor パラメータのリファレンスと制限事項](parameter-comprehensive-reference.md))
1. `%%%` や などの二重文字は避けてください。 `==`
1. 完全な URLs
**Example URL エンコードの例**
以下を使用する代わりに、以下を使用します。
```
manifest.redirect_url=https://example.com/path?param=value
```
URL エンコード形式を使用します。
```
manifest.redirect_url=https%3A%2F%2Fexample.com%2Fpath%3Fparam%3Dvalue
```
## 長さ制限エラー
長さ制限を超えるパラメータは切り捨てられたり、エラーが発生する可能性があります。
**長さの制限**
次の長さ制限が適用されます (詳細については[MediaTailor パラメータのリファレンスと制限事項](parameter-comprehensive-reference.md)、「」を参照してください）。
+ マニフェストクエリパラメータ (合計): 2000 文字
+ ADS パラメータ名: 10,000 文字
+ ADS パラメータ値: 25,000 文字
+ ADS URLs: 25,000 文字
**解決戦略**
長さの制限を処理するには:
1. 可能な場合は、より短いパラメータ名と値を使用する
1. 大きなパラメータ値を複数の小さなパラメータに分割する
1. 設定エイリアスを使用して短いエイリアスを長い値にマッピングする (「」を参照[MediaTailor 設定エイリアスの概要](configuration-aliases-overview.md))
1. パラメータリファレンスを含む大規模なデータには外部ストレージを使用することを検討する
## 設定エイリアスエラー
設定エイリアスの問題により、HTTP 400 エラーまたは予期しないパラメータ値が発生する可能性があります。
**一般的な設定エイリアスエラー**
設定エイリアスでは、一般的に次のエラーが発生します。
+ HTTP 400 エラー: エイリアス値がないか、無効です
+ ドメイン変数が正しく解決されない
+ プレイヤーパラメータがエイリアス値に置き換えられていない
**解決策チェックリスト**
設定エイリアスエラーを解決するには:
1. すべてのドメイン変数が として定義されていることを確認します。 `ConfigurationAliases`
1. プレイヤーパラメータ変数が`player_params.`プレフィックスを使用していることを確認する
1. 重要な URLs のドメイン変数 (`VideoContentSourceUrl`、`AdSegmentUrlPrefix`、`ContentSegmentUrlPrefix`) のエイリアス化された値のリストが網羅的であることを確認します。
1. セッション初期化リクエストで有効なエイリアス値が指定されていることを確認します。
1. ConfigurationAliases パラメータの JSON 構造を検証する
トラブルシューティングの詳細なガイダンスについては、「」を参照してください[MediaTailor 設定エイリアスのトラブルシューティングガイド](configuration-aliases-troubleshooting.md)。
**Example 設定エイリアスの検証**
設定に必要なエイリアスがすべて含まれていることを確認します。
```
"ConfigurationAliases": {
"player_params.origin_domain": {
"pdx": "abc.mediapackage.us-west-2.amazonaws.com",
"iad": "xyz.mediapackage.us-east-1.amazonaws.com"
// Must include all possible values used in session initialization
}
}
```
## パラメータ処理フローの問題
パラメータ処理フローを理解すると、パラメータの転送と変換に関する問題のトラブルシューティングに役立ちます。
**パラメータ処理順序**
MediaTailor は、次の順序でパラメータを処理します。
1. セッション初期化パラメータの検証
1. 設定エイリアスの解決 (該当する場合)
1. パラメータフィルタリング (ADS とオリジンとマニフェスト)
1. URL エンコードとフォーマット
1. URLsへのパラメータアプリケーション
**デバッグパラメータフロー**
パラメータ処理の問題をデバッグするには:
1. セッションの初期化でパラメータが正しく指定されていることを確認する
1. 設定エイリアスが期待値に解決することを確認する
1. パラメータが正しい URLs (マニフェスト、ADS、オリジン) に表示されることを確認する
1. URL エンコーディングが正しく適用されていることを確認する
**Example パラメータフローの例**
セッションの初期化:
```
POST master.m3u8
{
"playerParams": {"origin_domain": "pdx"},
"manifestParams": {"test": "123"}
}
```
エイリアスの解決と処理後:
+ オリジンリクエスト: `https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd`
+ マニフェスト URL: `/v1/master/.../index.m3u8?aws.sessionId=session&test=123`
## セキュリティに関する考慮事項とベストプラクティス
MediaTailor は、一般的なセキュリティ問題を防ぐために、パラメータ処理のためのセキュリティ対策を実装します。
**セキュリティ対策**
MediaTailor は、次のセキュリティ対策を実装します。
1. データベースの肥大化を防ぐための入力サイズの制限
1. ユーザー入力の適切なエンコードとサニタイズ
1. レスポンスの破損を防ぐための入力の URL エンコード
**ベストプラクティス**
安全なパラメータ処理については、次のベストプラクティスに従ってください。
+ 送信前にクライアント側でパラメータ値を検証する
+ 設定エイリアスを使用して、可能なパラメータ値を制限する
+ パラメータに機密情報を含めないようにする
+ 異常なパターンがないかパラメータの使用状況をモニタリングする
+ パラメータ値を推奨長さ制限内に維持する
# MediaTailor 設定エイリアスのトラブルシューティングガイド
AWS Elemental MediaTailor は、一般的な設定エイリアスの問題とエラーシナリオに関する体系的なトラブルシューティングガイダンスを提供します。
## 設定エイリアスの検証エラー
設定エイリアスがないか無効である場合、MediaTailor は問題の特定に役立つ特定のエラーレスポンスを返します。
**一般的なエラーシナリオ**
次の表に、一般的な設定エイリアスエラーとその解決手順を示します。
| エラー | 原因 | 解決策 |
| --- | --- | --- |
| HTTP 400: 無効なプレイヤーパラメータエイリアス | ConfigurationAliases にプレイヤーパラメータ値が見つかりません | 対応する ConfigurationAliases マッピングにプレイヤーパラメータ値がキーとして存在することを確認します。 |
| HTTP 400: 必要な設定エイリアスがありません | 対応する ConfigurationAliases エントリなしで使用されるドメイン変数 | 必要なすべてのエイリアスマッピングを使用して、欠落しているプレイヤーパラメータを ConfigurationAliases に追加する |
| HTTP 400: 設定の検証に失敗しました | ConfigurationAliases 構造が正しくないか、不完全です | JSON 構造を検証し、すべてのドメイン変数に対応するエイリアスがあることを確認する |
| URLs の空の文字列置換 | ドメイン以外の変数エイリアスが見つかりません | ConfigurationAliases で欠落しているエイリアスマッピングを追加するか、デフォルト値を指定する |
**検証チェックリスト**
次のチェックリストを使用して、設定エイリアスの設定を検証します。
1. **ドメイン変数カバレッジ:** URLs のドメイン部分で使用されるすべての変数に対応する ConfigurationAliases エントリがあることを確認します。
1. **エイリアスの完全性:** 可能なすべてのプレイヤーパラメータ値がエイリアスマッピングのキーとして含まれていることを確認します。
1. **JSON 構造:** ConfigurationAliases JSON が適切にフォーマットされ、ネストされていることを確認する
1. **パラメータの命名:** すべてのプレイヤーパラメータで `player_params.` プレフィックスが使用されていることを確認します。
1. **値の整合性:** エイリアス値が意図した用途 (URLs、プロファイル名など) に対して有効であることを確認します。
## 設定エイリアスの解決のデバッグ
この体系的なアプローチに従って、設定エイリアス解決の問題をデバッグします。
**Step-by-stepのデバッグ方法**
次の手順を使用して、設定エイリアスの問題を特定して解決します。
**設定エイリアスのデバッグ手順**
1. **設定構造の検証:** 再生設定に正しくフォーマットされた ConfigurationAliases が含まれていることを確認します。
```
{
"ConfigurationAliases": {
"player_params.example_param": {
"alias1": "value1",
"alias2": "value2"
}
}
}
```
1. **プレイヤーパラメータの形式を確認する:** セッションの初期化に正しくフォーマットされたプレイヤーパラメータが含まれていることを確認します。
```
{
"playerParams": {
"example_param": "alias1"
}
}
```
1. **エイリアスマッピングの検証:** プレイヤーパラメータ値 ("alias1") が ConfigurationAliases マッピングのキーとして存在することを確認します。
1. **シンプルな設定でテストする:** 最小限の設定から始めて問題を分離する
1. **エラーレスポンスのモニタリング:** 特定の検証メッセージの MediaTailor エラーレスポンスを確認する
1. **解決URLs の検証:** 最終的な解決済み URLsが有効でアクセス可能であることを確認します。
## 設定エイリアスのベストプラクティス
次のベストプラクティスに従って、信頼性の高い設定エイリアスの実装を確保します。
**セキュリティに関する考慮事項**
設定エイリアスを使用する場合は、次のセキュリティ対策を実装します。
+ **入力検証:** エイリアス解決で使用する前に、すべてのプレイヤーパラメータ値を検証する
+ **エイリアス値のサニタイズ:** エイリアス値に想定される文字と形式のみが含まれていることを確認します。
+ **ドメインの制限:** ドメインエイリアスを信頼できる制御されたドメインに制限する
+ **アクセスコントロール:** 承認された担当者のみに設定変更を制限する
**パフォーマンスの最適化**
次の推奨事項を使用して、設定エイリアスのパフォーマンスを最適化します。
+ **エイリアス数を最小限に抑える:** 必要なエイリアスのみを使用して処理オーバーヘッドを削減する
+ **効率的な命名:** エイリアスとパラメータに明確で一貫した命名規則を使用する
+ **デフォルト値:** 一般的なユースケースに適したデフォルトエイリアスを指定します。
+ **設定キャッシュ:** MediaTailor の設定キャッシュを活用してパフォーマンスを向上させる
**メンテナンスとモニタリング**
次のプラクティスを使用して、信頼性の高い設定エイリアスオペレーションを維持します。
+ **定期的な検証:** すべてのエイリアスマッピングが最新で機能していることを定期的に検証する
+ **エラーモニタリング:** 欠落または無効なエイリアスに関連する HTTP 400 エラーをモニタリングする
+ **ドキュメント:** すべてのエイリアスマッピングとその目的を明確に文書化する
+ **テスト手順:** すべてのエイリアスの組み合わせに対して包括的なテストを実装する
# MediaTailor マニフェストクエリパラメータ
AWS Elemental MediaTailor は、CDN ルーティングと認可用のマニフェストクエリパラメータ、オリジン固有の機能に使用できるその他のクエリパラメータなど、さまざまな目的でクエリパラメータを処理します。
AWS Elemental MediaTailor はセッション初期化からのクエリパラメータを保持し、パーソナライズされたマニフェスト URLsやその他のアセットに追加します。この機能は、MediaTailor とクライアントプレーヤーの間にコンテンツ配信ネットワーク (CDN) がある場合に使用します。
CDN が以下のクエリパラメータを必要とする場合は、マニフェストクエリパラメータを使用します。
+ さまざまな MediaTailor エンドポイントへの動的ルーティング
+ トークン認可
**クライアント側と CDN の動作**
MediaTailor はクライアント側のレポートエンドポイントにクエリパラメータを追加しますが、CDN セグメントには追加しません。更新された機能により、さまざまな MediaTailor アセットのクエリパラメータをより包括的にサポートできるため、CDN ルーティングと認可のユースケースの柔軟性が向上します。
MediaTailor はクライアント側のレポートエンドポイントにクエリパラメータを追加しますが、CloudFront (または他の CDN) セグメントにはクエリパラメータを追加しません。
パラメータの保存を使用するには、[AWS サポート](https://aws.amazon.com/premiumsupport/)に連絡して、マニフェストクエリパラメータのパススルーを有効にするようにリクエストしてください。
動作は、HLS と DASH、および明示的なセッション初期化と暗黙的なセッション初期化によって異なります。以下のトピックでは、MediaTailor がマニフェストにパラメータを渡すようにセッション初期化リクエストを設定する方法について説明します。
# オリジンの MediaTailor クエリパラメータ処理
AWS Elemental MediaTailor は、クエリパラメータの目的に応じて異なる方法でクエリパラメータを処理します。マニフェストクエリパラメータ (プレフィックスは `manifest.`) は CDN のルーティングと認可に使用されますが、オリジン固有の機能には他のクエリパラメータを使用できます。
**MediaPackage によるタイムシフト表示**
MediaPackage のタイムシフト表示機能では、リクエストに `start`および `end`パラメータを含めることができます。これらのパラメータは、スタートオーバーとキャッチアップ表示の特定のコンテンツウィンドウを定義します。
**Example タイムシフト表示リクエスト**
タイムシフト表示のマニフェストリクエストに開始パラメータと終了パラメータを含めます。
```
GET /v1/master/111122223333/originId/index.m3u8?start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z
```
**セッション中のパラメータ動作**
クエリパラメータはセッションの初期化時に処理されます。タイムシフト表示またはその他のオリジン固有の機能の場合:
+ **セッションの初期化:** 最初のマニフェストリクエストに必要なパラメータを含める
+ **パラメータの永続性:** パラメータはセッションに関連付けられ、再生中も維持されます。
+ **パラメータの変更:** タイムシフトウィンドウやその他のパラメータを変更するには、更新された値を使用して新しいセッションを作成します。
**重要**
クエリパラメータの特定の処理は、オリジン設定とコンテンツオリジンがサポートするパラメータによって異なります。MediaPackage 統合の場合、 の説明に従って必要なクエリパラメータを転送するように CDN が設定されていることを確認します[必須クエリパラメータを設定する](mediapackage-integration.md#mediapackage-query-strings)。
# MediaTailor パラメータの文字制限と URL エンコード
AWS Elemental MediaTailor は、マニフェストクエリパラメータで特定の文字をサポートします。特殊文字には URL エンコードを使用できます。
**URL エンコードでサポートされている文字**
URL エンコードでは、次の特殊文字がサポートされています。
+ 期間 (.) = %2E
+ ダッシュ (-) = %2D
+ アンダースコア (\$1) = %5F
+ パーセント (%) = %25
+ チルダ (\$1) = %7E
+ スラッシュ (/) = %2F
+ アスタリスク (\$1) = %2A
+ 等しい (=) = %3D
+ 質問 (?) = %3F
**URL エンコードのサポート**
MediaTailor は、URL エンコード (hello%20world = hello world など) で使用すると、パーセント (%) 記号をサポートします。HTTP 仕様に従って有効な URL エンコードである限り、任意の URL エンコード文字を使用できます。
**重要**
MediaTailor は、%%% や == などの二重文字をサポートしていません。
**セキュリティに関する考慮事項**
MediaTailor は、パラメータ処理に次のセキュリティ対策を実装します。
1. データベースの肥大化を防ぐための入力サイズの制限
1. ユーザー入力の適切なエンコードとサニタイズ
1. レスポンスの破損を防ぐための入力の URL エンコード
**Topics**
+ [オリジンクエリパラメータ](origin-query-parameters.md)
+ [MediaTailor の文字制限](manifest-query-parameters-character-restrictions.md)
+ [MediaTailor HLS の暗黙的なセッション](manifest-query-parameters-hls-implicit-session-initialization.md)
+ [MediaTailor DASH の暗黙的なセッション](manifest-query-parameters-dash-implicit-session-initialization.md)
+ [MediaTailor の明示的なセッション初期化](manifest-query-parameters-hls-and-dash-explicit-session-initialization.md)
+ [MediaTailor のプロトコル固有の動作](manifest-query-parameters-protocol-differences.md)
+ [MediaTailor CDN 統合](manifest-query-parameters-cdn-integration.md)
# MediaTailor HLS 暗黙的なセッションの初期化
AWS Elemental MediaTailor リクエストにキー を持つクエリパラメータが含まれている場合、 は MediaTailor リソースへのリンクにクエリパラメータを含めます`manifest.*`。次の例は、このリクエスト形式を示しています。
```
GET /v1/master/111122223333/originId/index.m3u8?manifest.test=123&other=456
```
リンクには `manifest.` プレフィックスは含まれません。
**HLS のパラメータアプリケーション**
HLS 暗黙的なセッションの場合、MediaTailor はマニフェスト階層の次の場所にパラメータを適用します。
+ 多変量プレイリスト URLs
+ メディアプレイリスト URLs
+ コンテンツセグメント URLs
+ 広告セグメント URLs
+ HLS URLs
**Example マルチバリアントプレイリスト**
次の例は、MediaTailor が多変量プレイリストの URL にクエリパラメータを含める方法を示しています。
```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-MEDIA:LANGUAGE="eng",AUTOSELECT=YES,FORCED=NO,TYPE=SUBTITLES,URI="../../../manifest/111122223333/originId/session/1.m3u8?test=123",GROUP-ID="subtitles",DEFAULT=YES,NAME="caption_1"
#EXT-X-STREAM-INF:CODECS="avc1.640029,mp4a.40.2",AVERAGE-BANDWIDTH=2525657,RESOLUTION=960x540,SUBTITLES="subtitles",FRAME-RATE=29.97,BANDWIDTH=2665212
../../../manifest/111122223333/originId/session/0.m3u8?test=123
```
**Example メディアプレイリスト**
次の例は、MediaTailor がコンテンツセグメントの URLs にクエリパラメータを含める方法を示しています。
```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:28716269
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXTINF:6.006,
https://origin.com/contentSegment_1.ts?originQueryParam=foo&test=123
#EXT-X-DISCONTINUITY
#EXTINF:6.006,
../../../../segment/111122223333/originId/session/0/2?test=123
```
# MediaTailor DASH 暗黙的なセッションの初期化
AWS Elemental MediaTailor はクライアントのセッションを作成し、クライアントがセッションなしでマニフェストリクエストを行うときにクエリパラメータでリダイレクトします。次の例は、このリクエスト形式を示しています。
```
GET /v1/dash/111122223333/originId/index.mpd?manifest.test=123&other=456
```
MediaTailor はクライアントのセッションを作成し、クエリパラメータを使用してリダイレクトします。
```
/v1/dash/111122223333/originId/index.mpd?sessionId=session&test=123
```
**DASH のパラメータアプリケーション**
DASH マニフェストレスポンスには、コンテンツセグメント、広告セグメント、初期化 URLs など、さまざまな場所のクエリパラメータが含まれます。MediaTailor は、以下のパラメータを適用します。
+ DASH マニフェストの場所要素
+ SegmentTemplate 初期化属性
+ SegmentTemplate メディア属性
+ コンテンツセグメント URLs
+ 広告セグメント URLs
クライアントがリクエストを行うと、MediaTailor は次の例のような DASH マニフェストで応答します。最初の期間はコンテンツ期間であるため、MediaTailor はそこにマニフェストクエリパラメータを挿入しません。広告期間である 2 番目の期間では、MediaTailor はマニフェストクエリパラメータを`SegmentTemplate`要素の `initialization` 属性と `media` 属性に挿入します。`Location` 要素には、マニフェストクエリパラメータもあります。
```
https://origin.com/contentSegments/
https://mediatailor.com/v1/dash/111122223333/originId/index.mpd?test=123&aws.sessionId=session