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

# PutMedia
<a name="API_dataplane_PutMedia"></a>

 使用此 API 將媒體資料傳送至 Kinesis 影片串流。

**注意**  
您必須先呼叫 `GetDataEndpoint` API 才能取得端點。然後使用 [--endpoint-url 參數](https://docs.aws.amazon.com/cli/latest/reference/)將`PutMedia`請求傳送至此端點。

在請求中，您可以使用 HTTP 標頭來提供參數資訊，例如串流名稱、時間戳記，以及時間戳記值是絕對值還是相對於生產者開始記錄的時間。您可以使用請求內文來傳送媒體資料。Kinesis Video Streams 僅支援使用此 API 傳送媒體資料的 Matroska (MKV) 容器格式。

您可以透過下列選項使用此 API 傳送資料：
+ 即時傳送媒體資料：例如，安全攝影機可以在產生影格時即時傳送影格。此方法可將視訊錄製與線路上傳送的資料之間的延遲降至最低。這稱為連續生產者。在這種情況下，消費者應用程式可以即時或在需要時讀取串流。
+ 離線傳送媒體資料 （分批傳送）：例如，主體攝影機可能會錄製影片數小時，並將其存放在裝置上。稍後，當您將攝影機連接到停駐連接埠時，攝影機可以啟動`PutMedia`工作階段，將資料傳送至 Kinesis 影片串流。在此案例中，延遲不是問題。

使用此 API 時，請注意下列考量事項：
+ 您必須指定 `streamName` 或 `streamARN`，但不能同時指定兩者。
+ 若要能夠在主控台或透過 HLS 播放媒體，每個片段的音軌 1 應該包含 h.264 編碼的視訊、片段中繼資料中的 CodecID 應該是「V\_MPEG/ISO/AVC」，而片段中繼資料應該包含 AVCC 格式的 h.264 轉碼器私有資料。或者，每個片段的軌道 2 應該包含 AAC 編碼音訊，片段中繼資料中的 CodecID 應該是 "A\_AAC"，而片段中繼資料應該包含 AAC 轉碼器私有資料。
+ `PutMedia` API 旨在透過長時間執行的連線做為串流 API 運作。它不適用於以傳統 RESTful 方式使用，其中會為每個片段建立新的 HTTP 連線並關閉。使用 `PutMedia` API 時，請使用 HTTP 區塊傳輸編碼，透過持久性連線持續傳送片段。
+ 對於`PutMedia`工作階段中接收的每個片段，Kinesis Video Streams 會傳送一或多個認可。潛在的用戶端網路考量可能會導致您無法在產生所有這些確認時取得這些確認。
**注意**  
使用 `PutMedia`做為串流長時間執行的連線，在單一持久性連線中傳送多個片段。如果您嘗試多個並行`PutMedia`連線，Kinesis Video Streams 會調節`ConnectionLimitExceededException`發生錯誤的最新連線。

使用 `PutMedia` API 時適用下列限制：
+ 用戶端每秒可以呼叫每個串流`PutMedia`最多五次。
+ 用戶端每秒每個串流最多可傳送五個片段。
+ Kinesis Video Streams 會在`PutMedia`工作階段期間以高達 12.5 MB/秒或 100 Mbps 的速率讀取媒體資料。

請注意下列限制條件。在這些情況下，Kinesis Video Streams 會在回應中傳送錯誤確認。
+ 不允許時間代碼範圍超過允許上限且包含超過 50 MB 資料的片段。
+ 不允許包含超過三個軌跡的片段。每個片段中的每個影格都必須具有與片段標頭中定義的其中一個軌跡相同的軌跡編號。此外，每個片段在片段標頭中定義的每個軌道必須至少包含一個影格。
+ 對於片段中繼資料中定義的每個軌跡，每個片段必須至少包含一個影格。
+ 片段中最早的影格時間戳記必須在前一個片段中的最新影格時間戳記之後。
+ 包含多個 MKV 區段或包含不允許 MKV 元素 （例如 `track*`) 的 MKV 串流也會導致錯誤確認。

