PutMedia - Amazon Kinesis Video Streams
请求语法URI 请求参数请求正文响应语法响应元素错误示例另请参阅
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

PutMedia

使用此 API 将媒体数据发送到 Kinesis 视频流。

注意

在使用此 API 之前，必须调用 GetDataEndpoint API 来获取终端节点。然后，您在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会话并在有效负载中发送大量媒体数据片段会更容易。对于收到的每个片段，Kinesis Video Streams 都会发送一条或多条确认。潜在的网络问题可能会导致你无法在生成所有这些确认时得到它们。

  • 您可以选择多个连续PutMedia会话，每个会话包含较少的片段，以确保实时获得来自服务的所有确认。

注意

如果您在多个同步PutMedia会话中将数据发送到同一个流，则媒体片段会在流上交错传输。你应该确保在你的应用程序场景中这是可以的。

使用 PutMedia API 时适用以下限制：

  • 客户端每秒PutMedia最多可以调用五次数据流。

  • 客户端每秒最多可以发送五个片段。

  • Kinesis Video Streams 在会话期间以高达 12.5 Mb/秒或 100 Mbps 的速率读取媒体数据。PutMedia

请注意以下限制。在这些情况下，Kinesis Video Streams 会在响应中发送错误确认。

  • 不允许使用时间码跨度超过 10 秒且包含超过 50 MB 数据的片段。

  • 不允许包含三首以上曲目的片段。每个片段中的每一帧必须与片段头中定义的轨道编号相同。此外，每个片段必须包含片段标头中定义的每个轨道的至少一帧。

  • 对于片段元数据中定义的每个轨道，每个片段必须包含至少一帧。

  • 片段中最早的帧时间戳必须晚于前一个片段中的最新帧时间戳。

  • 包含多个 MKV 分段或包含不允许的 MKV 元素（如track*）的 MKV 流也会导致错误确认。

Kinesis Video Streams 将每个传入的片段和相关元数据存储在所谓的 “块” 中。片段元数据包括以下内容：

  • 请求开始时提供的 MKV 标头 PutMedia

  • 以下 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 视频直播分配的唯一片段编号。

注意

当你发出GetMedia请求时，Kinesis Video Streams 会返回包含这些区块的直播。客户端可以根据需要处理元数据。

注意

此操作仅适用于适用于 Java 的Amazon软件开发工具包。其他语言的 Amazon SDK 不支持它。

注意

在通过 API 摄取和存档期间，Kinesis Video Streams 不会解析和验证编解码器私有数据。PutMedia通过 HLS API 使用直播时，KVS 会从 MPEG-TS 和 MP4 片段打包的编解码器私有数据中提取和验证必要的信息。

注意

如果在调用 Kinesis Video Streams 媒体 API 后引发错误，除了 HTTP 状态代码和响应正文外，它还包括以下信息：

  • x-amz-ErrorTypeHTTP 标头 — 除了 HTTP 状态码提供的错误类型外，还包含更具体的错误类型。

  • x-amz-RequestIdHTTP 标头 — 如果您想向其报告问题Amazon，如果提供请求编号，支持团队可以更好地诊断问题。

HTTP 状态码和ErrorType标头都可用于就错误是否可重试以及在何种条件下进行编程决策，并提供有关客户端程序员可能需要采取哪些操作才能成功重试的信息。

有关更多信息，请参阅本主题底部的错误部分以及常见错误。

请求语法

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如 API 概述中所述，Kinesis Video Streams 使用这些信息来计算请求中收到的片段的值。producer_timestamp

有效值：ABSOLUTE | RELATIVE

必需：是

ProducerStartTimestamp

您将此值作为 x-amzn-producer-start-timestamp HTTP 标头传递。

这是制作者开始录制媒体的制作者时间戳（不是请求中特定片段的时间戳）。

StreamARN

您将此值作为 x-amzn-stream-arn HTTP 标头传递。

您要在其中编写媒体内容的 Kinesis 视频流的亚马逊资源名称 (ARN)。如果您未指定streamARN，则必须指定streamName。

长度限制：最小长度为 1。长度上限为 1024。

模式：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。

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

请求正文

请求接受以下二进制数据。

Payload

要写入 Kinesis 视频流的媒体内容。在当前的实现中，Kinesis Video Streams 仅支持具有单个 MKV 分段的 Matroska (MKV) 容器格式。一个分段可以包含一个或多个集群。

注意

每个 MKV 集群都映射到一个 Kinesis 视频流片段。无论你选择什么集群持续时间，都会成为片段持续时间。

响应语法

HTTP/1.1 200

Payload

响应元素

如果此操作成功，则该服务将会发送回 HTTP 200 响应。

响应将以下内容作为 HTTP 正文返回。

Payload

在 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 Id le，则该元素可能会丢失。

  • FragmentNumber-Kinesis Video Streams 生成的片段编号已发送确认信。

  • ErrorId和 ErrorCode-如果AckEventType是ErrorId，则此字段提供相应的错误代码。以下是错误 ID 及其相应的错误代码和错误消息的列表：

    • 4000-STREAM_READ_ERROR-读取数据流时出错。

    • 4001-MAX_FRAGMENT_SIZE_REACHED-片段大小大于允许的最大限制 50 MB。

    • 4002-MAX_FRAGMENT_DURATION_REACHED-片段持续时间大于允许的最大限制，即 10 秒。

    • 4003-MAX_CONNECTION_DURATION_REACHED-连接持续时间大于允许的最大阈值。

    • 4004-FRAGMENT_TIMECODE_LESSER_THAN_PREVIOM-片段时间码小于之前的时间码（在调用中，不能乱序发送片段）。PutMedia

    • 4005-MORE_THAN_ALLOWED_TRACKS_FOUND-在 MKV 中可以找到不止一首曲目。 （已弃用）

    • 4006-INVALID_MKV_DATA-无法将输入流解析为有效的 MKV 格式。

    • 4007-无效_PRODUCER_TIMESTAMP-生产者时间戳无效。

    • 4008-STREAM_NOT_ACTIVE-直播已不存在（已删除）。

    • 4009-FRAGMENT_METADATA_LIMIT_REACHED-已达到片段元数据限制。

    • 4010-TRACK_NUMBER_MISTACH-MKV 帧中的曲目编号与 MKV 标头中的曲目不匹配。

    • 4011-FRAMES_MISSING_FOR_TRACK-该片段不包含 MKV 标题中至少一首曲目的任何帧。

    • 4012-INVALID_FRAGMENT_METADATA-片段元数据名称不能以字符串开头。 Amazon

    • 4500-KMS_KEY_ACCESS_DENIED-访问直播的指定 KMS 密钥被拒绝。

    • 4501-KMS_KEY_DISABLED-直播的指定的 KMS 密钥已禁用。

    • 4502-KMS_KEY_VALIDATION_ERROR-直播的指定的 KMS 密钥验证失败。

    • 4503-KMS_KEY_UNARCLIABLE-直播的指定的 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

调用者使用错误的端点将数据写入流。收到此类异常时，用户必须使用 se APIName t t GetDataEndpoint o 进行调用，PUT_MEDIA并使用响应中的端点调用下一PutMedia次调用。

HTTP 状态代码：400

NotAuthorizedException

调用者无权对给定流执行操作，或者令牌已过期。

HTTP 状态码：401

ResourceNotFoundException

状态码：404，给定名称的流不存在。

HTTP 状态代码：404

示例

确认格式

确认的格式如下：

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

另请参阅

有关在特定语言的 Amazon 软件开发工具包中使用此 API 的更多信息，请参阅以下内容：