PutMedia

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

注意

您必须先调用 GetDataEndpoint API 才能获取终端节点。然后使用 --endpoint-url 参数将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 会在响应中发送错误确认。

不允许使用时间码跨度超过允许的最大限制且包含超过 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 Video Streams 分配的唯一片段编号。

注意

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

注意

此操作仅适用于适用于 Java 的 Amazon SDK。其他语言的 Amazon SDK 不支持它。

注意

Kinesis Video Streams 在通过 API 进行摄取和存档期间不会解析和验证编解码器的私有数据。 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 请求正文）中的时间码是绝对的还是相对的。producerStartTimestampKinesis Video Streams 使用此信息来计算producer_timestamp请求中收到的片段的，如 API 概述中所述。

有效值：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 已将片段保存完毕（例如，保存到亚马逊 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，则此字段提供相应的错误代码。以下是错误 ID 及其相应的错误代码和错误消息的列表：
- 4000-STREAM_READ_ERROR-读取数据流时出错。
- 4001-MAX_FRAGMENT_SIZE_REACH-片段大小超过允许的最大限制 50 MB。
- 4002-MAX_FRAGMENT_DURATION_REACH-片段持续时间大于允许的最大限制。
- 4003-MAX_CONNECTION_DURATION_DURATION_REACH-连接持续时间大于允许的最大阈值。
- 4004-FRAGMENT_TIMECODE_LESSER_THAN_PREVIOR-片段时间码小于之前的时间码（在通话中，你不能乱序发送片段）。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 标题中至少一条轨道的任何帧。
- 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_UNFILABLE-直播中指定的 KMS 密钥不可用。
- 4504-KMS_KEY_INVALID_USAGE-直播中指定的 KMS 密钥的使用无效。
- 4505-KMS_KEY_INVALID_STATE-直播中指定的 KMS 密钥处于无效状态。
- 4506-KMS_KEY_NOT_FOUND-找不到直播指定的 KMS 密钥。
- 5000-内部错误-内部服务错误。
- 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       
      }
}

另请参阅

有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

GetMedia

Amazon Kinesis Video Streams 存档媒体