PutMedia - Amazon Kinesis Video Streams
リクエストの構文URI リクエストパラメータリクエストボディレスポンスの構文レスポンス要素エラー例以下の資料も参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

PutMedia

これを使用してAPI、Kinesis ビデオストリームにメディアデータを送信します。

注記

エンドポイントを取得するには、まず GetDataEndpointAPIを呼び出す必要があります。次に、--endpoint-url parameter を使用して PutMedia リクエストをこのエンドポイントに送信します。

リクエストでは、HTTPヘッダーを使用して、ストリーム名、タイムスタンプ、タイムスタンプ値が絶対値かプロデューサーが記録を開始した時点からの相対値かなどのパラメータ情報を提供します。リクエスト本文を使用してメディアデータを送信します。Kinesis Video Streams は、この を使用してメディアデータを送信するための Matroska (MKV) コンテナ形式のみをサポートしていますAPI。

この を使用してデータを送信するには、次のオプションがあります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方法で使用することは意図されていません。を使用する場合はPutMediaAPI、HTTPチャンク転送エンコーディングを使用して、永続接続を介してフラグメントを継続的に送信します。

  • PutMedia セッションで受信したフラグメントごとに、Kinesis Video Streams は 1 つ以上の確認応答を送信します。クライアント側のネットワークに関する潜在的な考慮事項により、これらの送達確認が生成されても、それらはすべて取得されない場合があります。

    注記

    複数の同時 PutMedia セッションの同じストリームにデータを送信すると、メディアフラグメントがストリームでインターリーブされます。これはアプリケーションのシナリオとして問題ないことを確認する必要があります。

を使用する場合、次の制限が適用されますPutMediaAPI。

  • クライアントは、ストリームごとに 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 でのみ使用できます。他の言語では SDKsで AWS サポートされていません。

注記

Kinesis Video Streams は、 を介した取り込みおよびアーカイブ中にコーデックのプライベートデータを解析および検証しません PutMedia API。 は、 を介してストリームを消費するときに、コーデックのプライベートデータから MPEG-TS およびMP4フラグメントパッケージングの必要な情報をKVS抽出および検証しますHLSAPIs。

注記

Kinesis Video Streams メディア を呼び出した後にエラーがスローされた場合API、HTTPステータスコードとレスポンス本文に加えて、次の情報が含まれます。

  • x-amz-ErrorType HTTP ヘッダー — HTTPステータスコードが提供するものに加えて、より具体的なエラータイプが含まれています。

  • x-amz-RequestId HTTP ヘッダー – 問題を報告したい場合は AWS、リクエスト ID を指定すれば、サポートチームが問題をより適切に診断できます。

HTTP ステータスコードと ErrorType ヘッダーの両方を使用して、エラーが再試行可能かどうか、どのような条件下で再試行できるかをプログラムで決定したり、クライアントプログラマーが再試行を正常に行うためにどのようなアクションを実行する必要があるかについて情報を提供したりできます。

詳細については、このトピックの下部にある[Errors] (エラー) セクションおよび「Common Errors」を参照してください。

リクエストの構文

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

この値を x-amzn-fragment-timecode-typeHTTPヘッダーとして渡します。

フラグメント (ペイロード、HTTPリクエストボディ) のタイムコードが絶対か、 を基準にしているかを示しますproducerStartTimestamp。Kinesis Video Streams は、API概要で説明されているように、この情報を使用して、リクエストで受信したフラグメントproducer_timestampの を計算します。

有効な値: ABSOLUTE | RELATIVE

必須: はい

ProducerStartTimestamp

この値を x-amzn-producer-start-timestampHTTPヘッダーとして渡します。

これは、プロデューサーがメディアの記録を開始したプロデューサーのタイムスタンプです（リクエスト内の特定のフラグメントのタイムスタンプではありません）。

StreamARN

この値を x-amzn-stream-arnHTTPヘッダーとして渡します。

