PutMedia

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

注記

エンドポイントを取得するには、最初に GetDataEndpoint API を呼び出す必要があります。次に、--endpoint-url parameter を使用して 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 つ以上の確認応答を送信します。クライアント側のネットワークに関する潜在的な考慮事項により、これらの確認が生成されるときに、すべての確認を取得できない場合があります。

  注記

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

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 でのみ使用できます。他の言語SDKs では AWS サポートされていません。

注記

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」を参照してください。

リクエストの構文

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-type HTTP ヘッダーとして渡します。

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

有効な値: ABSOLUTE | RELATIVE

必須: はい

ProducerStartTimestamp

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

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

StreamARN

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

メディアコンテンツを書き込む 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-name HTTP ヘッダーとして渡します。

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

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

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

リクエストボディ

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

Payload

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

注記

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

レスポンスの構文

HTTP/1.1 200

Payload

レスポンス要素

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

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

Payload

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

  • 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 リクエストごとに送信するフラグメントを少なくすることができます。

エラー

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

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 コマンドラインインターフェイス

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go v2

• AWS SDK for Java V2

• AWS SDK for JavaScript V3

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3