本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # ADS 請求的 MediaTailor 動態廣告變數 AWS Elemental MediaTailor 使用動態廣告變數，將資訊從檢視工作階段傳遞至廣告決策伺服器 (ADS)。此資訊有助於 ADS 為您的瀏覽者選取最相關的廣告。 本節提供動態廣告變數的概觀，以及特定實作指南的連結。如需step-by-step組態說明，請參閱下列個別主題。 **動態變數類型** MediaTailor 支援四種類型的動態變數： + **工作階段變數** – 自動產生的值，例如工作階段 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 當您設定 AWS Elemental MediaTailor 在範本 ADS URL 中指定本節中列出的一或多個變數時， 會將工作階段資料傳送至廣告決策伺服器 (ADS)。您可以使用個別變數，也可以串連多個變數來建立單一值。MediaTailor 會產生一些值，並從資訊清單和玩家的工作階段初始化請求等來源取得其餘值。 下表說明您可以在範本 ADS 請求 URL 組態中使用的工作階段資料變數。表格中列出的區段編號對應至 2019a 版本的纜線電信工程師協會 (SCTE)-35 規格、[數位節目插入提示訊息](https://account.scte.org/standards/library/catalog/scte-35-digital-program-insertion-cueing-message/)，如需廣告預先擷取的詳細資訊，請參閱 [預先擷取廣告](prefetching-ads.md)。 | 名稱 | 可用於廣告預先擷取 | SCTE-35 規格區段 | Description | | --- | --- | --- | --- | | [avail.index] | 是 | | 代表索引中廣告時段位置的數字。在播放工作階段開始時，MediaTailor 會在資訊清單中建立所有廣告時段的索引，並儲存工作階段其餘部分的索引。當 MediaTailor 向 ADS 提出請求以填滿時段時，它會包含廣告時段索引號碼。此參數可讓 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 | MediaTailor 從 SCTE-35 欄位 剖析的值avail\$1num，以長數字表示。MediaTailor 可以使用此值來指定線性廣告時段號碼。值必須是整數。 | | [scte.avails\$1expected] | 是 | 9，7.2.1 | 選用的長值，提供目前事件內的預期時段計數。 | | [scte.delivery\$1not\$1restricted\$1flag] | 是 | 10.3.3.1 | 選用的布林值。當此值為 0 時，會保留接下來的五個位元。當此值為 1 時，接下來的五個位元會採用 SCTE-35 規格中所述的意義。 | | [scte.device\$1restrictions] | 是 | 10.3.3.1 | 選用整數值，可發出三個預先定義、獨立和非階層的裝置群組訊號。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 segment\$1expected 描述。 | | [scte.event\$1id] | 是 | 9.1 和 9.7.2.1 | MediaTailor 從 SCTE-35 欄位 剖析的值splice\$1event\$1id，以長數字表示。MediaTailor 使用此值來指定線性廣告時段號碼或填入廣告伺服器查詢字串，例如廣告裝置位置。值必須是整數。 | | [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/zh_tw/mediatailor/latest/ug/variables-session.html) | | [scte.segmentation\$1upid.assetId] | 是 | | 與 Podbuster 工作流程segmentation\$1 upid\$1type的受管私有 UPID (0xC) 搭配使用。MediaTailor 會從 MPU 的 private\$1data JSON 結構中的 assetId 參數衍生此值。如需詳細資訊，請參閱[Managed Private UPID JSON structure for a podbuster workflow](#podbuster-workflow)。 | | [scte.segmentation\$1upid.cueData.key] | 是 | | 與 Podbuster 工作流程segmentation\$1 upid\$1type的受管私有 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] | 是 | | 與 Podbuster 工作流程segmentation\$1 upid\$1type的受管私有 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] | 是 | | 搭配 受管私有 UPID (0xC) segmentation\$1upid\$1type用於目標式廣告工作流程。MediaTailor 會分割冒號分隔的分段 UPID 權杖，並建立索引工作階段變數。索引對應於冒號分隔清單中的位置，忽略初始冒號的前導空格。例如，如果 `segmentation_upid = ":3213214:2313321/5:3943"`，則： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/variables-session.html) 值可以是字串。 | | [scte.segments\$1expected] | 是 | 10.3.3.1 | 選用整數值，提供區段集合中個別區段的預期計數。如需此變數的詳細資訊，請參閱 SCTE-35 規格中的 segment\$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 | MediaTailor 從 SCTE-35 splice\$1insert 欄位 剖析的整數值unique\$1program\$1id。ADS 會使用唯一計畫 ID (UPID) 以提供鎖定即時線性串流的計畫層級廣告。如果 SCTE-35 命令不是接合插入，MediaTailor 會將此值設為空值。值必須是整數。 | | [session.avail\$1duration\$1ms] | 是 | | 廣告可用性插槽的持續時間，以毫秒為單位。預設值為 300，000 毫秒。從輸入資訊清單中 AWS Elemental MediaTailor 取得持續時間值，如下所示： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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，因此它可用於預期要與請求關聯以獲得單一檢視的 ADS 欄位。 | | [session.referer] | 否 | | 通常，託管影片播放器的頁面 URL。MediaTailor 將此變數設定為播放器在對 MediaTailor 的請求中使用的Referer標頭值。如果播放器不提供此標頭，MediaTailor 會保留[session.referer]空白。如果您在資訊清單端點前面使用內容交付網路 (CDN) 或代理，並且希望此變數出現，請在此處從玩家代理正確的標頭。 | | [session.user\$1agent] | 否 | | MediaTailor 從玩家的工作階段初始化請求收到的User-Agent標頭。如果您在資訊清單端點之前使用 CDN 或 Proxy，您必須從此處的播放器代理正確的標頭。 | | [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/zh_tw/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 中 AWS Elemental MediaTailor 指定`player_params.`變數時， 會將從播放器接收的資料傳送至 ADS。例如，如果玩家在其請求`user_id`中將名為 的查詢參數傳送至 MediaTailor，若要在 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 收到工作階段初始化請求時，它會先將值解碼一次，再將其替換為 ADS 請求 URL。 **注意** 如果您的 ADS 需要 URL 編碼的值，請在播放器上將該值以 URL 編碼兩次。如此一來，MediaTailor 完成的解碼會產生 ADS 的一次性編碼值。 例如，如果傳送到 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 會在收到玩家請求時解碼參數。對於用戶端報告，不會變更 JSON 承載中收到的參數。MediaTailor 會將下列請求傳送至 ADS： ``` https://my.ads.com/?param1=value1:¶m2=value2: ``` 以此方式，`param1` 和 `param2` 索引鍵-值組會包含在 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中的網域變數提出請求，而這些 URL 未指定動態變數或使用無效的別名，則請求會失敗並顯示 HTTP `400` 狀態碼。非關鍵欄位 (`SlateAdUrl`、`TranscodeProfileName`、緩衝區 URLs) 會記錄警告，但不會讓請求失敗。 **遺失別名的備用行為** 找不到組態別名或組態別名無效時，MediaTailor 會實作下列備用行為： + **網域變數：**如果網域變數別名遺失或無效，請求會失敗並顯示 HTTP 400 狀態碼。所有網域變數都必須定義有效的別名。 + **非網域變數：**對於 URLs 的非網域部分中使用的變數 （例如路徑元素或查詢參數），缺少別名會導致空字串取代。 + **組態驗證：**MediaTailor 會驗證組態建立和更新操作期間是否存在所有必要的別名。 ## 步驟 1：建立組態別名 若要使用 MediaTailor 主控台建立用於網域取代的組態別名，請執行下列程序。 ------ #### [ Console ] **使用主控台建立組態別名** 1. 在 https：//[https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/) 開啟 MediaTailor 主控台。 1. 在**組態頁面上的組態別名**區段中，選擇**新增玩家參數**。 **** 1. 針對**玩家參數**，輸入您要用作動態變數的玩家參數名稱。例如 `player_params.origin_domain`。 1. 針對**別名**，輸入您要用於玩家參數的別名及其值。 1. 選擇**確定**。 AWS Elemental MediaTailor 會在**組態別名**區段的表格中顯示新參數。 1. 重複上述步驟以新增更多玩家參數。 1. 選擇**儲存**。 ------ #### [ API ] **使用 API 建立組態別名** 當您建立或更新 MediaTailor 組態時，請使用 `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" } } } ``` ------ ## 步驟 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 ``` **重要** 初始化時，您只能指定參數一次。組態別名會在轉送之前解析為實際值。 **將工作階段和播放器資訊傳遞至 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 （伺服器） 是否提供工作階段的廣告追蹤報告。如需關於這兩個選項的詳細資訊，請參閱[報告廣告追蹤資料](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 中的變數 AWS Elemental MediaTailor 取代為工作階段資料和玩家的`ads`參數。它會從播放器將其餘的參數傳遞至原始伺服器。 **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`：定義時間轉移資訊清單開頭的 Epoch 或 ISO 8601 時間戳記 + `end`：定義時間轉移資訊清單結尾的 Epoch 或 ISO 8601 時間戳記 + `time_delay`：將內容可用性延遲指定的秒數 + `manifest_window_seconds`：請求短於設定時段的資訊清單 **Example 使用 MediaPackage 時間轉移參數的 MediaTailor 工作階段初始化 MediaPackage** 下列範例示範如何使用時間轉移檢視參數初始化工作階段： ``` 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 參數行為遵循下列規則： + **一次性規格：**參數只能在工作階段初始化時指定一次 + **工作階段整體持續性：**參數會在整個工作階段中維護 + **初始化後不可變：**建立工作階段後無法修改參數 + **組態別名解析：**別名在轉送到目的地之前解析為實際值 **參數修改案例** 若要在播放期間修改參數： + **建立新的工作階段：**使用更新的參數值初始化新的工作階段 + **玩家轉換：**將玩家無縫轉換至新工作階段 + **參數繼承：**轉送不變的參數以維持一致性 **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 **重要** 單一工作階段的多個多變量播放清單請求不會在第一個請求後更新參數。參數在工作階段持續時間內保持不變。 # 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 編碼支援** 當您在 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 提供在 MediaTailor 中疑難排解常見參數相關問題的指引，包括字元限制、URL 編碼問題和組態別名錯誤。 ## 字元限制錯誤 包含不支援字元的參數值可能會導致錯誤或意外行為。 **常見症狀** 下列症狀可能表示角色限制問題： + 未出現在資訊清單 URLs中的參數 + 工作階段初始化期間的 HTTP 400 錯誤 + 截斷或損毀的參數值 + ADS 請求因 URL 格式錯誤而失敗 URLs **解決步驟** 若要解決字元限制錯誤： 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 會傳回特定錯誤回應，以協助識別問題。 **常見錯誤案例** 下表說明常見的組態別名錯誤及其解決步驟： | 錯誤 | 原因 | Resolution | | --- | --- | --- | | 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 錯誤 + **文件：**維護所有別名映射及其目的的明確文件 + **測試程序：**實作所有別名組合的完整測試