メディアコンテンツを書き込む Kinesis ビデオストリームの Amazon リソースネーム (ARN）。streamARN を指定しない場合は、streamName を指定する必要があります。

長さの制限: 最小長は 1 です。最大長は 1,024 です。

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

StreamName

この値を x-amzn-stream-nameHTTPヘッダーとして渡します。

メディアコンテンツを書き込む Kinesis ビデオストリームの名前。streamName を指定しない場合は、streamARN を指定する必要があります。

長さの制約: 最小長は 1 です。最大長は 256 です。

Pattern: [a-zA-Z0-9_.-]+

リクエストボディ

リクエストは以下のバイナリデータを受け入れます。

Payload

Kinesis ビデオストリームに書き込むメディアコンテンツ。現在の実装では、Kinesis Video Streams は 1 つのMKVセグメントを持つ Matroska (MKV) コンテナ形式のみをサポートしています。セグメントには、1 つまたは複数のクラスターを含めることができます。

注記

各MKVクラスターは Kinesis ビデオストリームフラグメントにマッピングされます。選択したクラスター期間は、フラグメント期間になります。

レスポンスの構文

HTTP/1.1 200

Payload

レスポンス要素

アクションが成功すると、サービスは 200 HTTP レスポンスを返します。

レスポンスは本文として以下を返しますHTTP。

Payload

Kinesis Video Streams が PutMedia リクエストを正常に受信した後、サービスがリクエストヘッダーを検証します。その後、サービスはペイロードの読み取りを開始し、最初に 200 HTTP レスポンスを送信します。

その後、サービスは改行で区切られた一連の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、このフィールドには対応するエラーコードが表示されます。以下は、エラーIDsとそれに対応するエラーコードおよびエラーメッセージのリストです。

    • 4000 - STREAM_READ_ERROR - データストリームの読み取り中にエラーが発生しました。

    • 4001 - MAX_FRAGMENT_SIZE_REACHED - フラグメントサイズが最大制限である 50 MB を超えています。

    • 4002 - MAX_FRAGMENT_DURATION_REACHED - フラグメントの再生時間が最大許容制限を超えています。

    • 4003 - MAX_CONNECTION_DURATION_REACHED - 接続時間が最大許容しきい値を超えています。

    • 4004 - FRAGMENT_TIMECODELESSER_THAN_PREVIOUS - フラグメントタイムコードが以前のタイムコードよりも小さい (PutMedia呼び出し内でフラグメントを順不同で送信することはできません）。

    • 4005 - MORE_THANALLOWED_TRACKS_FOUND - 複数のトラックが にあります (廃止）MKV。

    • 4006 - INVALID_MKV_DATA - 入力ストリームを有効なMKV形式として解析できませんでした。

    • 4007 - INVALID_PRODUCER_TIMESTAMP - 無効なプロデューサータイムスタンプ。

    • 4008 - STREAM_NOT_ACTIVE - ストリームは存在しなくなりました (削除されました）。

    • 4009 - FRAGMENT_METADATALIMIT_REACHED - フラグメントメタデータの制限に達しました。デベロッパーガイドの「制限」セクションを参照してください。

    • 4010 - TRACK_NUMBER_MISMATCH - MKVフレーム内のトラック番号がMKVヘッダー内のトラックと一致しませんでした。

    • 4011 - FRAMES_MISSING_FOR_TRACK - フラグメントにはMKV、ヘッダー内の少なくとも 1 つのトラックのフレームが含まれていませんでした。

    • 4012 - INVALID_FRAGMENT_METADATA - フラグメントメタデータ名は文字列 で始めることはできません AWS_。

    • 4500 - KMS_KEYACCESS_DENIED - ストリームの指定されたKMSキーへのアクセスは拒否されます。

    • 4501 - KMS_KEY_DISABLED - ストリームの指定されたKMSキーは無効です。

    • 4502 - KMS_KEYVALIDATION_ERROR - ストリームの指定されたKMSキーが検証に失敗しました。

    • 4503 - KMS_KEY_UNAVAILABLE - ストリームの指定されたKMSキーは使用できません。

    • 4504 - KMS_KEY_INVALID_USAGE - ストリームの指定されたKMSキーの使用が無効です。

    • 4505 - KMS_KEYINVALID_STATE - ストリームの指定されたKMSキーが無効な状態です。

    • 4506 - KMS_KEYNOT_FOUND - ストリームの指定されたKMSキーが見つかりません。

    • 5000 - INTERNAL_ERROR - 内部サービスエラー。

    • 5001 - ARCHIVAL_ERROR - Kinesis Video Streams がデータストアにフラグメントを保持できませんでした。

注記

プロデューサーは、長時間実行される PutMedia リクエストのペイロードを送信するときに、送達確認のレスポンスを読み取る必要があります。中間のプロキシサーバーでのバッファリングが原因で、プロデューサーは同時に確認応答のチャンクを受信する場合があります。タイムリーに確認応答を受信したいプロデューサーは、PutMedia リクエストごとに送信するフラグメントを少なくすることができます。

エラー

すべてのアクションに共通のエラーについては、「共通エラー」を参照してください。

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       
      }
}

以下の資料も参照してください。

言語固有の 1 つAPIでこれを使用する方法の詳細については AWS SDKs、以下を参照してください。