기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# MediaTailor 매니페스트 쿼리 파라미터
<a name="manifest-query-parameters"></a>

AWS Elemental MediaTailor 는 CDN 라우팅 및 권한 부여를 위한 매니페스트 쿼리 파라미터와 오리진별 기능에 사용할 수 있는 기타 쿼리 파라미터 등 다양한 목적으로 쿼리 파라미터를 처리합니다.

AWS Elemental MediaTailor 는 세션 초기화로부터 쿼리 파라미터를 보존하고 이를 개인화된 매니페스트 URLs 및 기타 자산에 추가합니다. MediaTailor와 클라이언트 플레이어 사이에 콘텐츠 전송 네트워크(CDN)가 있는 경우이 기능을 사용합니다.

CDN에 다음에 대한 쿼리 파라미터가 필요한 경우 매니페스트 쿼리 파라미터를 사용합니다.
+ 다른 MediaTailor 엔드포인트로 동적 라우팅
+ 토큰 권한 부여

**클라이언트 측 동작과 CDN 동작 비교**  
MediaTailor는 클라이언트 측 보고 엔드포인트에 대한 쿼리 파라미터를 추가하지만 CDN 세그먼트에는 추가하지 않습니다. 업데이트된 기능은 다양한 MediaTailor 자산에서 쿼리 파라미터에 대한 보다 포괄적인 지원을 제공하여 CDN 라우팅 및 권한 부여 사용 사례의 유연성을 향상시킵니다.

MediaTailor는 클라이언트 측 보고 엔드포인트에 대한 쿼리 파라미터를 추가하지만 CloudFront(또는 기타 CDN) 세그먼트에 대한 쿼리 파라미터는 추가하지 않습니다.

파라미터 보존을 사용하려면 [AWS Support](https://aws.amazon.com/premiumsupport/)에 문의하여 해당 매니페스트 쿼리 파라미터 전달 활성화를 요청합니다.

동작은 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

**URL 인코딩 지원**  
MediaTailor는 URL 인코딩에 사용할 때 백분율(%) 기호를 지원합니다(예: hello%20world = hello world). HTTP 사양에 따라 유효한 URL 인코딩인 경우 URL 인코딩된 문자를 사용할 수 있습니다.

**중요**  
MediaTailor는 %%% 또는 ==와 같은 이중 문자를 지원하지 않습니다.

**보안 고려 사항**  
MediaTailor는 파라미터 처리를 위해 다음과 같은 보안 조치를 구현합니다.

1. 데이터베이스 팽창을 방지하기 위한 입력 크기 제한

1. 사용자 입력의 적절한 인코딩 및 삭제

1. 응답 손상을 방지하기 위한 입력의 URL 인코딩

**Topics**
+ [오리진 쿼리 파라미터](origin-query-parameters.md)
+ [MediaTailor 문자 제한](manifest-query-parameters-character-restrictions.md)
+ [MediaTailor HLS 암시적 세션](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 CDN 통합](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가 다변량 재생 목록의 URL에 쿼리 파라미터를 포함하는 방법을 보여줍니다.  

```
#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

클라이언트가 요청을 하면 MediaTailor는 다음 예와 유사한 DASH 매니페스트를 사용하여 응답합니다. 첫 번째 기간은 콘텐츠 기간이므로 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 는 클라이언트가 명시적 세션 초기화 요청을 할 때 다변량 재생 목록에를 쿼리 파라미터`manifestParams`로 포함하고 응답에 URLs을 추적합니다.

**세션 초기화 방법**  
명시적 세션 초기화의 경우 요청 본문에 POST를 사용하거나 쿼리 파라미터에 GET을 사용할 수 있습니다.

1. **요청 본문이 있는 POST:**

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

1. **쿼리 파라미터를 사용한 GET:**

   ```
   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는 첫 번째 요청 후 매니페스트 쿼리 파라미터를 업데이트하지 않습니다.

**파라미터 처리 흐름**  
초기화 시 파라미터를 한 번만 지정할 수 있습니다. 구성 별칭은 전달하기 전에 실제 값으로 확인됩니다. 예:는 ConfigurationAliases 구성을 `ad_type=abc12345` 기반으로 로 `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 init URLs에 적용됨 | SegmentTemplate 초기화 속성에 적용됨 | 
| 세션 처리 | 재생 목록 업데이트 전반에 보존된 파라미터 | 세션 연속성을 위해 MPD 위치 요소에 포함된 파라미터 | 
| 광고 세그먼트 처리 | 미디어 재생 목록의 광고 세그먼트 URLs에 적용됨 | 광고 기간 SegmentTemplate 미디어 속성에 적용됨 | 

**파라미터 애플리케이션 위치**  
MediaTailor는 매니페스트 쿼리 파라미터를 다음 위치에 적용합니다.

## HLS 파라미터 애플리케이션
<a name="hls-parameter-application"></a>

HLS 스트림의 경우 MediaTailor는 매니페스트 쿼리 파라미터를 다음에 적용합니다.
+ **다변량 재생 목록 URLs:** 미디어 재생 목록 참조에 파라미터가 추가됩니다.
+ **미디어 재생 목록 URLs:** 파라미터는 미디어 재생 목록 내의 세그먼트 URLs에 포함됩니다.
+ **콘텐츠 세그먼트 URLs:** 모든 콘텐츠 세그먼트에는 매니페스트 쿼리 파라미터가 포함됩니다.
+ **광고 세그먼트 URLs** 
+ **HLS 초기화 URLs:** 스트림에 있는 경우 Init 세그먼트에 파라미터 포함
+ **슬레이트 세그먼트 URLs:** 슬레이트 콘텐츠에는 일관된 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 Location 요소:** Location 요소에는 매니페스트 새로 고침 요청에 대한 파라미터가 포함됩니다.
+ **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. **세그먼트 요청:** 일관된 CDN 동작을 위해 모든 세그먼트 URLs에 파라미터가 포함됩니다.

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
   ```