翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # PutMedia この API を使用して、メディアデータを Kinesis ビデオストリームに送信します。 **注記** エンドポイントを取得するには、最初に `GetDataEndpoint` API を呼び出す必要があります。次に、[--endpoint-url parameter](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 として動作するように設計されています。これは、フラグメントごとに新しい HTTP 接続が確立されて閉じられる従来の RESTful 方式での使用を意図していません。`PutMedia` API を使用する場合は、HTTP チャンク転送エンコーディングを使用して、永続接続を介してフラグメントを継続的に送信します。 + `PutMedia` セッションで受信したフラグメントごとに、Kinesis Video Streams は 1 つ以上の確認を送信します。クライアント側のネットワークに関する潜在的な考慮事項により、これらの確認が生成されても、それらの確認がすべて取得されない場合があります。 **注記** 1 つの永続接続で複数のフラグメントを送信するには、長時間実行されるストリーミング接続`PutMedia`として を使用します。複数の同時`PutMedia`接続を試みると、Kinesis Video Streams は最新の接続を`ConnectionLimitExceededException`エラーでスロットリングします。 `PutMedia` API を使用するときは以下の制限が適用されます。 + クライアントは、ストリームごとに 1 秒間に最大 5 回 `PutMedia` を呼び出すことができます。 + クライアントは、ストリームごとに 1 秒あたり最大 5 つのフラグメントを送信できます。 + Kinesis Video Streams は、最大12.5 MB/秒、つまり `PutMedia` セッション中に 100 Mbps の速度でメディアデータを読み込みます。 以下の制約があることに注意してください。このような場合、Kinesis Video Streams は応答でエラー確認を送信します。 + 最大許容制限よりも長いタイムコードを持ち、50 MB を超えるデータを含むフラグメントは許可されません。 + 3 つ以上のトラックを含むフラグメントは許可されません。すべてのフラグメントの各フレームには、フラグメントヘッダーで定義されているトラックの 1 つと同じトラック番号が必要です。さらに、すべてのフラグメントには、フラグメントヘッダーで定義されたトラックごとに少なくとも 1 つのフレームが含まれている必要があります。 + 各フラグメントには、フラグメントメタデータで定義された各トラックに少なくとも 1 つのフレームが含まれている必要があります。 + フラグメント内の最初のフレームタイムスタンプは、前のフラグメントの最後のフレームタイムスタンプの後にする必要があります。 + 複数の MKV セグメントを含む、または許可されていない MKV 要素 (`track*` など) を含む MKV ストリームもエラー確認になります。 Kinesis Video Streams は、受信する各フラグメントと関連メタデータを「チャンク」と呼ばれるものに格納します。フラグメントメタデータには、次のものが含まれます。 + `PutMedia` 要求の開始時に提供される MKV ヘッダ + 次のフラグメントの Kinesis Video Streams 固有のメタデータ。 + `server_timestamp` - Kinesis Video Streams がフラグメントを受け取った時のタイムスタンプ。 + `producer_timestamp` - プロデューサーがフラグメントの記録を開始したときのタイムスタンプ。Kinesis Video Streams は、リクエストで受信した 3 つの情報を使用して、この値を計算します。 + フラグメントとともにリクエスト本文で受信されたフラグメントのタイムコード値。 + 2 つのリクエストヘッダー: `producerStartTimestamp`（プロデューサーの記録開始時間）および `fragmentTimeCodeType`（ペイロード内フラグメントの絶対タイムコードまたは相対タイムコードの設定）。 Kinesis Video Streams は、フラグメントの `producer_timestamp` を次のように計算します。 `fragmentTimeCodeType` が相対の場合: `producer_timestamp` = `producerStartTimeStamp` \+ フラグメントタイムコード `fragmentTimeCodeType` が絶対の場合: `producer_timestamp` = フラグメントタイムコード (ミリ秒に変換) + Kinesis Video Streams によって割り当てられた一意のフラグメント番号。 **注記** `GetMedia` リクエストを行うと、Kinesis Video Streams はこれらのチャンクのストリームを返します。クライアントは必要に応じてメタデータを処理できます。 **注記** このオペレーションは AWS SDK for Java でのみ使用できます。他の言語の AWS SDKs ではサポートされていません。 **注記** Kinesis Video Streams は、PutMedia API を介した取り込みやアーカイブ中に、コーデックのプライベートデータを解析および検証しません。KVS は、HLS API を介してストリームを消費するときに、MPEG-TS および MP4 フラグメントパッケージングのコーデックプライベートデータから必要な情報を抽出して検証します。 **注記** Kinesis Video Streams メディア API を呼び出した後にエラーがスローされた場合、HTTP ステータスコードとレスポンス本文に加えて、次の情報が含まれます。 `x-amz-ErrorType` HTTP ヘッダー — HTTP ステータスコードで提供されるものに加えて、より具体的なエラータイプが含まれます。 `x-amz-RequestId` HTTP ヘッダー – 問題を報告したい場合は AWS、リクエスト ID を指定することで、サポートチームが問題をより適切に診断できます。 HTTP ステータスコードと ErrorType ヘッダーの両方を使用すれば、エラーが再試行可能かどうか、またはどのような条件下でエラーが再試行可能かについてプログラムで判断したり、クライアントプログラマーが再度試行するために必要なアクションに関する情報を提供したりできます。 詳細については、このトピックの下部にある**[Errors]** (エラー) セクションおよび「[Common Errors](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/CommonErrors.html)」を参照してください。 ## リクエストの構文 ``` 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 リクエストパラメータ リクエストでは、次の URI パラメータを使用します。 ** [FragmentTimecodeType](#API_dataplane_PutMedia_RequestSyntax) ** この値を `x-amzn-fragment-timecode-type` HTTP ヘッダーとして渡します。 フラグメント（ペイロード、HTTP リクエスト本文）内のタイムコードが `producerStartTimestamp` に対して絶対値であるか相対値であるかを示します。Kinesis Video Streams は、API の概要で説明されているように、この情報を使用して、リクエストで受信したフラグメントの `producer_timestamp` を計算します。 有効な値：`ABSOLUTE | RELATIVE` 必須: はい ** [ProducerStartTimestamp](#API_dataplane_PutMedia_RequestSyntax) ** この値を `x-amzn-producer-start-timestamp` HTTP ヘッダーとして渡します。 これは、プロデューサーがメディアの記録を開始したプロデューサーのタイムスタンプです（リクエスト内の特定のフラグメントのタイムスタンプではありません）。 ** [StreamARN](#API_dataplane_PutMedia_RequestSyntax) ** この値を `x-amzn-stream-arn` HTTP ヘッダーとして渡します。 メディアコンテンツを書き込む Kinesis のビデオストリームの Amazon リソース名 (ARN)。`streamARN` を指定しない場合は、`streamName` を指定する必要があります。 長さの制限: 最小長は 1 です。最大長は 1,024 です。 パターン: `arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+` ** [StreamName](#API_dataplane_PutMedia_RequestSyntax) ** この値を `x-amzn-stream-name` HTTP ヘッダーとして渡します。 メディアコンテンツを書き込む Kinesis ビデオストリームの名前。`streamName` を指定しない場合は、`streamARN` を指定する必要があります。 長さの制約: 最小長は 1 です。最大長は 256 です。 パターン: `[a-zA-Z0-9_.-]+` ## リクエストボディ リクエストは以下のバイナリデータを受け入れます。 ** [Payload](#API_dataplane_PutMedia_RequestSyntax) ** Kinesis ビデオストリームに書き込むメディアコンテンツ。現在の実装では、Kinesis Video Streams は、単一の MKV セグメントを含む Matroska (MKV) コンテナ形式のみをサポートしています。セグメントには、1 つまたは複数のクラスターを含めることができます。 各 MKV クラスターは Kinesis ビデオストリームフラグメントにマッピングされます。選択したクラスター期間は、フラグメント期間になります。 ## レスポンスの構文 ``` HTTP/1.1 200 {{Payload}} ``` ## レスポンス要素 アクションが成功すると、サービスは HTTP 200 レスポンスを返します。 レスポンスは、HTTP 本文として以下を返します。 ** [Payload](#API_dataplane_PutMedia_ResponseSyntax) ** Kinesis Video Streams が `PutMedia` リクエストを正常に受信した後、サービスがリクエストヘッダーを検証します。次に、サービスはペイロードの読み込みを開始し、最初に HTTP 200 レスポンスを送信します。 次に、サービスは、改行で区切られた一連の JSON オブジェクト（`Acknowledgement` オブジェクト）を含むストリームを返します。確認応答は、メディアデータが送信されるのと同じ接続で受信されます。`PutMedia` リクエストには多くの確認応答があります。各 `Acknowledgement` は、次のキーと値のペアで構成されています。 + `AckEventType` - 確認応答が表すイベントタイプ。 + **Buffering:** Kinesis Video Streams がフラグメントの受信を開始しました。Kinesis Video Streams は、フラグメントデータの最初のバイトを受信されると、最初の Buffering 確認応答を送信します。 + **Received:** Kinesis Video Streams がフラグメント全体を受信しました。データを保持するようにストリームを設定しなかった場合、プロデューサーはこの確認応答を受信するとフラグメントのバッファリングを停止できます。 + **Persisted:** Kinesis Video Streams は、フラグメントを保持しました（Amazon S3 など）。データを保持するようにストリームを設定すると、この確認応答を受け取ります。この確認応答を受信すると、プロデューサはフラグメントのバッファリングを停止できます。 + **Error:** フラグメントの処理中に Kinesis Video Streams でエラーが発生しました。エラーコードを確認して、次のアクションを決定できます。 + **Idle:** `PutMedia`セッションが進行中です。ただし、Kinesis Video Streams は現在データを受信していません。　 Kinesis Video Streams は、最後のデータ受信後最大 30 秒間、この確認応答を定期的に送信します。データが 30 秒以内に受信されない場合、Kinesis Video Streams はリクエストを終了します。 **注記** この確認応答は、データを送信していない場合でも、プロデューサーが `PutMedia` 接続が有効であるかどうかを判断するのに役立ちます。 + `FragmentTimecode` - 確認応答が送信されるフラグメントタイムコード。 `AckEventType` が **Idle** の場合、要素が欠落している可能性があります。 + `FragmentNumber` - 確認応答が送信される Kinesis Video Streams が生成するフラグメント番号。 + `ErrorId` および `ErrorCode` - `AckEventType`が の場合`Error`、このフィールドには対応するエラーコードが表示されます。次に、エラー ID とそれに対応するエラーコードおよびエラーメッセージのリストを示します。 + 4000 - STREAM\_READ\_ERROR - データストリームの読み取り中にエラーが発生しました。 + 4001 - MAX\_FRAGMENT\_SIZE\_REACH - フラグメントサイズが最大制限の 50 MB を超えています。 + 4002 - MAX\_FRAGMENT\_DURATION\_REACHED - フラグメント期間が最大許容制限を超えています。 + 4003 - MAX\_CONNECTION\_DURATION\_REACH - 接続時間が最大許容しきい値を超えています。 + 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\_REACH - フラグメントメタデータの制限に達しました。デベロッパーガイドの[「制限](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)」セクションを参照してください。 + 4010 - TRACK\_NUMBER\_MISMATCH - MKV フレームのトラック番号が MKV ヘッダーのトラックと一致しませんでした。 + 4011 - FRAMES\_MISSING\_FOR\_TRACK - フラグメントには、MKV ヘッダーのトラックの少なくとも 1 つのフレームが含まれていませんでした。 + 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\_NAVAULABLE - ストリームの指定された 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` リクエストごとに送信するフラグメントを少なくすることができます。 ## エラー すべてのアクションに共通のエラーについては、「[一般的なエラータイプ](CommonErrors.md)」を参照してください。 ** ClientLimitExceededException ** Kinesis Video Streams は、許可されたクライアントコールの制限を超えているため、リクエストをスロットリングしました。後で呼び出しを試みてください。 HTTP ステータスコード: 400 ** ConnectionLimitExceededException ** 許可されたクライアント接続の制限を超えたため、Kinesis Video Streams がリクエストをスロットリングしました。 HTTP ステータスコード: 400 ** InvalidArgumentException ** この入力パラメータの値は無効です。 HTTP ステータスコード: 400 ** InvalidEndpointException ** 呼び出し元が間違ったエンドポイントを使用してデータをストリームに書き込みました。このような例外を受信すると、ユーザーは `APIName` を `PUT_MEDIA` に設定して `GetDataEndpoint` を呼び出し、応答からのエンドポイントを使用して次の `PutMedia` コールを呼び出す必要があります。 HTTP ステータスコード: 400 ** NotAuthorizedException ** 呼び出し元は、指定されたストリームで操作を実行する権限がないか、トークンの有効期限が切れています。 HTTP ステータスコード: 401 ** ResourceNotFoundException ** ステータスコード: 404 指定された名前のストリームは存在しません。 HTTP ステータスコード: 404 ## 例 ### 確認応答の形式 確認応答の形式は次のとおりです。 ``` { Acknowledgement : { "EventType": enum "FragmentTimecode": Long, "FragmentNumber": Long, "ErrorId" : String } } ``` ## 以下の資料も参照してください。 言語固有の AWS SDKs のいずれかでこの API を使用する方法の詳細については、以下を参照してください。 + [AWS コマンドラインインターフェイス V2](https://docs.aws.amazon.com/goto/cli2/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for C\+\+](https://docs.aws.amazon.com/goto/SdkForCpp/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/kinesis-video-data-2017-09-30/PutMedia) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/kinesis-video-data-2017-09-30/PutMedia)