PutMedia - Amazon Kinesis Video Streams
请求语法URI请求参数请求正文响应语法响应元素错误示例另请参阅

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

PutMedia

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

注意

您必须先调用GetDataEndpointAPI以获取终端节点。然后使用 --endpoint-url 参数将PutMedia请求发送到此端点。

在请求中，您可以使用HTTP标头提供参数信息，例如直播名称、时间戳以及时间戳值是绝对值还是相对于制作人开始录制的时间。您使用请求正文发送媒体数据。Kinesis Video Streams 仅支持 Matroska MKV () 容器格式，用于使用它发送媒体数据。API

您可以使用以下选项来使用它发送数据API：

  • 实时发送媒体数据：例如，安全摄像机可以在生成帧时实时发送帧。这种方法最大限度地减少了视频录制和通过线路发送的数据之间的延迟。这被称为连续生产者。在这种情况下，消费者应用程序可以实时或在需要时读取流。

  • 离线发送媒体数据（分批）：例如，机身摄像机可能会录制数小时的视频并将其存储在设备上。稍后，当您将摄像机连接到坞站端口时，摄像机可以启动PutMedia会话，将数据发送到 Kinesis 视频流。在这种情况下，延迟不是问题。

使用它时API，请注意以下注意事项：

  • 您必须指定 streamName 或 streamARN，但不能同时指定两者。

  • 为了能够在主机上或通过控制台播放媒体HLS，每个片段的轨道 1 应包含 h.264 编码的视频，片段元数据中的 CodeCid 应为 “V_ MPEGISO/AVC”，片段元数据应包含AVCC格式化的 h.264 编解码器私有数据。或者，每个片段的轨道 2 应包含AAC已编码的音频，片段元数据中的 CodeCid 应为 “A_AAC”，片段元数据应包含AAC编解码器私有数据。

  • 您可能会发现，使用单个长时间运行的PutMedia会话并在有效负载中发送大量媒体数据片段会更容易。对于收到的每个片段，Kinesis Video Streams 都会发送一个或多个致谢。潜在的网络考虑因素可能会导致您在生成这些确认时无法获得所有这些确认。

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

注意

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

使用时适用以下限制 PutMediaAPI：

  • 每个直播客户端每秒PutMedia最多可以呼叫五次。

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

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

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

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

  • 不允许包含超过三首曲目的片段。每个片段中的每个帧必须与片段标题中定义的轨道之一具有相同的轨道编号。此外，对于片段标题中定义的每个轨道，每个片段必须至少包含一个帧。

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

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

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

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 SDK 的。其他语言不支持它。 AWS SDKs

注意

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

注意

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

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

  • x-amz-RequestIdHTTP标题——如果你想向报告问题 AWS，如果给出请求编号，支持团队可以更好地诊断问题。

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-typeHTTP标题传递。

表示片段（有效负载、HTTP请求正文）中的时间码是绝对时间码还是相对时间码。producerStartTimestamp如概述中所述，Kinesis Video Streams 使用此信息来计算producer_timestamp请求中收到的片段API的。

有效值：ABSOLUTE | RELATIVE

必需：是

ProducerStartTimestamp

您可以将此值作为x-amzn-producer-start-timestampHTTP标题传递。

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

StreamARN

您可以将此值作为x-amzn-stream-arnHTTP标题传递。

您要在其中编写媒体内容的 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-nameHTTP标题传递。

您要在其中写入媒体内容的 Kinesis 视频流的名称。如果未指定streamName，则必须指定streamARN。

长度限制：最小长度为 1。最大长度为 256。

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

请求正文

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

Payload

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

注意

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

响应语法

HTTP/1.1 200

Payload

响应元素

如果操作成功，服务将发回 HTTP 200 响应。

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

Payload

Kinesis Video Streams 成功收到PutMedia请求后，该服务将验证请求标头。然后，该服务开始读取有效载荷并首先发送 HTTP 200 响应。

然后，该服务返回一个流，其中包含一系列由换行符分隔的JSONAcknowledgement对象（对象）。确认是在发送媒体数据的同一连接上接收的。一个PutMedia请求可能有许多确认信息。每个键值对Acknowledgement由以下键值对组成：

  • AckEventType-确认所代表的事件类型。

    • 缓冲：Kinesis Video Streams 已开始接收片段。当收到片段数据的第一个字节时，Kinesis Video Streams 会发送第一个缓冲确认。

    • 已收到：Kinesis Video Streams 收到了整个片段。如果您未将流配置为保留数据，则生产者可以在收到此确认后停止缓冲片段。

    • 已@@ 保存：Kinesis Video Streams 已将片段保存完毕（例如，保存到亚马逊 S3）。如果您将流配置为保留数据，则会收到此确认。收到此确认后，制作者可以停止缓冲片段。

    • 错误：Kinesis Video Streams 在处理片段时遇到了错误。您可以查看错误代码并确定下一步的操作方案。

    • 闲置：会PutMedia话正在进行中。但是，Kinesis Video Streams 目前没有接收数据。Kinesis Video Streams 在最后一次收到数据后最长 30 秒内定期发送此确认。如果在 30 秒内没有收到任何数据，Kinesis Video Streams 将关闭请求。

      注意

      这种确认可以帮助生产者确定PutMedia连接是否处于活动状态，即使它没有发送任何数据。

  • FragmentTimecode-发送确认的片段时间码。

    如果为 Id le，则可能缺少AckEventType该元素。

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

  • ErrorIdand 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-已达到片段元数据限制。请参阅开发者指南的 “限制” 部分。

    • 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请求中发送更少的片段。

错误

有关所有操作的常见错误的信息，请参阅常见错误。

ClientLimitExceededException

Kinesis Video Streams 已限制该请求，因为你已超过允许的客户端调用限制。稍后再尝试拨打电话。

HTTP状态码：400

ConnectionLimitExceededException

Kinesis Video Streams 已限制该请求，因为您已超过允许的客户端连接限制。

HTTP状态码：400

InvalidArgumentException

此输入参数的值无效。

HTTP状态码：400

InvalidEndpointException

呼叫者使用了错误的端点将数据写入流。收到此类异常后，用户必须在APIName设置为的情况下调GetDataEndpoint用，PUT_MEDIA并使用响应中的端点来调用下一个PutMedia调用。

HTTP状态码：400

NotAuthorizedException

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

HTTP状态码：401

ResourceNotFoundException

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

HTTP状态码：404

示例

确认格式

确认的格式如下：

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

另请参阅

有关API在一种特定语言中使用此功能的更多信息 AWS SDKs，请参阅以下内容：