支持的参数 AWS.startTime aws.preroll AWS.OverlayVails AWS.LogMode aws.avai SuppressionMode

MediaTailor 用于会话控制的服务变量

AWS Elemental MediaTailor 为控制会话级行为的服务变量保留aws.查询参数命名空间。与ads.参数（转发到 ADS）和manifest.参数（附加到个性化清单 URL）不同，aws.参数由源服务器或 ADS 直接使用 MediaTailor ，不会转发到源服务器或 ADS。

支持的参数

下表列出了可用于控制会话级别行为的aws.*参数。

参数	Type	值	默认值	说明
`aws.startTime`	ISO 8601 时间戳	例如，`2026-06-17T10:00:00Z`	未设置（实时加入）	在 DVR 窗口的特定时刻启动会话。 MediaTailor 将时间戳解析为最近的分段边界并在 HLS 清单`EXT-X-START:TIME-OFFSET`中发出。
`aws.preroll`	String enum	`enabled`，`disabled`（不区分大小写）	`enabled`	控制是否在会话中插入前置广告。当时`disabled`，即使回放配置有，预先播放也会被抑制。`LivePreRollConfiguration`
`aws.overlayAvails`	String enum	`on`，`off`（不区分大小写）	`on`	控制是否为会话处理叠加（非线性）和可用空间。当时`off`，源清单中的叠加广告标记将被忽略，不会插入叠加广告。
`aws.logMode`	String enum	`DEBUG`, `DISABLED`	`DISABLED`	为会话启用详细的调试日志。设置为时`DEBUG`，向日志 MediaTailor 发送详细的会话 CloudWatch 日志以进行故障排除。
`aws.availSuppressionMode`	String enum	`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`	String enum	`FULL_AVAIL_ONLY`，`PARTIAL_AVAIL`（不区分大小写）	`FULL_AVAIL_ONLY`	当模式为时`AFTER_LIVE_EDGE`，控制是否填充部分抑制的空白区域。

AWS.startTime

设置后，在aws.startTime距离指定程序日期时间最近的分段边界处 MediaTailor 启动会话。

用量

在清单请求中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）。

行为

下表描述了在不同场景中的aws.startTime行为：

场景	结果
DVR 窗口内的时间戳	从最近的分段边界开始，发射 `EXT-X-START`
时间戳早于 DVR 窗口	从窗口头夹紧到 3×目标持续时间
时间戳在实时边缘的 3x 目标持续时间内	视作实时边缘联接（否）`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

用量

在清单请求中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）。

行为

下表描述了aws.preroll行为方式：

值	结果
`enabled`（或省略）	Pre-roll 像往常一样插入
`disabled`	Pre-roll 在此会话中已禁用
值无效	记录为错误，视为 `enabled`

限制

会话初始化后，您无法更改此参数。

AWS.OverlayVails

当aws.overlayAvails=off， MediaTailor 忽略源清单中的叠加（非线性）广告标记，并且不会为会话插入叠加广告。

用量

在清单请求中aws.overlayAvails作为查询参数传递：


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

要求

以下要求适用于aws.overlayAvails：

要使此参数生效，来源清单必须包含叠加广告标记（例如，具有叠加分段类型 SCTE-35 的事件）。
适用于 HLS 和 DASH、直播和 VOD 会话（包括 SSAI 和 SGAI）。

行为

下表描述了aws.overlayAvails行为方式：

值	结果
`on`（或省略）	我们照常处理叠加广告并插入广告
`off`	叠加广告标记被忽略，没有插入叠加广告
值无效	记录为错误，视为未指定（默认值：`on`）

限制

会话初始化后，您无法更改此参数。

AWS.LogMode

当时aws.logMode=DEBUG，为会话 MediaTailor 启用详细的调试日志记录。调试日志发送到日 CloudWatch 志，提供有关清单个性化、广告决策服务器请求和会话状态的详细信息，这对于解决广告插入问题很有用。

用量

在清单请求中aws.logMode作为查询参数传递：


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

要求

以下要求适用于aws.logMode：

播放配置必须启用（PercentEnabled > 0或EnabledLoggingStrategies配置）日志记录才能发出调试日志。
调试日志记录对每个客户都有速率限制，以防止日志量过大。

行为

下表描述了aws.logMode行为方式：

值	结果
`DEBUG`	为会话发出的详细调试日志
`DISABLED`（或省略）	正常的记录行为（基于播放配置设置）
值无效	引发错误，会话初始化失败

限制

适用以下限制：

会话初始化后，您无法更改此参数。
值区分大小写（DEBUG，不区分debug）。

aws.avai SuppressionMode

控制是否根据广告相对于实时边缘的位置对其进行抑制。使用它可以跳过落在直播边缘之后或之后的时间窗口内的广告插播时间，例如，避免填充观众在活动中途加入直播时已经经过的广告插播时间。

用量

在清单请求中将空闲抑制参数作为查询参数传递：


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	效果
`OFF`（或省略）	抑制无济于事 — 所有广告插播时间均正常填充
`BEHIND_LIVE_EDGE`	抑制在指定时间窗口内在实时边缘后面开始的广告插播时间
`AFTER_LIVE_EDGE`	从实时边缘隐藏在指定时间窗口之后开始的广告插播时间

填写政策（仅限 AFTER_LIVE_EDGE）

下表描述了模式为时的填充策略行为AFTER_LIVE_EDGE：

填写政策	效果
`FULL_AVAIL_ONLY`（默认值）	仅填充完全处于抑制窗口之外的可用空间
`PARTIAL_AVAIL`	填补空余地中超出抑制窗口的部分

例无效抑制示例

以下请求会在 Live Edge 后的 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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

域变量

配置别名