本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 清单筛选
<a name="manifest-filtering"></a>

使用清单筛选， AWS Elemental MediaPackage 可以根据您在附加到播放请求的查询中指定的参数动态生成客户端清单。这使您能够从一个端点执行某些操作，比如限制观看者对优质 4K HEVC 内容的访问，或定位特定设备类型和音频采样率范围。以前，您必须配置多个端点才能完成此行为。 MediaPackage 现在提供了一种经济实惠的方式，可以在同一个端点上动态生成不同的客户端清单。

## 使用清单筛选条件
<a name="working-with-manifest-filters"></a>

使用清单筛选条件时，生成的清单仅包括与您在查询中指定的特征匹配的音频流和视频流。如果未使用清单筛选条件，则所有接收的流都会出现在终端节点输出流中。例外情况是，如果您已为终端节点设置流筛选条件，例如最小视频比特率。在这种情况下，清单筛选条件会在流筛选条件之后应用，这可能会使输出偏斜，因而不建议使用。

清单筛选可用于以下支持的所有终端节点类型 MediaPackage：
+ Apple HLS
+ DASH-ISO
+ Microsoft Smooth Streaming
+ CMAF

要使用清单筛选，请将`aws.manifestfilter`查询参数附加到您的播放请求中。 MediaPackage MediaPackage 评估查询，并根据这些查询参数提供客户端清单。清单查询*不* 区分大小写，长度最多为 1024 个字符。如果查询格式不正确，或者它没有与查询参数匹配的流，则 MediaPackage 返回不完整的清单或空清单。有关查询语法，请参阅以下部分。

