MediaTailor 參數參考 MediaTailor 組態別名 MediaTailor 傳遞 ADS 參數 MediaTailor 疑難排解別名

MediaTailor 動態廣告變數

AWS Elemental MediaTailor 對廣告決策伺服器 (ADS) 的請求包含目前檢視工作階段的相關資訊。此資訊有助於 ADS 選擇要在回應中提供的最佳廣告。當您在 MediaTailor 組態中設定 ADS 範本時，您可以包含動態變數，也稱為巨集。動態變數是可取代的字串。

動態變數可以採用下列形式：

靜態值 – 不會從一個工作階段變更為下一個工作階段的值。例如，MediaTailor 從 ADS 預期的回應類型。
網域變數 – 可用於 URL 網域的動態變數，例如 URL https：//my-ads-server.com。 http://my-ads-server.com 如需詳細資訊，請參閱MediaTailor 網域變數。
工作階段資料 – MediaTailor 為每個工作階段提供的動態值，例如工作階段 ID。如需詳細資訊，請參閱MediaTailor 工作階段變數。
玩家資料 – 由玩家為每個工作階段提供的動態值。這些描述內容檢視器，並協助 ADS 判斷 MediaTailor 應該拼接到串流中的廣告。如需詳細資訊，請參閱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 編碼支援

當您在 URL 編碼中使用 MediaTailor 時，支援百分比 (%) 符號（例如，hello%20world = hello world)。您可以使用任何 URL 編碼字元，只要它們是根據 HTTP 規格有效的 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 現在支援作為 ads和的替代方案adsParams，以改善 API 一致性。

遺失別名的備用行為

找不到組態別名或組態別名無效時，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

重要

初始化時，您只能指定參數一次。組態別名會在轉送之前解析為實際值。

將工作階段和播放器資訊傳遞至 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 （伺服器）是否為工作階段提供廣告追蹤報告。如需關於這兩個選項的詳細資訊，請參閱報告廣告追蹤資料。

根據您需要的是伺服器或用戶端廣告追蹤報告，進行以下其中一個類型的呼叫。在這兩個範例呼叫中，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 中的變數 AWS Elemental MediaTailor 取代為工作階段資料和玩家的ads參數。它會從播放器將其餘的參數傳遞至原始伺服器。

範例具有廣告變數的 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 會傳回特定錯誤回應，以協助識別問題。

常見錯誤案例

下表說明常見的組態別名錯誤及其解決步驟：

錯誤	原因	Resolution
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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

有條件廣告

MediaTailor 參數疑難排解