本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # GetHLSStreamingSessionURL 擷取串流的 HTTP 即時串流 (HLS) URL。然後，您可以在瀏覽器或媒體播放器中開啟 URL，以檢視串流內容。 `StreamName` 和 `StreamARN` 參數都是選用的，但您必須在叫用此 API 操作`StreamARN`時指定 `StreamName`或 。 Amazon Kinesis 影片串流對於透過 HLS 提供資料有下列需求： + [影片播放軌跡需求](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/video-playback-requirements.html)。 + 資料保留必須大於 0。 + 每個片段的視訊軌必須包含 H.264 格式的編解碼器私有資料 (AVC) 或 H.265 格式的 HEVC ([MPEG-4 規格 ISO/IEC 14496-15](https://www.iso.org/standard/55980.html))。如需將串流資料轉換為特定格式的相關資訊，請參閱 [NAL Adaptation Flags](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-reference-nal.html)。 + 每個片段的音軌 （如果有） 必須包含 AAC 格式的轉碼器私有資料 ([AAC 規格 ISO/IEC 13818-7](https://www.iso.org/standard/43345.html))。 Kinesis Video Streams HLS 工作階段包含分段 MPEG-4 格式 （也稱為 fMP4 或 CMAF) 或 MPEG-2 格式 （也稱為 HLS 規格也支援的 TS 區塊） 的片段。如需 HLS 片段類型的詳細資訊，請參閱 [HLS 規格](https://tools.ietf.org/html/draft-pantos-http-live-streaming-23)。 下列程序說明如何搭配 Kinesis Video Streams 使用 HLS： 1. 呼叫 `GetDataEndpoint` API 以取得端點。然後使用 [--endpoint-url 參數](https://docs.aws.amazon.com/cli/latest/reference/)將`GetHLSStreamingSessionURL`請求傳送至此端點。 1. 使用 擷取 HLS URL`GetHLSStreamingSessionURL`。Kinesis Video Streams 會建立 HLS 串流工作階段，用於使用 HLS 通訊協定存取串流中的內容。 `GetHLSStreamingSessionURL`會傳回工作階段 HLS *主播放清單* （使用 HLS 串流所需的根資源） 的已驗證 URL （包括加密工作階段字符）。 **注意** 不要在未經授權的實體可以存取它的地方共用或存放此字符。權杖可讓您存取串流的內容。使用與 AWS 登入資料相同的量值來保護字符。 透過播放清單提供的媒體僅包含請求的串流、時間範圍和格式。不提供其他媒體資料 （例如請求視窗外的影格或替代位元速率）。 1. 將 HLS 主播放清單的 URL （包含加密工作階段字符） 提供給支援 HLS 通訊協定的媒體播放器。Kinesis Video Streams 透過主播放清單 URL 提供 HLS 媒體播放清單、初始化片段和媒體片段。初始化片段包含串流的轉碼器私有資料，以及設定視訊或音訊解碼器和轉譯器所需的其他資料。媒體片段包含 H.264 編碼的影片影格或 AAC 編碼的音訊範例。 1. 媒體播放器會正常接收已驗證的 URL 並請求串流中繼資料和媒體資料。當媒體播放器請求資料時，它會呼叫下列動作： + **GetHLSMasterPlaylist：**擷取 HLS 主播放清單，其中包含每個軌跡`GetHLSMediaPlaylist`的動作 URL，以及媒體播放器的其他中繼資料，包括估計位元速率和解析度。 + **GetHLSMediaPlaylist：**擷取 HLS 媒體播放清單，其中包含使用 `GetMP4InitFragment`動作存取 MP4 初始化片段的 URL，以及使用 `GetMP4MediaFragment`動作存取 MP4 媒體片段的 URLs。HLS 媒體播放清單也包含播放器播放所需的串流中繼資料，例如 `PlaybackMode`是 `LIVE`還是 `ON_DEMAND`。對於具有 `PlaybackType`的工作階段，HLS 媒體播放清單通常是靜態的`ON_DEMAND`。HLS 媒體播放清單會持續更新為具有 `PlaybackType`之工作階段的新片段`LIVE`。視訊音軌和音訊音軌 （如果適用） 有不同的 HLS 媒體播放清單，其中包含特定音軌的 MP4 媒體 URLs。 + **GetMP4InitFragment：**擷取 MP4 初始化片段。媒體播放器通常會先載入初始化片段，再載入任何媒體片段。此片段包含「`fytp`」和「`moov`」MP4 原子，以及初始化媒體播放器解碼器所需的子原子。 初始化片段不會對應至 Kinesis 影片串流中的片段。它只包含串流和個別軌道的轉碼器私有資料，媒體播放器需要這些資料來解碼媒體影格。 + **GetMP4MediaFragment：**擷取 MP4 媒體片段。這些片段包含「`moof`」和「`mdat`」MP4 原子及其子原子，其中包含編碼片段的媒體影格及其時間戳記。 **注意** 每個片段中包含的轉碼器私有資料 (CPD) 包含轉碼器特定的初始化資訊，例如影格速率、解析度和編碼描述檔，這些是正確解碼片段所需的資訊。對於 TS 和 MP4，串流工作階段期間支援 CPD 變更。因此，工作階段中的片段在 CPD 中可以有不同的資訊，而不會中斷播放。對於每個串流工作階段，僅允許 500 個 CPD 變更。 **重要** 不支援追蹤變更。追蹤在整個查詢媒體中必須保持一致。如果串流中的片段從只有視訊變更為同時擁有音訊和視訊，或者 AAC 音軌變更為 A-Law 音軌，則串流將會失敗。 使用此動作擷取的資料可計費。如需相關資訊，請參閱 [ 定價](https://aws.amazon.com/kinesis/video-streams/pricing/)。 + **GetTSFragment：**擷取 MPEG TS 片段，其中包含串流中所有軌道的初始化和媒體資料。 **注意** 如果 `ContainerFormat`是 `MPEG_TS`，則會使用此 API 而非 `GetMP4InitFragment`和 `GetMP4MediaFragment`來擷取串流媒體。 使用此動作擷取的資料可計費。如需詳細資訊，請參閱 [Kinesis Video Streams 定價](https://aws.amazon.com/kinesis/video-streams/pricing/)。 不得在玩家之間共用串流工作階段 URL。如果多個媒體播放器共用工作階段，服務可能會調節工作階段。如需連線限制，請參閱 [Kinesis Video Streams 配額](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)。 您可以透過監控 `GetMP4MediaFragment.OutgoingBytes`Amazon CloudWatch 指標來監控媒體播放器使用的資料量。如需使用 CloudWatch 監控 Kinesis Video Streams 的資訊，請參閱[監控 Kinesis Video Streams](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/monitoring.html)。如需定價資訊，請參閱 [Amazon Kinesis Video Streams 定價](https://aws.amazon.com/kinesis/video-streams/pricing/)和[AWS 定價](https://aws.amazon.com/pricing/)。同時收取 HLS 工作階段和傳出 AWS 資料的費用。 請參閱 文件指南中的影片播放範例： [使用 AWS CLI 擷取 HLS 串流工作階段 URL](hls-playback.md#retrieve-hls-url)和 [範例：在 HTML 和 JavaScript 中使用 HLS](hls-playback.md#how-hls-ex1)。 如需 HLS 的詳細資訊，請參閱 [Apple 開發人員](https://developer.apple.com)網站上的 [HTTP 即時串流](https://developer.apple.com/streaming/)。 **重要** 如果在叫用 Kinesis Video Streams 封存媒體 API 後擲出錯誤，除了 HTTP 狀態碼和回應內文之外，還包含下列資訊： `x-amz-ErrorType` HTTP 標頭 – 除了 HTTP 狀態碼提供的內容之外，還包含更具體的錯誤類型。 `x-amz-RequestId` HTTP 標頭 – 如果您想要向 報告問題 AWS，支援團隊可以根據請求 ID 更好地診斷問題。 HTTP 狀態碼和 ErrorType 標頭都可以用來對錯誤是否可以重試和在何種條件下進行程式設計決策，並提供用戶端程式設計人員可能需要採取的動作的相關資訊，以便成功重試。 如需詳細資訊，請參閱本主題底部的**錯誤**區段，以及[常見錯誤](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/CommonErrors.html)。 ## 請求語法 ``` POST /getHLSStreamingSessionURL HTTP/1.1 Content-type: application/json { "ContainerFormat": "string", "DiscontinuityMode": "string", "DisplayFragmentTimestamp": "string", "Expires": number, "HLSFragmentSelector": { "FragmentSelectorType": "string", "TimestampRange": { "EndTimestamp": number, "StartTimestamp": number } }, "MaxMediaPlaylistFragmentResults": number, "PlaybackMode": "string", "StreamARN": "string", "StreamName": "string" } ``` ## URI 請求參數 請求不會使用任何 URI 參數。 ## 請求主體 請求接受採用 JSON 格式的下列資料。 ** [ContainerFormat](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 指定應該用於封裝媒體的格式。指定`FRAGMENTED_MP4`容器格式會將媒體封裝為 MP4 片段 (fMP4 或 CMAF)。這是建議的封裝，因為封裝負荷最少。另一個容器格式選項是 `MPEG_TS`。HLS 自發行以來已支援 MPEG TS 區塊，有時是較舊的 HLS 播放器上唯一支援的封裝。MPEG TS 通常有 5-25% 的封裝額外負荷。這表示 MPEG TS 通常需要比 fMP4 多 5-25% 的頻寬和成本。 預設值為 `FRAGMENTED_MP4`。 類型：字串 有效值:`FRAGMENTED_MP4 | MPEG_TS` 必要：否 ** [DiscontinuityMode](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 指定何時標記標記片段之間的不連續性新增到媒體播放清單。 媒體播放器通常會根據每個片段的時間戳記，建置要播放的媒體內容時間軸。這表示如果片段之間有任何重疊或間隙 （如 [HLSFragmentSelector](API_reader_HLSFragmentSelector.md)設為 的典型情況`SERVER_TIMESTAMP`)，媒體播放器時間軸在某些位置也會有片段之間的小間隙，在其他位置會覆寫影格。媒體播放器時間軸中的間隙可能會導致播放停滯，重疊可能會導致播放抖動。當片段之間存在不連續旗標時，媒體播放器預期會重設時間軸，導致下一個片段在前一個片段之後立即播放。 支援下列模式： + `ALWAYS`：不連續標記會放置在 HLS 媒體播放清單中的每個片段之間。`ALWAYS` 如果片段時間戳記不正確，建議使用 的值。 + `NEVER`：不會將不連續標記放在任何位置。建議使用 值`NEVER`，以確保媒體播放器時間軸最準確地對應到生產者時間戳記。 + `ON_DISCONTINUITY`：不連續標記會放置在間隙或重疊超過 50 毫秒的片段之間。對於大多數播放案例，建議使用 值，`ON_DISCONTINUITY`以便媒體播放器時間軸只有在媒體時間軸 （例如缺少片段） 發生重大問題時才會重設。 預設值為`ALWAYS`[HLSFragmentSelector](API_reader_HLSFragmentSelector.md)當 設為 時`SERVER_TIMESTAMP`，以及當 設為 `NEVER`時`PRODUCER_TIMESTAMP`。 類型：字串 有效值:`ALWAYS | NEVER | ON_DISCONTINUITY` 必要：否 ** [DisplayFragmentTimestamp](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 指定何時應將片段開始時間戳記包含在 HLS 媒體播放清單中。一般而言，媒體播放器會將播放頭位置報告為相對於播放工作階段中第一個片段開始的時間。不過，當 HLS 媒體播放清單中包含啟動時間戳記時，有些媒體播放器可能會根據片段時間戳記，將目前的播放頭報告為絕對時間。這有助於建立播放體驗，向觀眾顯示媒體的時鐘時間。 預設值為 `NEVER`。當 [HLSFragmentSelector](API_reader_HLSFragmentSelector.md)為 時`SERVER_TIMESTAMP`，時間戳記將是伺服器啟動時間戳記。同樣地，當 [HLSFragmentSelector](API_reader_HLSFragmentSelector.md)為 時`PRODUCER_TIMESTAMP`，時間戳記將是生產者起始時間戳記。 類型：字串 有效值:`ALWAYS | NEVER` 必要：否 ** [Expires](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 請求的工作階段過期前的秒數。此值可以介於 300 (5 分鐘） 和 43200 (12 小時） 之間。 當工作階段過期時，`GetTSFragment`無法對該工作階段進行對 `GetHLSMasterPlaylist`、`GetMP4MediaFragment`、、 或 `GetHLSMediaPlaylist` `GetMP4InitFragment`的新呼叫。 預設值為 300 (5 分鐘)。 類型：整數 有效範圍：最小值為 300。最大值為 43200。 必要：否 ** [HLSFragmentSelector](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 所請求片段的時間範圍和時間戳記的來源。 如果 `PlaybackMode`是 `ON_DEMAND`或 ，則需要此參數`LIVE_REPLAY`。如果 PlaybackMode 為`` ，則此參數為選用`LIVE`。如果 `PlaybackMode`是 `LIVE`，`FragmentSelectorType`則可以設定 ，但`TimestampRange`不應設定 。如果 `PlaybackMode`是 `ON_DEMAND`或 `LIVE_REPLAY`，`TimestampRange`則必須同時設定 `FragmentSelectorType`和 。 類型：[HLSFragmentSelector](API_reader_HLSFragmentSelector.md) 物件 必要：否 ** [MaxMediaPlaylistFragmentResults](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** HLS 媒體播放清單中傳回的片段數量上限。 當 `PlaybackMode`為 時`LIVE`，最新的片段會傳回至此值。當 `PlaybackMode`為 時`ON_DEMAND`，會傳回最舊的片段，最多達到此最大數量。 當即時 HLS 媒體播放清單中有更多可用的片段時，影片播放器通常會在開始播放之前緩衝內容。增加緩衝區大小會增加播放延遲，但可減少播放期間重新緩衝的可能性。我們建議即時 HLS 媒體播放清單至少包含 3 個片段，最多 10 個片段。 如果 `PlaybackMode`是 `LIVE`或 ，則預設為 5 個片段`LIVE_REPLAY`，如果 `PlaybackMode`是 ，則預設為 1，000 個片段`ON_DEMAND`。 5，000 個片段的最大值對應於具有 1 秒片段之串流上的影片超過 80 分鐘，以及具有 10 秒片段之串流上的影片超過 13 小時。 類型：Long 有效範圍：最小值為 1。最大值為 5000。 必要：否 ** [PlaybackMode](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 要擷取即時、即時重播或封存的隨需資料。 三種工作階段類型的功能包括下列項目： + ** `LIVE` **：對於此類型的工作階段，HLS 媒體播放清單會持續更新為可用的最新片段。我們建議媒體播放器每隔一秒擷取新的播放清單。在媒體播放器中播放此類型的工作階段時，使用者介面通常會顯示「即時」通知，沒有用於選擇要顯示之播放視窗中的位置的清理程式控制。 **注意** 在 `LIVE`模式中，最新的可用片段會包含在 HLS 媒體播放清單中，即使片段之間有間隙 （亦即，如果片段遺失）。這種差距可能會導致媒體播放器停止或導致播放跳躍。在此模式中，如果片段比播放清單中的最新片段舊，則不會將片段新增至 HLS 媒體播放清單。如果遺失的片段在後續片段新增至播放清單後變成可用，則不會新增較舊的片段，也不會填滿間隙。 + ** `LIVE_REPLAY` **：對於此類型的工作階段，HLS 媒體播放清單的更新方式與`LIVE`模式的更新方式類似，只是從包含指定開始時間的片段開始。片段會新增為下一個片段的持續時間，而不是在擷取片段時新增的片段。例如，如果工作階段中的片段長度為兩秒，則每兩秒會將新的片段新增至媒體播放清單。此模式有助於在偵測到事件時開始播放，並繼續在工作階段建立時尚未擷取的即時串流媒體。此模式也適用於串流先前封存的媒體，而不會受限於 `ON_DEMAND` 模式中的 1，000 個片段限制。 + ** `ON_DEMAND` **：對於此類型的工作階段，HLS 媒體播放清單包含工作階段的所有片段，最高可達 中指定的數字`MaxMediaPlaylistFragmentResults`。每個工作階段只能擷取播放清單一次。在媒體播放器中播放此類型的工作階段時，使用者介面通常會顯示清除器控制項，以選擇要在播放視窗中顯示的位置。 在所有播放模式中，如果 `FragmentSelectorType`是 `PRODUCER_TIMESTAMP`，且如果有多個片段具有相同的啟動時間戳記，則具有最大片段編號 （即最新片段） 的片段會包含在 HLS 媒體播放清單中。不包含其他片段。具有不同時間戳記但持續時間重疊的片段仍會包含在 HLS 媒體播放清單中。這可能會導致媒體播放器發生非預期的行為。 預設值為 `LIVE`。 類型：字串 有效值:`LIVE | LIVE_REPLAY | ON_DEMAND` 必要：否 ** [StreamARN](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 要擷取 HLS 主播放清單 URL 之串流的 Amazon Resource Name (ARN)。 您必須指定 `StreamName`或 `StreamARN`。 類型：字串 長度限制：長度下限為 1。長度上限為 1024。 模式：`arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+` 必要：否 ** [StreamName](#API_reader_GetHLSStreamingSessionURL_RequestSyntax) ** 要擷取 HLS 主播放清單 URL 的串流名稱。 您必須指定 `StreamName`或 `StreamARN`。 類型：字串 長度限制：長度下限為 1。長度上限為 256。 模式：`[a-zA-Z0-9_.-]+` 必要：否 ## 回應語法 ``` HTTP/1.1 200 Content-type: application/json { "HLSStreamingSessionURL": "string" } ``` ## 回應元素 如果動作成功，則服務傳回 HTTP 200 回應。 服務會傳回下列 JSON 格式的資料。 ** [HLSStreamingSessionURL](#API_reader_GetHLSStreamingSessionURL_ResponseSyntax) ** 媒體播放器可用來擷取 HLS 主播放清單的 URL （包含工作階段字符）。 類型：字串 ## 錯誤 如需所有動作常見錯誤的資訊，請參閱[常見錯誤類型](CommonErrors.md)。 ** ClientLimitExceededException ** Kinesis Video Streams 已調節請求，因為您已超過限制。稍後再嘗試進行呼叫。如需限制的相關資訊，請參閱 [Kinesis Video Streams 配額](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)。 HTTP 狀態碼：400 ** InvalidArgumentException ** 指定的參數超過其限制、不支援或無法使用。 HTTP 狀態碼：400 ** InvalidCodecPrivateDataException ** 至少其中一個視訊串流軌道中的轉碼器私有資料不適用於此操作。 HTTP 狀態碼：400 ** MissingCodecPrivateDataException ** 在影片串流的至少一個軌跡中找不到轉碼器私有資料。 HTTP 狀態碼：400 ** NoDataRetentionException ** `GetImages` 請求的串流不會保留資料 （也就是 `DataRetentionInHours`的 為 0)。 HTTP 狀態碼：400 ** NotAuthorizedException ** 狀態碼：403，發起人無權在指定的串流上執行 操作，或權杖已過期。 HTTP 狀態碼：401 ** ResourceNotFoundException ** `GetImages` 當 Kinesis Video Streams 找不到您指定的串流時， 會擲回此錯誤。 `GetHLSStreamingSessionURL` 如果`LIVE_REPLAY`請求具有 `ON_DEMAND`或 `PlaybackMode`的工作階段的串流在請求的時間範圍內沒有片段，或者請求具有 `PlaybackMode`的工作階段的串流在過去 30 秒內沒有片段，`LIVE`則`GetDASHStreamingSessionURL`擲回此錯誤。 HTTP 狀態碼：404 ** UnsupportedStreamMediaTypeException ** 媒體的類型 （例如，h.264 或 h.265 視訊或 AAC 或 G.711 音訊） 無法從播放工作階段第一個片段中軌道的編解碼器 IDs 決定。軌道 1 的轉碼器 ID 應該是 ，`V_MPEG/ISO/AVC`並且可選地，軌道 2 的轉碼器 ID 應該是 `A_AAC`。 HTTP 狀態碼：400 ## 另請參閱 如需在其中一種語言特定 AWS SDKs中使用此 API 的詳細資訊，請參閱下列內容： + [AWS 命令列界面 V2](https://docs.aws.amazon.com/goto/cli2/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 .NET V4 的 SDK](https://docs.aws.amazon.com/goto/DotNetSDKV4/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 C\$1\$1 的 SDK](https://docs.aws.amazon.com/goto/SdkForCpp/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 Go 的 SDK v2](https://docs.aws.amazon.com/goto/SdkForGoV2/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 Java V2 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaV2/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 JavaScript V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 Kotlin 的 SDK](https://docs.aws.amazon.com/goto/SdkForKotlin/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 PHP V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForPHPV3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 Python 的 SDK](https://docs.aws.amazon.com/goto/boto3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL) + [AWS 適用於 Ruby V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForRubyV3/kinesis-video-reader-data-2017-09-30/GetHLSStreamingSessionURL)