支援的參數 aws.startTime aws.preroll aws.overlayAvails aws.logMode aws.availSuppressionMode

工作階段控制的 MediaTailor 服務變數

AWS Elemental MediaTailor 會為控制工作階段層級行為的服務變數保留aws.查詢參數命名空間。與ads.參數（轉送至 ADS) 和manifest.參數（附加至個人化資訊清單 URLs) 不同，MediaTailor 會直接使用aws.參數，而不會轉送至原始伺服器或 ADS。

支援的參數

下表列出可用來控制工作階段層級行為的aws.*參數。

參數	Type	值	預設	說明
`aws.startTime`	ISO 8601 時間戳記	例如 `2026-06-17T10:00:00Z`	未設定（即時邊緣聯結）	在 DVR 視窗中的特定點啟動工作階段。MediaTailor 會將時間戳記解析為最近的區段界限`EXT-X-START:TIME-OFFSET`，並在 HLS 資訊清單中發出。
`aws.preroll`	字串列舉	`enabled`、 `disabled`（不區分大小寫）	`enabled`	控制工作階段是否發生前導廣告插入。當時`disabled`，即使播放組態具有，也會隱藏前導`LivePreRollConfiguration`。
`aws.overlayAvails`	字串列舉	`on`、 `off`（不區分大小寫）	`on`	控制是否針對工作階段處理浮水印（非線性）廣告時段。當時`off`，會忽略來源資訊清單中的浮水印廣告標記，而且不會插入浮水印廣告。
`aws.logMode`	字串列舉	`DEBUG`, `DISABLED`	`DISABLED`	啟用工作階段的詳細偵錯記錄。設為時`DEBUG`，MediaTailor 會將詳細的工作階段日誌發送到 CloudWatch Logs 進行故障診斷。
`aws.availSuppressionMode`	字串列舉	`OFF`、`BEHIND_LIVE_EDGE`、 `AFTER_LIVE_EDGE`（不區分大小寫）	`OFF`	根據廣告時段相對於即時邊緣的位置，控制廣告時段是否遭到隱藏。
`aws.availSuppressionValue`	持續時間	HH：MM：SS 格式（例如 `00:00:10`)	未設定	時段禁止的時段。當 `availSuppressionMode`為 `BEHIND_LIVE_EDGE`或時為必要`AFTER_LIVE_EDGE`。
`aws.availSuppressionFillPolicy`	字串列舉	`FULL_AVAIL_ONLY`、 `PARTIAL_AVAIL`（不區分大小寫）	`FULL_AVAIL_ONLY`	當模式為時`AFTER_LIVE_EDGE`，會控制是否填充部分隱藏的時段。

aws.startTime

設定 aws.startTime 時，MediaTailor 會在最接近指定程式日期時間的區段界限開始工作階段。

Usage

在資訊清單請求中以查詢參數aws.startTime傳遞：


GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.startTime=2026-06-17T10:00:00Z

或在明確的工作階段初始化中，將其作為不含aws.字首的頂層欄位傳遞：


POST /v1/session/{hashed-account-id}/{origin-id}/{asset}.m3u8

{
    "startTime": "2026-06-17T10:00:00Z"
}

要求

下列需求適用於 aws.startTime：

來源資訊清單必須包含區段上的 EXT-X-PROGRAM-DATE-TIME(PDT)。如果沒有 PDT， aws.startTime就無法解析，且會被忽略。
僅適用於 HLS 即時工作階段 (SSAI 和 SGAI)。

Behavior (行為)

下表說明在不同案例中aws.startTime的行為：

案例	結果
DVR 時段內的時間戳記	從最近的區段界限開始，發出 `EXT-X-START`
早於 DVR 視窗的時間戳記	從窗口夾到 3×targetDuration
3×targetDuration of live edge 內的時間戳記	視為即時邊緣聯結（否 `EXT-X-START`)
即時邊緣或之後的時間戳記	一般即時邊緣聯結
格式化或不格式化 ISO 8601	忽略 – 回到即時邊緣聯結，記錄錯誤
資訊清單沒有 PDT	忽略 – 回到即時邊緣聯結，記錄錯誤
省略參數	預設：一般即時邊緣聯結

綁定行為

如果起點在工作階段中超過 DVR 視窗， EXT-X-START 會從視窗前端固定為 3×targetDuration。3×targetDuration 緩衝區符合 RFC 8216 §6.3.3 播放器緩衝建議。

範例 aws.startTime 的資訊清單輸出

當玩家使用初始化工作階段，aws.startTime=2026-06-17T10:00:00Z且解析的偏移距離即時邊緣 120 秒時，MediaTailor 會發出：


#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-START:TIME-OFFSET=-120.120,PRECISE=YES
#EXT-X-MEDIA-SEQUENCE:500
#EXT-X-PROGRAM-DATE-TIME:2026-06-17T09:58:00.000Z
#EXTINF:6.006,
segment500.ts
#EXTINF:6.006,
segment501.ts
...

會TIME-OFFSET=-120.120告知玩家在最接近所請求開始時間的區段界限，開始在即時邊緣後方播放 120 秒。

限制

有下列限制：

您無法在工作階段初始化後變更此參數。
來源資訊清單中需要 EXT-X-PROGRAM-DATE-TIME 。
EXT-X-START 是玩家提示 – MediaTailor 無法保證所有玩家都遵守。

aws.preroll

當時aws.preroll=disabled，MediaTailor 會抑制工作階段的預導廣告插入，即使播放組態具有 LivePreRollConfiguration。

Usage

在資訊清單請求中以查詢參數aws.preroll傳遞：


GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.preroll=disabled

或在明確的工作階段初始化中，將其作為不含aws.字首的頂層欄位傳遞：