**注意**  
如果使用 Apple HLS 或 CMAF 端点，则需要满足特殊条件。有关这些条件的信息，请参阅[HLS 和 CMAF 清单的特殊条件](#special-conditions-HLS-CMAF-manifests)。

**查询语法**  
基本查询参数为 `aws.manifestfilter`，后跟可选参数名称和值对。要构造查询，请在 MediaPackage 端点 URL 的末尾附加`?aws.manifestfilter=`参数名称和值。有关所有可用参数的列表，请参阅[清单筛选条件查询参数](#manifest-filter-query-parameters)。

Apple HLS 筛选条件查询可能如下所示：

`https://example-mediapackage-endpoint.mediapackage.us-west-2.amazonaws.com/out/v1/examplemediapackage/index.m3u8{{?aws.manifestfilter=audio_sample_rate:0-44100;video_bitrate:0-2147483647;video_codec:h265;audio_language:fr,en-US,de}}`

下表列出了查询语法。


| 查询字符串组件 | 说明 | 
| --- | --- | 
| ? | 标记查询开始的受限字符。 | 
| aws.manifestfilter= | 基本查询，后跟由名称和值对构造的参数。有关所有可用参数的列表，请参阅[清单筛选条件查询参数](#manifest-filter-query-parameters)。 | 
| : | 用于将参数名称与值关联。例如 {{parameter\_name}}:{{value}}。 | 
| ; | 在包含多个参数的查询中分隔参数。例如 {{parameter1\_name:value}};{{parameter2\_name:minValue-maxValue}}。 | 
| , | 分隔值的列表。例如 parameter\_name:{{value1}},{{value2}},{{value3}}。列表中以逗号分隔的值表示存在 OR 关系。 | 
| - | 用于定义参数的最小值-最大值范围。例如 audio\_sample\_rate:0-44100。当数值用在范围中时，数值将包含在范围定义中。这意味着流必须大于或等于最小值，并且小于或等于最大值。对于范围，最小值和最大值是必需的。支持的范围值为 0 - 2147483647。 | 

**注意**  
如果您使用 Amazon CloudFront 作为 CDN，则可能需要设置其他配置。有关更多信息，请参阅[为所有终端节点配置缓存行为](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/live-streaming.html#live-streaming-with-mediapackage-create-cache-behavior)。

## 清单筛选条件查询参数
<a name="manifest-filter-query-parameters"></a>

MediaPackage 支持以下查询参数。


| 类别 | Name | 说明 | 示例 | 
| --- | --- | --- | --- | 
| 音频 | audio\_bitrate |  +  音频比特率（单位：比特/秒）。 <br />+  **可接受的值**：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 `0` - `2147483647`。   | stream.mpd?aws.manifestfilter=audio\_bitrate:0-2147483647 | 
| 音频 | audio\_channels |  +  音频通道数。 <br />+  **可接受的值**：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 `1` - `32767`。   | stream.mpd?aws.manifestfilter=audio\_channels:1-8 | 
| 音频 | audio\_codec |  +  音频编解码器类型。 <br />+  **可接受的值**：`AACL`、`AACH`、`AC-3` 和 `EC-3`。对于 `AC-3` 和 `EC-3`，您必须包括 `-`。 <br />值*不* 区分大小写。   | stream.mpd?aws.manifestfilter=audio\_codec:AACL,AC-3 | 
| 音频 | audio\_language |  +  从编码器直通 (passthrough) 派生的音频语言或功能代码。 <br />+  **可接受的值**：任意字符串，如两字符或四字符 [ISO-639-1](https://www.andiamo.co.uk/resources/iso-language-codes/) 语言代码。您必须使用为编码器设置的相同语言字符串。 <br />值*不* 区分大小写。   | stream.mpd?aws.manifestfilter=audio\_language:fr,en-US,de | 
| 音频 | audio\_sample\_rate |  +  音频采样率（单位：Hz）。 <br />+  **可接受的值**：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 `0` - `2147483647`。   | stream.mpd?aws.manifestfilter=audio\_sample\_rate:0-44100 | 
| 子标题 | subtitle\_language |  +  从编码器传递派生的字幕语言或功能代码。 <br />+  **可接受的值**：任意字符串，如两字符或四字符 [ISO-639-1](https://www.andiamo.co.uk/resources/iso-language-codes/) 语言代码。您必须使用为编码器设置的相同语言字符串。 <br />值*不* 区分大小写。   | stream.mpd?aws.manifestfilter=subtitle\_language:en-US, hi | 
| 视频 | trickplay\_height |  +  trick-play 映像的高度（单位：像素）。适用于仅限 I-frame 和基于映像的 trick-play。  如果将此参数与仅限 I-frame 一起使用，`trickplay_height` 和 `video_height` 应具有相似的值。如果值不同，则可能会从清单中删除仅限 I-frame 轨道。  <br />+  在对 VOD 进行 DASH 时，会在平铺之前应用 `trickplay_height` 筛选器。 <br />+  **可接受的值**：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 `1` - `2147483647`。   | stream.mpd?aws.manifestfilter=trickplay\_height:200-1200 | 
| 视频 | trickplay\_type |  +  trickplay 轨道类型。您可以对 iframe 或映像 trickplay 轨道进行筛选，也可以使用值 `none` 筛选掉所有 trickplay 轨道（iframe 和映像）。 <br />+  **可接受的值**：`iframe`、`image` 和 `none`。 <br />值*不* 区分大小写。   | stream.mpd?aws.manifestfilter=trickplay\_type:iframe | 
| 视频 | video\_bitrate |  +  视频比特率（单位：比特/秒）。  如果您使用此参数，我们建议您仅使用 `video_bitrate` 筛选条件参数来设置视频比特率。也不要通过 MediaPackage 主机设置视频比特率的最小和最大值，或者 AWS CLI。`video_bitrate` 筛选条件应用于在终端节点上创建的视频比特率设置。如果您使用参数并在控制台或中设置比特率 AWS CLI，则输出可能会出现偏差。  <br />+  **可接受的值**：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 `0` - `2147483647`。 <br />+   您不能将此参数用于 trick-play 流。    | stream.mpd?aws.manifestfilter=video\_bitrate:0-2147483647 | 
| 视频 | video\_codec |  +  视频编解码器类型。 <br />+  **可接受的值**： `H264`、`H265`。 <br />值*不* 区分大小写。   | stream.mpd?aws.manifestfilter=video\_codec:h264 | 
| 视频 | video\_dynamic\_range |  +  视频动态范围。 <br />+  **可接受的值**：`hdr10`、`hlg` 和 `sdr`。 <br />值*不* 区分大小写。   | stream.mpd?aws.manifestfilter=video\_dynamic\_range:hdr10 | 
| 视频 | video\_framerate |  +  NTSC 格式的视频帧速率范围。 <br />+  **可接受的值**：用短划线连接的两个浮点数，用于定义包含的范围（含两端的值）。每个浮点数最多可以有三个可选的小数值。例如，`29.97` 或 `29.764`。支持的范围值为 `1` - `999.999`。   | stream.mpd?aws.manifestfilter=video\_framerate:23.976-30 | 
| 视频 | video\_height |  +  视频的高度，以像素为单位。  如果将此参数与仅限 I-frame 一起使用，`trickplay_height` 和 `video_height` 应具有相似的值。如果值不同，则可能会从清单中删除仅限 I-frame 轨道。  <br />+  **可接受的值**：用短划线聚合的两个整数，用于定义包含的范围（含两端的值）。支持的范围值为 `1` - `32767`。   | stream.mpd?aws.manifestfilter=video\_height:720-1080 | 

## 清单筛选示例
<a name="manifest-filtering-examples"></a>

这些是清单筛选示例。

**Example 1：确定目标为支持 AVC 和 44.1k 音频采样率的播放器**  
查看器正在仅支持 AVC 和 44.1k 音频采样率的设备上播放内容。您可以设置 `video_codec` 和 `audio_sample_rate` 以筛选掉不符合这些要求的流。

`?aws.manifestfilter=audio_sample_rate:0-44100;video_codec:h264`

**Example 2：限制 4K HEVC 内容**  
您的 4K HEVC 流是 15 Mbps，所有其他流都小于 9 Mbps。要从流集中排除 4K 流，您可以将阈值设置为每秒 9,000,000 位，以筛选掉更高的比特率。

`?aws.manifestfilter=video_bitrate:0-9000000`

**Example 3：包括帧速率在每秒 23.976 到 30 之间的视频**  
要只包含特定帧速率范围内的视频，请使用 `video_framerate`。此参数接受最多具有三个可选小数值的浮点数。

`?aws.manifestfilter=video_framerate:23.976-30`

## HLS 和 CMAF 清单的特殊条件
<a name="special-conditions-HLS-CMAF-manifests"></a>

如果您使用的是 HLS 或 CMAF 清单，则这些特殊条件适用。
+ 对于 HLS 清单，我们强烈建议您使用音频渲染组，以避免删除与筛选掉的音频流进行多路复用的视频流。有关副本组的更多信息，请参阅[格式副本组引用于 AWS Elemental MediaPackage](rendition-groups.md)。
+ 在 HLS 和 CMAF 清单中，不会发出音频采样率信号，因此不容易直观地检查此设置的原始清单或筛选后的清单。要验证音频采样率，请检查编码器级别和输出级别的音频采样率。
+ 在 HLS 和 CMAF 清单中，变体的 `BANDWIDTH` 属性将音频轨道的带宽与视频轨道相关联，无论它是与视频轨道多路复用，还是它为由视频轨道引用的音频轨道。因此，您无法直观地检查原始清单和筛选的清单来确认 `video_bitrate` 筛选条件是否正常工作。要验证筛选条件，请检查编码器级别和输出级别的视频比特率。
+ 对于 HLS 和 CMAF 清单，附加到比特率播放列表或分段的请求参数会导致 HTTP 400 错误。

## 错误条件
<a name="error-conditions-and-handling"></a>

如果清单或片段包含无效或未知的查询参数，则某些播放设备将返回错误。以下是 MediaPackage 可以处理的查询参数：
+ `m`
+ `start`
+ `end`
+ `aws.manifestfilter`
+ `aws.drmsettings`

如果您的查询参数不是列出的参数，请使用诸如 Amazon 之类的 CDN CloudFront 来删除不必要的参数。有关更多信息，请参阅 *Amazon CloudFront 开发者指南*中的[基于查询字符串参数缓存内容](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html)。

下表包含其他常见错误情况。


****  

| 错误条件 | 示例 | HTTP 状态代码 | 
| --- | --- | --- | 
| 列表参数未找到且不是约束列表的一部分 | ?aws.manifestfilter=audio\_language:dahlia | 200 | 
| 流中只存在字幕流 | ?aws.manifestfilter=audio\_sample\_rate:0-1;video\_bitrate=0-1 | 200 | 
| 重复的筛选条件参数 | ?aws.manifestfilter=audio\_sample\_rate:0-48000;aws.manifestfilter=audio\_sample\_rate:0-48000 | 400 | 
| 参数无效 | ?aws.manifestfilter=donut\_type:rhododendron | 400 | 
| 范围参数无效 | ?aws.manifestfilter=audio\_sample\_rate:300-0 | 400 | 
| 范围值无效（大于 INT\_MAX） | ?aws.manifestfilter=audio\_sample\_rate:0-2147483648 | 400 | 
| 查询字符串格式错误 | ?aws.manifestfilter=audio\_sample\_rate:is:0-44100 | 400 | 
| 参数字符串大于 1024 个字符 | ?aws.manifestfilter=audio\_language:abcdef.... | 400 | 
| HLS 或 CMAF 比特率清单上的查询参数 | index\_1.m3u8?aws.manifestfilter=video\_codec:h264 | 400 | 
| 分段请求上的查询参数 | ...\_1.[ts\|mp4\|vtt..]?aws.manifestfilter=video\_codec:h264 | 400 | 
| 重复的查询参数 | ?aws.manifestfilter=audio\_sample\_rate:0-48000;aws.manifestfilter=video\_bitrate:0-1 | 400 | 
| 应用筛选条件会导致空清单（内容中没有可满足查询字符串中所定义的条件的流） | ?aws.manifestfilter=audio\_sample\_rate:0-1;video\_bitrate=0-1 | 400 |