Kinesis Video Streams 會將每個傳入片段和相關中繼資料存放在稱為「區塊」的 中。片段中繼資料包括下列項目：
+ `PutMedia` 請求開始時提供的 MKV 標頭
+ 片段的下列 Kinesis Video Streams 特定中繼資料：
  +  `server_timestamp` - Kinesis Video Streams 開始接收片段時的時間戳記。
  +  `producer_timestamp` - 生產者開始記錄片段時的時間戳記。Kinesis Video Streams 使用請求中接收的三個資訊來計算此值。
    + 請求內文中接收的片段時間碼值以及片段。
    + 兩個請求標頭： `producerStartTimestamp` （生產者開始記錄時） 和 `fragmentTimeCodeType`（承載中的片段時間碼是絕對還是相對）。

    Kinesis Video Streams 接著會運算片段`producer_timestamp`的 ，如下所示：

     如果 `fragmentTimeCodeType` 是相對的，則 

     `producer_timestamp` = `producerStartTimeStamp` \+ 片段時間碼 

    如果 `fragmentTimeCodeType` 是絕對值，則 

     `producer_timestamp` = 片段時間碼 （轉換為毫秒）
  + Kinesis Video Streams 指派的唯一片段編號。

  

**注意**  
 當您提出`GetMedia`請求時，Kinesis Video Streams 會傳回這些區塊的串流。用戶端可以視需要處理中繼資料。

**注意**  
此操作僅適用於適用於 Java 的 AWS 開發套件。其他語言不支援 AWS SDKs。

**注意**  
Kinesis Video Streams 不會在透過 PutMedia API 擷取和封存期間剖析和驗證轉碼器私有資料。KVS 透過 HLS APIs 使用串流時，會從 MPEG-TS 和 MP4 片段封裝的編解碼器私有資料擷取並驗證必要資訊。

**注意**  
如果叫用 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)。

## 請求語法
<a name="API_dataplane_PutMedia_RequestSyntax"></a>

```
POST /putMedia HTTP/1.1
x-amzn-stream-name: {{StreamName}}
x-amzn-stream-arn: {{StreamARN}}
x-amzn-fragment-timecode-type: {{FragmentTimecodeType}}
x-amzn-producer-start-timestamp: {{ProducerStartTimestamp}}

{{Payload}}
```

## URI 請求參數
<a name="API_dataplane_PutMedia_RequestParameters"></a>