POST /v1/session/{hashed-account-id}/{origin-id}/{asset}.m3u8

{
    "preroll": "disabled"
}

要求

下列需求適用於 aws.preroll：

播放組態必須具有 LivePreRollConfiguration，此參數才能有任何效果。如果未設定前導，則設定此參數不會有任何效果。
適用於 HLS 即時工作階段 (SSAI 和 SGAI)。

Behavior (行為)

下表說明 aws.preroll的行為：

Value	結果
`enabled` （或省略）	像往常一樣插入前導
`disabled`	此工作階段的預先滾動已隱藏
無效值	記錄為錯誤，視為 `enabled`

限制

您無法在工作階段初始化後變更此參數。

aws.overlayAvails

當時aws.overlayAvails=off，MediaTailor 會忽略來源資訊清單中的浮水印（非線性）廣告標記，而不會插入工作階段的浮水印廣告。

Usage

在資訊清單請求中以查詢參數aws.overlayAvails傳遞：


GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.overlayAvails=off

要求

下列需求適用於 aws.overlayAvails：

來源資訊清單必須包含浮水印廣告標記（例如具有浮水印分割類型的 SCTE-35 事件），此參數才會有任何效果。
適用於 HLS 和 DASH、即時和 VOD 工作階段 (SSAI 和 SGAI)。

Behavior (行為)

下表說明 aws.overlayAvails的行為：

Value	結果
`on` （或省略）	重疊時段會照常處理並插入廣告
`off`	會忽略浮水印廣告標記，不會插入浮水印廣告
無效值	記錄為錯誤，視為未指定（預設：`on`)

限制

您無法在工作階段初始化後變更此參數。

aws.logMode

當時aws.logMode=DEBUG，MediaTailor 會啟用工作階段的詳細偵錯記錄。偵錯日誌會傳送到 CloudWatch Logs，並提供資訊清單個人化、廣告決策伺服器請求和工作階段狀態的詳細資訊，有助於疑難排解廣告插入問題。

Usage

在資訊清單請求中以查詢參數aws.logMode傳遞：


GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.logMode=DEBUG

要求

下列需求適用於 aws.logMode：

播放組態必須啟用 (PercentEnabled > 0 或 EnabledLoggingStrategies設定）記錄，才能發出偵錯日誌。
每個客戶的偵錯記錄速率限制，以防止日誌磁碟區過多。

Behavior (行為)

下表說明 aws.logMode的行為方式：

Value	結果
`DEBUG`	為工作階段發出的詳細偵錯日誌
`DISABLED` （或省略）	正常記錄行為（根據播放組態設定）
無效值	擲出錯誤，工作階段初始化失敗

限制

有下列限制：

您無法在工作階段初始化後變更此參數。
值區分大小寫 (DEBUG，而非 debug)。

aws.availSuppressionMode

根據廣告時段相對於即時邊緣的位置，控制廣告時段是否遭到隱藏。使用此選項可略過落在即時邊緣後方或之後時間範圍內的廣告休息時間 – 例如，避免填補檢視器在加入即時串流活動期間已通過的廣告休息時間。

Usage

在資訊清單請求中將時段禁止參數作為查詢參數傳遞：


GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.availSuppressionMode=BEHIND_LIVE_EDGE&aws.availSuppressionValue=00:00:10

此參數適用於兩個配套參數：

aws.availSuppressionValue – 時間範圍（模式不是時需要OFF)
aws.availSuppressionFillPolicy – 控制部分填充行為（僅適用於 AFTER_LIVE_EDGE 模式）

要求

下列要求適用於時段禁止參數：

適用於 HLS 和 DASH 即時工作階段。
aws.availSuppressionValue 當模式為 BEHIND_LIVE_EDGE或時，必須以 HH:MM:SS 格式提供AFTER_LIVE_EDGE。
aws.availSuppressionFillPolicy 只有在模式為時才有效AFTER_LIVE_EDGE。

模式行為

下表說明每個抑制模式的效果：

Mode	Effect
`OFF` （或省略）	無時段禁止 – 所有廣告休息時間皆正常填滿
`BEHIND_LIVE_EDGE`	隱藏在即時邊緣後方指定時段內開始的廣告休息時間
`AFTER_LIVE_EDGE`	從即時邊緣的指定時段之後開始隱藏廣告休息時間

填入政策（僅限 AFTER_LIVE_EDGE)

下表說明模式為時的填充政策行為AFTER_LIVE_EDGE：

填入政策	Effect
`FULL_AVAIL_ONLY` (default)	僅填滿完全在禁止時段外的時段
`PARTIAL_AVAIL`	填滿超出禁止時段的時段部分

範例可用抑制範例

下列請求會抑制即時邊緣後方 10 秒內的廣告休息時間：


GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.availSuppressionMode=BEHIND_LIVE_EDGE&aws.availSuppressionValue=00:00:10

限制

有下列限制：

您無法在工作階段初始化後變更此參數。
aws.availSuppressionValue 模式為時，不得提供 OFF。
中的時間格式無效，aws.availSuppressionValue導致模式回復為 OFF。

您的瀏覽器已停用或無法使用 Javascript。

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

文件慣用形式

網域變數

組態別名

工作階段控制的 MediaTailor 服務變數

支援的參數

aws.startTime

Usage

要求

Behavior (行為)

綁定行為

範例 aws.startTime 的資訊清單輸出

限制

aws.preroll

Usage

要求

Behavior (行為)

限制

aws.overlayAvails

Usage

要求

Behavior (行為)

限制

aws.logMode

Usage

要求

Behavior (行為)

限制

aws.availSuppressionMode

Usage

要求

模式行為

填入政策 （僅限 AFTER_LIVE_EDGE)

範例可用抑制範例

限制

填入政策（僅限 AFTER_LIVE_EDGE)