本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # GetMedia 使用此 API 從 Kinesis 影片串流擷取媒體內容。在請求中，您可以識別串流名稱或串流 Amazon Resource Name (ARN) 和起始區塊。然後，Kinesis Video Streams 會依片段編號依序傳回區塊串流。 **注意** 您必須先呼叫 `GetDataEndpoint` API 才能取得端點。然後使用 [--endpoint-url 參數](https://docs.aws.amazon.com/cli/latest/reference/)將`GetMedia`請求傳送至此端點。 當您將媒體資料 （片段） 放在串流上時，Kinesis Video Streams 會將每個傳入片段和相關中繼資料儲存在稱為「區塊」的內容中。如需詳細資訊，請參閱 [PutMedia](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_PutMedia.html)。`GetMedia` API 會從您在請求中指定的區塊開始傳回這些區塊的串流。 `GetMedia` API 旨在透過長時間執行的連線做為串流 API 運作。它不適用於以傳統 RESTful 方式使用，其中會為每個片段建立新的 HTTP 連線並關閉。當您叫用 `GetMedia` API 時，Kinesis Video Streams 會使用 HTTP 區塊傳輸編碼，透過持久性長時間執行的連線持續交付片段。 使用 `GetMedia` API 時適用下列限制： + 用戶端每秒可以呼叫每個串流`GetMedia`最多五次。 + Kinesis Video Streams 會在`GetMedia`工作階段期間以每秒高達 25 MB （或每秒 200 MB) 的速率傳送媒體資料。 **注意** 使用 `GetMedia`做為串流長時間執行的連線，擷取單一持久性連線中的多個片段。請勿在建立和關閉每個片段的新 HTTP 連線時，以傳統 RESTful 方式使用 `GetMedia` API。如果您嘗試三個以上的並行`GetMedia`連線，Kinesis Video Streams 會使用`ConnectionLimitExceededException`錯誤調節最新的連線。 **注意** `GetMedia` HTTP 回應狀態碼會立即傳回，但如果沒有可供播放的擷取片段，則讀取 HTTP 回應承載會在 3 秒後逾時。 **注意** 如果在叫用 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 /getMedia HTTP/1.1 Content-type: application/json { "StartSelector": { "AfterFragmentNumber": "{{string}}", "ContinuationToken": "{{string}}", "StartSelectorType": "{{string}}", "StartTimestamp": {{number}} }, "StreamARN": "{{string}}", "StreamName": "{{string}}" } ``` ## URI 請求參數 請求不會使用任何 URI 參數。 ## 請求主體 請求接受採用 JSON 格式的下列資料。 ** [StartSelector](#API_dataplane_GetMedia_RequestSyntax) ** 識別要從指定串流取得的起始區塊。 類型：[StartSelector](API_dataplane_StartSelector.md) 物件 必要：是 ** [StreamARN](#API_dataplane_GetMedia_RequestSyntax) ** 您想要從中取得媒體內容的串流 ARN。如果您未指定 `streamARN`，則必須指定 `streamName`。 類型：字串 長度限制：長度下限為 1。長度上限為 1024。 模式：`arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+` 必要：否 ** [StreamName](#API_dataplane_GetMedia_RequestSyntax) ** 您要從中取得媒體內容的 Kinesis 影片串流名稱。如果您未指定 `streamName`，則必須指定 `streamARN`。 類型：字串 長度限制：長度下限為 1。長度上限為 256。 模式：`[a-zA-Z0-9_.-]+` 必要：否 ## 回應語法 ``` HTTP/1.1 200 Content-Type: {{ContentType}} {{Payload}} ``` ## 回應元素 如果動作成功，則服務傳回 HTTP 200 回應。 回應會傳回下列 HTTP 標頭。 ** [ContentType](#API_dataplane_GetMedia_ResponseSyntax) ** 所請求媒體的內容類型。 長度限制：長度下限為 1。長度上限為 128。 模式：`^[a-zA-Z0-9_\.\-]+$` 回應傳回以下內容作為 HTTP 主體。 ** [Payload](#API_dataplane_GetMedia_ResponseSyntax) ** 承載 Kinesis Video Streams 傳回是來自指定串流的一系列區塊。如需區塊的詳細資訊，請參閱 [PutMedia](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_PutMedia.html)。Kinesis Video Streams 在`GetMedia`呼叫中傳回的區塊也包含下列額外的 Matroska (MKV) 標籤： + AWS\_KINESISVIDEO\_CONTINUATION\_TOKEN (UTF-8 字串） - 如果您的`GetMedia`呼叫終止，您可以在下一個請求中使用此接續字符，以取得最後一個請求終止的下一個區塊。 + AWS\_KINESISVIDEO\_MILLIS\_BEHIND\_NOW (UTF-8 字串） - 用戶端應用程式可以使用此標籤值來判斷回應中傳回的區塊落後於串流上最新區塊的程度。 + AWS\_KINESISVIDEO\_FRAGMENT\_NUMBER - 區塊中傳回的片段編號。 + AWS\_KINESISVIDEO\_SERVER\_TIMESTAMP - 片段的伺服器時間戳記。 + AWS\_KINESISVIDEO\_PRODUCER\_TIMESTAMP - 片段的生產者時間戳記。 如果發生錯誤，將出現下列標籤： + AWS\_KINESISVIDEO\_ERROR\_CODE - 導致 GetMedia 停止之錯誤的字串描述。 + AWS\_KINESISVIDEO\_ERROR\_ID：錯誤整數代碼。 錯誤代碼如下所示： + 3002 - 寫入串流時發生錯誤 + 4000 - 找不到請求的片段 + 4500 - 拒絕存取串流的 KMS 金鑰 + 4501 - 串流的 KMS 金鑰已停用 + 4502 - 串流 KMS 金鑰上的驗證錯誤 + 4503 - 串流中指定的 KMS 金鑰無法使用 + 4504 - 串流中指定的 KMS 金鑰使用無效 + 4505 - 串流中指定的 KMS 金鑰狀態無效 + 4506 - 找不到串流中指定的 KMS 金鑰 + 5000 - 內部錯誤 ## 錯誤 如需所有動作常見錯誤的資訊，請參閱[常見錯誤類型](CommonErrors.md)。 ** ClientLimitExceededException ** Kinesis Video Streams 已調節請求，因為您已超過允許的用戶端呼叫限制。稍後嘗試進行呼叫。 HTTP 狀態碼：400 ** ConnectionLimitExceededException ** Kinesis Video Streams 已調節請求，因為您已超過允許的用戶端連線限制。 HTTP 狀態碼：400 ** InvalidArgumentException ** 此輸入參數的值無效。 HTTP 狀態碼：400 ** InvalidEndpointException ** 來電者使用錯誤的端點將資料寫入串流。收到這類例外狀況時，使用者必須呼叫 `GetDataEndpoint`，並將 `APIName`設定為 `PUT_MEDIA` ，並使用 回應中的端點來叫用下一個`PutMedia`呼叫。 HTTP 狀態碼：400 ** NotAuthorizedException ** 發起人無權對指定的串流執行 操作，或權杖已過期。 HTTP 狀態碼：401 ** ResourceNotFoundException ** 狀態碼：404，具有指定名稱的串流不存在。 HTTP 狀態碼：404 ## 另請參閱 如需在其中一種語言特定 AWS SDKs中使用此 API 的詳細資訊，請參閱下列內容： + [AWS 命令列界面 V2](https://docs.aws.amazon.com/goto/cli2/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 .NET V4 的 SDK](https://docs.aws.amazon.com/goto/DotNetSDKV4/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 C\+\+ 的 SDK](https://docs.aws.amazon.com/goto/SdkForCpp/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 Go 的 SDK v2](https://docs.aws.amazon.com/goto/SdkForGoV2/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 Java V2 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaV2/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 JavaScript V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 Kotlin 的 SDK](https://docs.aws.amazon.com/goto/SdkForKotlin/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 PHP V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForPHPV3/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 Python 的 SDK](https://docs.aws.amazon.com/goto/boto3/kinesis-video-data-2017-09-30/GetMedia) + [AWS 適用於 Ruby V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForRubyV3/kinesis-video-data-2017-09-30/GetMedia)