GetMedia - Amazon Kinesis Video Streams
請求語法URI 請求參數請求主體回應語法回應元素錯誤另請參閱

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

GetMedia

使用此 API 從 Kinesis 影片串流擷取媒體內容。在請求中，您可以識別串流名稱或串流 Amazon Resource Name (ARN) 和啟動區塊。然後，Kinesis Video Streams 會依片段編號依序傳回區塊串流。

注意

您必須先呼叫 GetDataEndpoint API 才能取得端點。然後使用 --endpoint-url 參數將GetMedia請求傳送至此端點。

當您將媒體資料 （片段） 放在串流時，Kinesis Video Streams 會將每個傳入片段和相關中繼資料存放在稱為「區塊」的 中。如需詳細資訊，請參閱 PutMedia。GetMedia API 會從您在請求中指定的區塊開始傳回這些區塊的串流。

GetMedia API 旨在透過長時間執行的連線做為串流 API 運作。它不適用於以傳統 RESTful 方式使用，其中會為每個片段建立新的 HTTP 連線並關閉。使用 GetMedia API 時，請使用 HTTP 區塊傳輸編碼，透過持久性連線持續傳送片段。

使用 GetMedia API 時，適用下列限制：

  • 用戶端每秒可以呼叫每個串流GetMedia最多五次。

  • Kinesis Video Streams 會在GetMedia工作階段期間以每秒高達 25 MB （或每秒 200 MB) 的速率傳送媒體資料。

注意

GetMedia HTTP 回應狀態碼會立即傳回，但如果沒有可供播放的擷取片段，則讀取 HTTP 回應承載會在 3 秒後逾時。

注意

如果在叫用 Kinesis Video Streams 媒體 API 後擲出錯誤，除了 HTTP 狀態碼和回應內文之外，還包含下列資訊：

  • x-amz-ErrorType HTTP 標頭 – 除了 HTTP 狀態碼提供的內容之外，還包含更具體的錯誤類型。

  • x-amz-RequestId HTTP 標頭 – 如果您想要向 回報問題 AWS，支援團隊可以在指定請求 ID 時更妥善地診斷問題。

HTTP 狀態碼和 ErrorType 標頭都可以用來以程式設計方式決定錯誤是否可重試，以及在何種條件下，以及提供用戶端程式設計人員可能需要採取的動作資訊，以便成功重試。

如需詳細資訊，請參閱本主題底部的錯誤區段，以及常見錯誤。

請求語法

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

識別要從指定串流取得的開始區塊。

類型：StartSelector 物件

必要：是

StreamARN

您想要從中取得媒體內容的串流 ARN。如果您未指定 streamARN，則必須指定 streamName。

類型：字串

長度限制：長度下限為 1。長度上限為 1024。

模式：arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

必要：否

StreamName

您想要從中取得媒體內容的 Kinesis 影片串流名稱。如果您未指定 streamName，則必須指定 streamARN。

類型：字串

長度限制：長度下限為 1。長度上限為 256。

模式：[a-zA-Z0-9_.-]+

必要：否

回應語法

HTTP/1.1 200
Content-Type: ContentType

Payload

回應元素

如果動作成功，則服務傳回 HTTP 200 回應。

回應會傳回下列 HTTP 標頭。

ContentType

請求媒體的內容類型。

長度限制：長度下限為 1。長度上限為 128。

模式：^[a-zA-Z0-9_\.\-]+$

回應傳回以下內容作為 HTTP 主體。

Payload

承載 Kinesis Video Streams 傳回是來自指定串流的一系列區塊。如需區塊的詳細資訊，請參閱 PutMedia。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 - 內部錯誤

錯誤

如需所有動作常見錯誤的資訊，請參閱常見錯誤。

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 的詳細資訊，請參閱下列內容：