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

# MediaTailor 清单查询参数
<a name="manifest-query-parameters"></a>

AWS Elemental MediaTailor 处理用于不同目的的查询参数：用于 CDN 路由和授权的清单查询参数，以及可用于源特定功能的其他查询参数。

AWS Elemental MediaTailor 保留会话初始化的查询参数并将其附加到个性化清单 URLs 和其他资产。当您在客户端播放器之间有内容分发网络 (CDN) 时 MediaTailor ，请使用此功能。

当您的 CDN 需要以下内容的查询参数时，请使用清单查询参数：
+ 动态路由到不同的 MediaTailor 端点
+ 令牌授权

**客户端行为与 CDN 行为**  
MediaTailor 为客户端报告端点添加查询参数，但不会为 CDN 分段附加查询参数。更新后的功能为各种 MediaTailor 资产的查询参数提供了更全面的支持，增强了 CDN 路由和授权用例的灵活性。

MediaTailor 为客户端报告端点添加查询参数，但它不会为 CloudFront （或其他 CDN）细分追加查询参数。

要使用参数保存，请联系 [AWS S](https://aws.amazon.com/premiumsupport/) upport，请求启用清单查询参数通过。

在 HLS 和 DASH 之间，以及显式和隐式会话初始化之间，行为会有所不同。以下主题介绍如何配置会话初始化请求，以便将参数 MediaTailor 传递到清单：

# MediaTailor 原点的查询参数处理
<a name="origin-query-parameters"></a>

AWS Elemental MediaTailor 根据查询参数的用途，对查询参数的处理方式有所不同。清单查询参数（前缀为`manifest.`）用于 CDN 路由和授权，而其他查询参数可用于源特定功能。

**时移观看 MediaPackage**  
要使用时移查看功能 MediaPackage，您可以在请求中包含`start`和`end`参数。这些参数定义了特定的内容窗口，用于从头到尾查看和追赶查看。

**Example 时移观看请求**  
在清单请求中加入开始和结束参数，以便进行时移查看：  

```
GET /v1/master/111122223333/originId/index.m3u8?start=2024-08-26T10:00:00Z&end=2024-08-26T11:00:00Z
```

**会话期间的参数行为**  
查询参数在会话初始化时处理。对于时移观看或其他特定于原点的功能：
+ **会话初始化：**在初始清单请求中包含必需的参数
+ **参数持久性：**参数与会话相关联，并在整个播放过程中保持不变
+ **更改参数：**要修改时移窗口或其他参数，请使用更新的值创建一个新会话

**重要**  
查询参数的具体处理取决于您的来源配置和内容来源支持的参数。要进行 MediaPackage 集成，请确保您的 CDN 已配置为转发必要的查询参数，如中所述。[配置基本查询参数](mediapackage-integration.md#mediapackage-query-strings)

# MediaTailor 参数字符限制和 URL 编码
<a name="manifest-query-parameters-character-restrictions"></a>

AWS Elemental MediaTailor 支持清单查询参数中的特定字符。您可以对特殊字符使用 URL 编码。

**支持的带有 URL 编码的字符**  
URL 编码支持以下特殊字符：
+ 时期 (.) = %2E
+ 短划线 (-) = %2D
+ 下划线 (\$1) = %5F
+ 百分比 (%) = %25
+ 波浪号 (\$1) = %7E
+ 正斜杠 (/) = %2F
+ 星号 (\$1) = %2A
+ 等于 (=) = %3D
+ 问题 (？) = %3F

**网址编码支持**  
MediaTailor 当你在 URL 编码中使用百分号 (%) 时（例如，hello%20world = hello world = hello world），则支持该符号。您可以使用任何 URL 编码字符，只要它们是符合 HTTP 规范的有效 URL 编码即可。

**重要**  
MediaTailor 不支持双字符，例如%%% 或 ==。

**安全注意事项**  
MediaTailor 为参数处理实现了以下安全措施：

1. 防止数据库膨胀的输入大小限制

1. 对用户输入进行适当的编码和审查

1. 对输入进行网址编码，以防止响应损坏

**Topics**
+ [来源查询参数](origin-query-parameters.md)
+ [MediaTailor字符限制](manifest-query-parameters-character-restrictions.md)
+ [MediaTailorHLS 隐式会话](manifest-query-parameters-hls-implicit-session-initialization.md)
+ [MediaTailor DASH 隐式会话](manifest-query-parameters-dash-implicit-session-initialization.md)
+ [MediaTailor 显式会话初始化](manifest-query-parameters-hls-and-dash-explicit-session-initialization.md)
+ [MediaTailor特定于协议的行为](manifest-query-parameters-protocol-differences.md)
+ [MediaTailor 内容分发网络集成](manifest-query-parameters-cdn-integration.md)

# MediaTailor HLS 隐式会话初始化
<a name="manifest-query-parameters-hls-implicit-session-initialization"></a>

AWS Elemental MediaTailor 如果您的请求包含带有密钥的查询参数，则在 MediaTailor 资源链接中包含查询参数`manifest.*`。以下示例显示了这种请求格式：

```
GET /v1/master/111122223333/originId/index.m3u8?manifest.test=123&other=456
```

链接不包含前`manifest.`缀。

**HLS 中的参数应用**  
对于 HLS 隐式会话，将参数 MediaTailor 应用于清单层次结构中的以下位置：
+ 多变体播放列表 URLs
+ 媒体播放列表 URLs
+ 内容细分 URLs
+ 广告细分 URLs
+ HLS 初始化 URLs

**Example 多变播放列表**  
以下示例显示了如何在多变体播放列表的网址中 MediaTailor 包含查询参数：  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-MEDIA:LANGUAGE="eng",AUTOSELECT=YES,FORCED=NO,TYPE=SUBTITLES,URI="../../../manifest/111122223333/originId/session/1.m3u8?test=123",GROUP-ID="subtitles",DEFAULT=YES,NAME="caption_1"
#EXT-X-STREAM-INF:CODECS="avc1.640029,mp4a.40.2",AVERAGE-BANDWIDTH=2525657,RESOLUTION=960x540,SUBTITLES="subtitles",FRAME-RATE=29.97,BANDWIDTH=2665212
../../../manifest/111122223333/originId/session/0.m3u8?test=123
```

**Example 媒体播放列表**  
以下示例显示了如何在中 MediaTailor 包含内容分段 URLs的查询参数：  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:28716269
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXTINF:6.006,
https://origin.com/contentSegment_1.ts?originQueryParam=foo&test=123
#EXT-X-DISCONTINUITY
#EXTINF:6.006,
../../../../segment/111122223333/originId/session/0/2?test=123
```

# MediaTailor DASH 隐式会话初始
<a name="manifest-query-parameters-dash-implicit-session-initialization"></a>

AWS Elemental MediaTailor 为客户端创建会话，并在客户端在没有会话的情况下发出清单请求时使用查询参数重定向该会话。以下示例显示了这种请求格式：

```
GET /v1/dash/111122223333/originId/index.mpd?manifest.test=123&other=456
```

MediaTailor 为客户端创建会话并使用查询参数重定向该会话：

```
/v1/dash/111122223333/originId/index.mpd?sessionId=session&test=123
```

**DASH 中的参数应用**  
DASH 清单响应包括不同位置的查询参数，包括内容细分、广告细分和初始化 URLs。 MediaTailor 将参数应用于以下内容：
+ DASH 清单位置元素
+ SegmentTemplate 初始化属性
+ SegmentTemplate 媒体属性
+ 内容细分 URLs
+ 广告细分 URLs

当客户端发出请求时，会使用类似于以下示例的 DASH 清单进行 MediaTailor 响应。第一个句点是内容周期，因此 MediaTailor 不要在那里插入清单查询参数。在第二个时段（即广告时段）中，将清单查询参数 MediaTailor插入`SegmentTemplate`元素的`initialization`属性和`media`属性中。该`Location`元素还具有清单查询参数。

```
<?xml version="1.0" encoding="UTF-8"?>
<MPD availabilityStartTime="2018-07-27T09:48:23.634000+00:00" id="201" minBufferTime="PT30S" minimumUpdatePeriod="PT15S" profiles="urn:mpeg:dash:profile:isoff-live:2011" publishTime="2023-02-14T23:37:43" suggestedPresentationDelay="PT25.000S" timeShiftBufferDepth="PT56.997S" type="dynamic" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd">
    <BaseURL>https://origin.com/contentSegments/</BaseURL>
    <Location>https://mediatailor.com/v1/dash/111122223333/originId/index.mpd?test=123&aws.sessionId=session</Location>
    <Period duration="PT29.963S" id="28737823" start="PT143732873.178S">
        <AdaptationSet bitstreamSwitching="true" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <Representation bandwidth="2200000" codecs="avc1.640029" frameRate="30000/1001" height="540" id="1" width="960">
                <SegmentTemplate initialization="index_video_7_0_init.mp4?m=1611174111" media="index_video_7_0_$Number$.mp4?m=1611174111" presentationTimeOffset="4311986195351" startNumber="28737828" timescale="30000">
                    <SegmentTimeline>
                        <S d="180180" t="4311986911066"/>
                        <S d="3003" t="4311987091246"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
        </AdaptationSet>
    </Period>
    <Period id="28737829_1" start="PT39925H48M23.141S">
        <BaseURL>https://mediatailor.com/v1/dashsegment/111122223333/originId/session/28737829/28737829_1/</BaseURL>
        <AdaptationSet bitstreamSwitching="false" frameRate="30000/1001" mimeType="video/mp4" segmentAlignment="true" startWithSAP="1" subsegmentAlignment="true" subsegmentStartsWithSAP="1">
            <SegmentTemplate startNumber="1" timescale="90000"/>
            <Representation bandwidth="2200000" codecs="avc1.64001f" height="540" id="1" width="960">
                <SegmentTemplate initialization="asset_540_2_0init.mp4?test=123" media="asset_540_2_0_$Number%09d$.mp4?test=123" startNumber="1" timescale="90000">
                    <SegmentTimeline>
                        <S d="180180" r="6" t="0"/>
                        <S d="87087" t="1261260"/>
                    </SegmentTimeline>
                </SegmentTemplate>
            </Representation>
        </AdaptationSet>
    </Period>
</MPD>
```

# MediaTailor HLS 和 DASH 显式会话初始化
<a name="manifest-query-parameters-hls-and-dash-explicit-session-initialization"></a>

AWS Elemental MediaTailor 在多变播放列表中包含 a `manifestParams` s query 参数，并在客户端发出显式会话初始化请求时的响应 URLs 中进行跟踪。

**会话初始化方法**  
对于显式会话初始化，你可以使用带有请求正文的 POST 或带有查询参数的 GET：

1. **带有请求正文的 POST：**

   ```
   POST /v1/session/111122223333/originId/index.m3u8
   {
       "adsParams": {"param1": "value1", "param2": "value2", "param3": "value3"},
       "manifestParams": {"test": "123"}
   }
   ```

1. **使用查询参数获取：**

   ```
   GET /v1/session/111122223333/originId/index.m3u8?ads.param1=value1&ads.param2=value2&manifestParams.test=123
   ```

**Example 会话初始化请求**  

```
POST /v1/session/111122223333/originId/index.m3u8
{
    "adsParams": {
        "param1": "value1",
        "param2": "value2",
        "param3": "value3"
    },
    "manifestParams": { 
        "test": "123"
    },
    "reportingMode": "client"
}
```

**Example 清单和追踪响应**  

```
{
    "manifestUrl": "/v1/master/111122223333/originId/index.m3u8?aws.sessionId=session&test=123",
    "trackingUrl": "/v1/tracking/111122223333/originId/session?test=123"
}
```

会话的清单响应的具体内容与前面描述`manifestParams`的隐式会话初始化工作流程 MediaTailor URLs 类似。关键区别在于，显式会话初始化的清单参数不是以开头的`manifest.`。

清单查询参数是不可变的，您只能在会话初始化时进行设置。如果客户端为单个会话发出多个多变体播放列表请求，则 MediaTailor 不会在第一个请求之后更新清单查询参数。

**参数处理流程**  
在初始化时，只能指定一次参数。在转发之前，配置别名会解析为实际值。例如：`ad_type=abc12345`根据 ConfigurationAliases配置`player_params.ad_type=customized`解析为。

# MediaTailor 特定于协议的参数行为
<a name="manifest-query-parameters-protocol-differences"></a>

AWS Elemental MediaTailor 对于 HLS 和 DASH 协议，对清单查询参数的处理方式有所不同。每种协议类型都有特定的应用位置和处理方法。

**HLS 与 DASH 参数处理对比**  
下表比较了如何 MediaTailor 处理 HLS 和 DASH 协议中的清单查询参数：


| 方面 | HLS 行为 | 达世币行为 | 
| --- | --- | --- | 
| 参数应用 | 直接应用于清单 URLs 和区段 URLs | 应用于位置元素、 SegmentTemplate 属性和区段 URLs | 
| 清单层次结构 | 多变体播放列表 → 媒体播放列表 → 片段 | MPD → 时期 AdaptationSets → 陈述 | 
| 初始化 URLs | 存在时应用于 HLS 初始化 URLs  | 应用于 SegmentTemplate 初始化属性 | 
| 会话处理 | 播放列表更新期间保留的参数 | MPD 位置元素中包含的用于会话连续性的参数 | 
| 广告细分处理 | 应用于媒体播放列表 URLs 中的广告区段 | 应用于广告周期 SegmentTemplate 媒体属性 | 

**参数应用程序位置**  
MediaTailor 将清单查询参数应用于以下位置：

## HLS 参数应用程序
<a name="hls-parameter-application"></a>

对于 HLS 流， MediaTailor 将清单查询参数应用于：
+ **多变播放列表 URLs：**参数附加到媒体播放列表引用中
+ **媒体播放列表 URLs：**参数包含在媒体播放列表的片段 URLs 中
+ **内容分段 URLs：**所有内容区段都包含清单查询参数
+ **广告细分 URLs：**广告区段接收用于 CDN 路由和授权的参数
+ **HLS 初始化 URLs：**Init 分段包含流中存在的参数
+ **Slate 片段 URLs：**Slate 内容包括用于一致 CDN 行为的参数

**Example HLS 参数应用示例**  
鉴于会话初始化：  

```
GET /v1/master/123456789/originId/index.m3u8?manifest.auth_token=abc123&manifest.region=us-west
```
多变播放列表包含媒体播放列表参考中的参数：  

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=2665212,RESOLUTION=960x540
../../../manifest/123456789/originId/session/0.m3u8?auth_token=abc123&region=us-west
```
媒体播放列表包含片段中的参数 URLs：  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:7
#EXTINF:6.006,
https://origin.com/segment1.ts?auth_token=abc123&region=us-west
#EXTINF:6.006,
../../../../segment/123456789/originId/session/0/2?auth_token=abc123&region=us-west
```

## DASH 参数应用程序
<a name="dash-parameter-application"></a>

对于 DASH 直播， MediaTailor 将清单查询参数应用于：
+ **MPD 位置元素：**位置元素包括清单刷新请求的参数
+ **SegmentTemplate 初始化属性：**Init 段 URLs 包含参数
+ **SegmentTemplate 媒体属性：**媒体片段 URL 模板包含参数
+ **内容区段 URLs：**根据模板生成的所有内容区段都包含参数
+ **广告细分 URLs：**广告周期细分包含 CDN 集成的参数
+ **服务器端举报重定向：**302 重定向到广告细分会保留参数

**Example DASH 参数应用示例**  
鉴于会话初始化：  

```
GET /v1/dash/123456789/originId/index.mpd?manifest.auth_token=abc123&manifest.region=us-west
```
DASH 清单包含多个位置的参数：  

```
<MPD>
    <Location>https://mediatailor.com/v1/dash/123456789/originId/index.mpd?auth_token=abc123&region=us-west&aws.sessionId=session</Location>
    <Period>
        <AdaptationSet>
            <Representation>
                <SegmentTemplate 
                    initialization="init.mp4?auth_token=abc123&region=us-west" 
                    media="segment_$Number$.mp4?auth_token=abc123&region=us-west"/>
            </Representation>
        </AdaptationSet>
    </Period>
</MPD>
```

# MediaTailor CDN 集成和参数路由
<a name="manifest-query-parameters-cdn-integration"></a>

AWS Elemental MediaTailor 清单查询参数支持复杂的 CDN 集成场景。您可以将它们用于动态路由、授权和负载平衡。

**CDN 路由用例**  
受益于清单查询参数的常见 CDN 集成场景包括：
+ **地理路由：**根据查看者的位置将请求路由到特定区域的 MediaTailor 终端节点
+ **基于令牌的授权：**通过 CDN 将授权令牌传递给， MediaTailor 以实现安全的内容访问
+ **负载平衡：**使用 CDN 路由逻辑在多个 MediaTailor 端点之间分配流量
+ **A/B 测试：**将不同的用户分段路由到不同的 MediaTailor 配置进行测试
+ **设备特定优化：**根据设备类型或功能路由请求

**在 CDN 层之间保留参数**  
MediaTailor 确保在多个 CDN 层和请求类型中保留清单查询参数：

1. **初始请求：**参数是从会话初始化请求中提取的

1. **清单生成：**参数应用于清单 URLs 中的所有相关内容

1. **分段请求：**所有分段中都包含参数， URLs 以实现一致的 CDN 行为

1. **广告插入：在广告插入**和区段替换期间会保留参数

**Example CDN 授权流程**  
以下示例演示了使用清单查询参数的完整的 CDN 授权流程：  

1. 客户端请求以授权令牌出现：

   ```
   GET https://cdn.example.com/mediatailor/v1/master/123456789/originId/index.m3u8?manifest.auth_token=jwt_token_here&manifest.user_id=12345
   ```

1. CDN MediaTailor 使用以下参数将请求转发给：

   ```
   GET https://mediatailor.amazonaws.com/v1/master/123456789/originId/index.m3u8?manifest.auth_token=jwt_token_here&manifest.user_id=12345
   ```

1. MediaTailor 生成将参数应用于所有内容的清单 URLs：

   ```
   #EXTM3U
   #EXT-X-STREAM-INF:BANDWIDTH=2665212
   ../../../manifest/123456789/originId/session/0.m3u8?auth_token=jwt_token_here&user_id=12345
   ```

1. 后续的分段请求包括用于 CDN 授权的参数：

   ```
   GET https://cdn.example.com/mediatailor/segment/123456789/originId/session/0/1?auth_token=jwt_token_here&user_id=12345
   ```