本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # PutMedia 使用此 API 向 Kinesis 视频流发送媒体数据。 **注意** 您必须先调用 `GetDataEndpoint` API 才能获取终端节点。然后使用 [--endpoint-url 参数将`PutMedia`请求发送到此端点](https://docs.aws.amazon.com/cli/latest/reference/)。 在请求中，您可以使用 HTTP 标头提供参数信息，例如直播名称、时间戳以及时间戳值是绝对值还是相对于制作人开始录制的时间。您使用请求正文发送媒体数据。Kinesis Video Streams 仅支持 Matroska (MKV) 容器格式，用于使用此 API 发送媒体数据。 您可以使用以下选项来使用此 API 发送数据： + 实时发送媒体数据：例如，安全摄像机可以在生成帧时实时发送帧。这种方法最大限度地减少了视频录制和通过线路发送的数据之间的延迟。这被称为连续生产者。在这种情况下，消费者应用程序可以实时或在需要时读取流。 + 离线发送媒体数据（分批）：例如，机身摄像机可能会录制数小时的视频并将其存储在设备上。稍后，当您将摄像机连接到坞站端口时，摄像机可以启动`PutMedia`会话，将数据发送到 Kinesis 视频流。在这种情况下，延迟不是问题。 使用此 API 时，请注意以下注意事项： + 您必须指定 `streamName` 或 `streamARN`，但不能同时指定两者。 + 为了能够在主机上或通过 HLS 播放媒体，每个片段的轨道 1 应包含 h.264 编码的视频，片段元数据中的 CodeCid 应为 “V\$1”，片段元数据应包含 AVCC 格式MPEG/ISO/AVC的 h.264 编解码器私有数据。或者，每个片段的轨道 2 应包含 AAC 编码的音频，片段元数据中的 CodeCid 应为 “A\$1AAC”，片段元数据应包含 AAC 编解码器私有数据。 + 该 `PutMedia` API 旨在通过长时间运行的连接作为流媒体 API 运行。它不打算 RESTful 以传统方式使用，即为每个片段建立并关闭一个新的 HTTP 连接。使用 `PutMedia` API 时，使用 HTTP 分块传输编码通过持久连接连续发送片段。 + 对于`PutMedia`会话中收到的每个片段，Kinesis Video Streams 都会发送一个或多个确认。潜在的客户端网络考虑因素可能会导致您在生成这些确认时无法获得所有这些确认。 **注意** `PutMedia`用作长时间运行的流媒体连接，在单个持久连接中发送多个片段。如果你尝试多个并发`PutMedia`连接，Kinesis Video Streams 会因错误而限制最新的连接。`ConnectionLimitExceededException` 使用 `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` \$1 片段时间码 如果`fragmentTimeCodeType`是绝对的，那么 `producer_timestamp`= 片段时间码（转换为毫秒） + 由 Kinesis Video Streams 分配的唯一片段编号。 **注意** 当你提出`GetMedia`请求时，Kinesis Video Streams 会返回这些区块的直播。客户端可以根据需要处理元数据。 **注意** 此操作仅适用于适用于 Java 的 AWS SDK。其他语言不支持它。 AWS SDKs **注意** Kinesis Video Streams 在通过 API 摄取和存档期间不会解析和验证编解码器的私有数据。 PutMedia KVS 从 MPEG-TS 的编解码器私有数据中提取并验证通过 HLS 消费流时使用的必要信息，并 MP4 进行片段打包。 APIs **注意** 如果在调用 Kinesis Video Streams 媒体 API 后出现错误，则除了 HTTP 状态代码和响应正文外，还会包含以下信息： `x-amz-ErrorType`HTTP 标头 — 除了 HTTP 状态码提供的错误类型外，还包含更具体的错误类型。 `x-amz-RequestId`HTTP 标头 — 如果你想向报告问题 AWS，如果给出请求编号，支持团队可以更好地诊断问题。 HTTP 状态码和 ErrorType 标头都可用于对错误是否可重试以及在什么条件下做出编程决策，并提供有关客户端程序员可能需要采取哪些操作才能成功重试的信息。 有关更多信息，请参阅本主题底部的**错误**部分以及[常见错误](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/CommonErrors.html)。 ## 请求语法 ``` 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](#API_dataplane_PutMedia_RequestSyntax) ** 您将此值作为 `x-amzn-fragment-timecode-type` HTTP 标头进行传递。 表示片段（有效负载、HTTP 请求正文）中的时间码是绝对的还是相对的。`producerStartTimestamp`Kinesis Video Streams 使用此信息来计算`producer_timestamp`请求中收到的片段的，如 API 概述中所述。 有效值：`ABSOLUTE | RELATIVE` 是否必需：是 ** [ProducerStartTimestamp](#API_dataplane_PutMedia_RequestSyntax) ** 您将此值作为 `x-amzn-producer-start-timestamp` HTTP 标头进行传递。 这是制作人开始录制媒体的制作人时间戳（不是请求中特定片段的时间戳）。 ** [StreamARN](#API_dataplane_PutMedia_RequestSyntax) ** 您将此值作为 `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](#API_dataplane_PutMedia_RequestSyntax) ** 您将此值作为 `x-amzn-stream-name` HTTP 标头进行传递。 您要在其中写入媒体内容的 Kinesis 视频流的名称。如果未指定`streamName`，则必须指定`streamARN`。 长度限制：最小长度为 1。最大长度为 256。 模式：`[a-zA-Z0-9_.-]+` ## 请求正文 请求接受以下二进制数据。 ** [Payload](#API_dataplane_PutMedia_RequestSyntax) ** 要写入 Kinesis 视频流的媒体内容。在当前的实现中，Kinesis Video Streams 仅支持带有单个 MKV 片段的 Matroska (MKV) 容器格式。一个区段可以包含一个或多个集群。 每个 MKV 集群都映射到 Kinesis 视频流片段。无论您选择哪个集群持续时间，都将成为片段持续时间。 ## 响应语法 ``` HTTP/1.1 200 Payload ``` ## 响应元素 如果此操作成功，则该服务将会发送回 HTTP 200 响应。 响应将以下内容作为 HTTP 正文返回。 ** [Payload](#API_dataplane_PutMedia_ResponseSyntax) ** 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 生成的已发送确认的片段编号。 + `ErrorId`and `ErrorCode`-如果`AckEventType`是`Error`，则此字段提供相应的错误代码。以下是错误及其对应的错误 IDs 代码和错误消息的列表： + 4000-STREAM\$1READ\$1ERROR-读取数据流时出错。 + 4001-MAX\$1FRAGMENT\$1SIZE\$1REACH-片段大小超过允许的最大限制 50 MB。 + 4002-MAX\$1FRAGMENT\$1DURATION\$1REACH-片段持续时间大于允许的最大限制。 + 4003-MAX\$1CONNECTION\$1DURATION\$1DURATION\$1REACH-连接持续时间大于允许的最大阈值。 + 4004-FRAGMENT\$1TIMECODE\$1LESSER\$1THAN\$1PREVIOR-片段时间码小于之前的时间码（在通话中，你不能乱序发送片段）。`PutMedia` + 4005-MORE\$1THAN\$1ALLOWED\$1TRACKS\$1FOUND-在 MKV 中发现了不止一首曲目。 （已弃用） + 4006-INVALID\$1MKV\$1DATA-无法将输入流解析为有效的 MKV 格式。 + 4007-INVALID\$1PRODUCER\$1TIMESTAMP-生产者时间戳无效。 + 4008-STREAM\$1NOT\$1ACTIVE-直播已不存在（已删除）。 + 4009-FRAGMENT\$1METADATA\$1LIMIT\$1REACH-已达到片段元数据限制。请参阅开发者指南的 “[限制](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)” 部分。 + 4010-TRACK\$1NUMBER\$1MISMATCH-MKV 帧中的曲目编号与 MKV 标题中的曲目不匹配。 + 4011-FRAMES\$1MISSING\$1FOR\$1TRACK-该片段不包含 MKV 标题中至少一条轨道的任何帧。 + 4012-INVALID\$1FRAGMENT\$1METADATA-片段元数据名称不能以字符串开头。` AWS_` + 4500-KMS\$1KEY\$1ACCESS\$1DENIED-访问直播中指定的 KMS 密钥被拒绝。 + 4501-KMS\$1KEY\$1DISABLED-直播中指定的 KMS 密钥已禁用。 + 4502-KMS\$1KEY\$1VALIDATION\$1ERROR-直播中指定的 KMS 密钥验证失败。 + 4503-KMS\$1KEY\$1UNFILABLE-直播中指定的 KMS 密钥不可用。 + 4504-KMS\$1KEY\$1INVALID\$1USAGE-直播中指定的 KMS 密钥的使用无效。 + 4505-KMS\$1KEY\$1INVALID\$1STATE-直播中指定的 KMS 密钥处于无效状态。 + 4506-KMS\$1KEY\$1NOT\$1FOUND-找不到直播指定的 KMS 密钥。 + 5000-内部错误-内部服务错误。 + 5001-ARCHIVAL\$1ERROR-Kinesis Video Streams 未能将片段保存到数据存储中。 生产者在为长时间运行的`PutMedia`请求发送有效负载时，应阅读响应以进行确认。由于中间代理服务器上的缓冲，生产者可能会同时收到大量确认。想要及时收到确认的制作者可以在每个`PutMedia`请求中发送更少的片段。 ## 错误 有关所有操作的常见错误的信息，请参阅[常见错误类型](CommonErrors.md)。 ** 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，请参阅以下内容： + [AWS 命令行界面 V2](https://docs.aws.amazon.com/goto/cli2/kinesis-video-data-2017-09-30/PutMedia) + [AWS 适用于.NET 的 SDK V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/kinesis-video-data-2017-09-30/PutMedia) + [AWS 适用于 C\$1\$1 的 SDK](https://docs.aws.amazon.com/goto/SdkForCpp/kinesis-video-data-2017-09-30/PutMedia) + [AWS 适用于 Go v2 的 SDK](https://docs.aws.amazon.com/goto/SdkForGoV2/kinesis-video-data-2017-09-30/PutMedia) + [AWS 适用于 Java 的 SDK V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/kinesis-video-data-2017-09-30/PutMedia) + [AWS JavaScript V3 版软件开发工具包](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/kinesis-video-data-2017-09-30/PutMedia) + [AWS 适用于 Kotlin 的 SDK](https://docs.aws.amazon.com/goto/SdkForKotlin/kinesis-video-data-2017-09-30/PutMedia) + [AWS 适用于 PHP 的 SDK V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/kinesis-video-data-2017-09-30/PutMedia) + [AWS Python 软件开发工具包](https://docs.aws.amazon.com/goto/boto3/kinesis-video-data-2017-09-30/PutMedia) + [AWS 适用于 Ruby V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForRubyV3/kinesis-video-data-2017-09-30/PutMedia)