請求會使用下列 URI 參數。

 ** [FragmentTimecodeType](#API_dataplane_PutMedia_RequestSyntax) **   <a name="KinesisVideo-dataplane_PutMedia-request-FragmentTimecodeType"></a>
您可以將此值傳遞為 `x-amzn-fragment-timecode-type` HTTP 標頭。  
指出片段中的時間碼 （承載、HTTP 請求內文） 是絕對還是相對於 `producerStartTimestamp`。Kinesis Video Streams 會使用此資訊來計算請求中接收`producer_timestamp`之片段的 ，如 API 概觀中所述。  
有效值:`ABSOLUTE | RELATIVE`   
必要：是

 ** [ProducerStartTimestamp](#API_dataplane_PutMedia_RequestSyntax) **   <a name="KinesisVideo-dataplane_PutMedia-request-ProducerStartTimestamp"></a>
您會將此值傳遞為 `x-amzn-producer-start-timestamp` HTTP 標頭。  
這是生產者開始記錄媒體的生產者時間戳記 （而非請求中特定片段的時間戳記）。

 ** [StreamARN](#API_dataplane_PutMedia_RequestSyntax) **   <a name="KinesisVideo-dataplane_PutMedia-request-StreamARN"></a>
您可以將此值傳遞為 `x-amzn-stream-arn` HTTP 標頭。  
您要寫入媒體內容之 Kinesis 影片串流的 Amazon Resource Name (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_PutMedia_RequestSyntax) **   <a name="KinesisVideo-dataplane_PutMedia-request-StreamName"></a>
您可以將此值傳遞為 `x-amzn-stream-name` HTTP 標頭。  
您要寫入媒體內容的 Kinesis 影片串流名稱。如果您未指定 `streamName`，則必須指定 `streamARN`。  
長度限制：長度下限為 1。長度上限為 256。  
模式：`[a-zA-Z0-9_.-]+`

## 請求主體
<a name="API_dataplane_PutMedia_RequestBody"></a>

請求接受下列二進位資料。

 ** [Payload](#API_dataplane_PutMedia_RequestSyntax) **   <a name="KinesisVideo-dataplane_PutMedia-request-Payload"></a>
 要寫入 Kinesis 影片串流的媒體內容。在目前的實作中，Kinesis Video Streams 僅支援具有單一 MKV 區段的 Matroska (MKV) 容器格式。區段可以包含一或多個叢集。  
每個 MKV 叢集都會映射至 Kinesis 影片串流片段。無論您選擇哪個叢集持續時間，都會成為片段持續時間。

## 回應語法
<a name="API_dataplane_PutMedia_ResponseSyntax"></a>

```
HTTP/1.1 200

{{Payload}}
```

## 回應元素
<a name="API_dataplane_PutMedia_ResponseElements"></a>

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

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

 ** [Payload](#API_dataplane_PutMedia_ResponseSyntax) **   <a name="KinesisVideo-dataplane_PutMedia-response-Payload"></a>
 Kinesis Video Streams 成功收到`PutMedia`請求後，服務會驗證請求標頭。然後，服務會開始讀取承載，並先傳送 HTTP 200 回應。  
然後，服務會傳回串流，其中包含一系列以換行分隔的 JSON 物件 (`Acknowledgement` 物件）。在傳送媒體資料的相同連線上收到確認。`PutMedia` 請求可以有許多確認。每個 都`Acknowledgement`包含下列鍵/值對：  
+  `AckEventType` - 確認所代表的事件類型。
  +  **緩衝：**Kinesis Video Streams 已開始接收片段。Kinesis Video Streams 會在收到第一個片段資料位元組時傳送第一個緩衝認可。
  +  **已接收：**Kinesis Video Streams 收到整個片段。如果您未將串流設定為保留資料，生產者可以在收到此確認後停止緩衝片段。
  +  **持久性：**Kinesis Video Streams 已保留片段 （例如 Amazon S3)。如果您將串流設定為保留資料，則會收到此確認。收到此確認後，生產者可以停止緩衝片段。
  +  **錯誤：**Kinesis Video Streams 在處理片段時發生錯誤。您可以檢閱錯誤代碼，並判斷下一個動作。
  +  **閒置：**`PutMedia`工作階段正在進行中。不過，Kinesis Video Streams 目前未接收資料。Kinesis Video Streams 會在最後一次接收資料後最多 30 秒內定期傳送此認可。如果在 30 秒內未收到任何資料，Kinesis Video Streams 會關閉請求。
**注意**  
 此認可可協助生產者判斷`PutMedia`連線是否有效，即使它未傳送任何資料也一樣。
+  `FragmentTimecode` - 傳送確認的片段時間碼。

  如果 `AckEventType`為**閒置**，則元素可能會遺失。
+  `FragmentNumber` - 傳送確認的 Kinesis Video Streams 產生的片段編號。
+  `ErrorId` 和 `ErrorCode` - 如果 `AckEventType`是 `Error`，則此欄位會提供對應的錯誤代碼。以下是錯誤 IDs及其對應的錯誤代碼和錯誤訊息清單：
  + 4000 - STREAM\_READ\_ERROR - 讀取資料串流時發生錯誤。
  + 4001 - MAX\_FRAGMENT\_SIZE\_REACHED - 片段大小大於上限，允許 50 MB。
  + 4002 - MAX\_FRAGMENT\_DURATION\_REACHED - 片段持續時間大於允許的上限。
  + 4003 - MAX\_CONNECTION\_DURATION\_REACHED - 連線持續時間大於允許的閾值上限。
  + 4004 - FRAGMENT\_TIMECODE\_LESSER\_THAN\_PREVIOUS - 片段時間碼小於先前時間碼的時間碼 （在`PutMedia`通話中，您無法依序傳送片段）。
  + 4005 - more\_THAN\_ALLOWED\_TRACKS\_FOUND - 在 MKV 中找到多個軌道。（已棄用）
  + 4006 - INVALID\_MKV\_DATA - 無法將輸入串流剖析為有效的 MKV 格式。
  + 4007 - INVALID\_PRODUCER\_TIMESTAMP - 無效的生產者時間戳記。
  + 4008 - STREAM\_NOT\_ACTIVE - 串流不再存在 （已刪除）。
  + 4009 - FRAGMENT\_METADATA\_LIMIT\_REACHED - 已達到片段中繼資料限制。請參閱 開發人員指南的限制[https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)一節。
  + 4010 - TRACK\_NUMBER\_MISMATCH - MKV 影格中的軌跡編號與 MKV 標頭中的軌跡不相符。
  + 4011 - FRAMES\_MISSING\_FOR\_TRACK - 片段不包含 MKV 標頭中至少一個軌道的任何影格。
  + 4012 - INVALID\_FRAGMENT\_METADATA - 片段中繼資料名稱不能以字串 開頭` AWS_`。
  + 4500 - KMS\_KEY\_ACCESS\_DENIED - 拒絕存取串流指定的 KMS 金鑰。
  + 4501 - KMS\_KEY\_DISABLED - 串流指定的 KMS 金鑰已停用。
  + 4502 - KMS\_KEY\_VALIDATION\_ERROR - 串流指定的 KMS 金鑰驗證失敗。
  + 4503 - KMS\_KEY\_UNAVAILABLE - 串流指定的 KMS 金鑰無法使用。
  + 4504 - KMS\_KEY\_INVALID\_USAGE - 串流指定 KMS 金鑰的使用無效。
  + 4505 - KMS\_KEY\_INVALID\_STATE - 串流指定的 KMS 金鑰處於無效狀態。
  + 4506 - KMS\_KEY\_NOT\_FOUND - 找不到串流指定的 KMS 金鑰。
  + 5000 - INTERNAL\_ERROR - 內部服務錯誤。
  + 5001 - ARCHIVAL\_ERROR - Kinesis Video Streams 無法將片段保留到資料存放區。
生產者在傳送長時間執行`PutMedia`請求的承載時，應讀取回應以進行確認。由於在中繼代理伺服器上緩衝，生產者可能會同時收到確認區塊。想要接收及時確認的生產者可以在每個`PutMedia`請求中傳送較少的片段。

## 錯誤
<a name="API_dataplane_PutMedia_Errors"></a>

如需所有動作常見錯誤的資訊，請參閱[常見錯誤類型](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

## 範例
<a name="API_dataplane_PutMedia_Examples"></a>

### 確認格式
<a name="API_dataplane_PutMedia_Example_1"></a>

確認的格式如下：

```
{
       Acknowledgement : {
          "EventType": enum
          "FragmentTimecode": Long,
          "FragmentNumber": Long,
          "ErrorId" : String       
      }
}
```

## 另請參閱
<a name="API_dataplane_PutMedia_SeeAlso"></a>

如需在其中一種語言特定 AWS SDKs中使用此 API 的詳細資訊，請參閱下列內容：
+  [AWS 命令列界面 V2](https://docs.aws.amazon.com/goto/cli2/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 .NET V4 的 SDK](https://docs.aws.amazon.com/goto/DotNetSDKV4/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 C\+\+ 的 SDK](https://docs.aws.amazon.com/goto/SdkForCpp/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 Go 的 SDK v2](https://docs.aws.amazon.com/goto/SdkForGoV2/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 Java V2 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaV2/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 JavaScript V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 Kotlin 的 SDK](https://docs.aws.amazon.com/goto/SdkForKotlin/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 PHP V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForPHPV3/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 Python 的 SDK](https://docs.aws.amazon.com/goto/boto3/kinesis-video-data-2017-09-30/PutMedia) 
+  [AWS 適用於 Ruby V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForRubyV3/kinesis-video-data-2017-09-30/PutMedia)