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

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

GetDASHStreamingSessionURL

检索该流的 MPEG 动态自适应流（DASH）。然后，您可以在媒体播放器中打开 URL 以查看直播内容。

StreamName和StreamARN参数都是可选的，但在调用此 API 操作StreamARN时必须指定StreamName或。

要通过 MPEG-DASH 提供数据，Amazon Kinesis 视频流有以下要求：

  • 媒体必须包含 h.264 或 h.265 编码的视频以及（可选）AAC 或 G.711 编码的视频。具体而言，轨道 1 的 编解码器 ID 应为 V_MPEG/ISO/AVC（对于 h.264）或 V_MPEGH/ISO/HEVC（对于 H.265）。（可选）轨道 2 的编解码器 ID 应为 A_AAC（对于 AAC）或 A_MS/ACM（对于 G.711）。

  • 数据保留必须大于 0。

  • 对于 H.264 格式的高级视频编码 (AVC) 和 H.265 格式的 HEVC，各个片段的视频轨道必须包含编解码器专用数据。有关更多信息，请参阅 MPEG-4 规范 ISO/IEC 14496-15。有关使流数据适应给定格式的信息，请参阅 NAL 适应标志。

  • 各个片段的音频轨道（如果存在）必须包含 AAC 格式 (AAC specification ISO/IEC 13818-7) 或 MS Wave 格式的编解码器专用数据。

以下过程介绍了如何在 Kinesiis 视频直播中使用 MPEG-Dash的视频流：

  1. 使用获取终端节点 GetDataEndpoint，GET_DASH_STREAMING_SESSION_URL为APIName参数指定。

  2. 使用以下方法检索 MPEG-DASH 网址。GetDASHStreamingSessionURLKinesis Video Streams 创建 MPEG-DASH 流媒体会话，用于使用 MPEG-DASH 协议访问直播中的内容。 GetDASHStreamingSessionURL返回会话的 MPEG-DASH 清单（使用 MPEG-DASH 进行直播所需的根资源）的经过身份验证的 URL（包括加密的会话令牌）。

    注意

    不要将此令牌共享或存储在未经授权的实体可以访问的地方。该令牌提供对直播内容的访问权限。使用与Amazon证书相同的措施保护令牌。

    通过清单提供的媒体仅包含请求的流、时间范围和格式。没有其他媒体数据（例如请求窗口以外的帧或备用比特率）可用。

  3. 向支持 MPEG-DASH 协议的媒体播放器提供 MPEG-DASH 清单的 URL（包含加密会话令牌）。Kinesis Video Streams 通过清单 URL 提供初始化片段和媒体片段。初始化片段包含流的编解码器私有数据，以及设置视频或音频解码器和渲染器所需的其他数据。媒体片段包含编码的视频帧或编码的音频样本。

  4. 媒体播放器接收经过身份验证的 URL 并正常请求流元数据和媒体数据。当媒体播放器请求数据时，它会调用以下操作：

    • getDashManifest：检索 MPEG DASH 清单，其中包含您要播放的媒体的元数据。

    • getMP4InitFragment：检索 MP4 初始化片段。媒体播放器通常在加载任何媒体片段之前加载初始化片段。此片段包含 “fytp” 和 “moov” MP4 原子，以及初始化媒体播放器解码器所需的子原子。

      初始化片段与 Kinesis 视频流中的片段不对应。它仅包含流和相应轨道的编解码器私有数据，媒体播放器需要这些数据来解码媒体帧。

    • getMP4MediaFragment：检索 MP4 媒体片段。这些片段包含 “moof” 和 “mdat” MP4 原子及其子原子，包含编码片段的媒体帧及其时间戳。

      注意

      在流媒体会话中提供第一个媒体片段后，任何不包含相同编解码器私有数据的片段都会在加载这些不同的媒体片段时返回错误。因此，编解码器私有数据不应在会话中的片段之间更改。这也意味着，如果流中的片段从仅包含视频变为同时包含音频和视频，则会话将失败。

      通过此操作检索的数据是可计费的。详情请参阅定价。

注意

有关适用于 MPEG-DASH 会话的限制，请参阅 Kinesis Video Streams 限制。

您可以通过监控GetMP4MediaFragment.OutgoingBytes亚马逊CloudWatch指标来监控媒体播放器消耗的数据量。有关使用CloudWatch监视 Kinesis Video Streams 的信息，请参阅监控 Kinesis Video Streams。有关定价信息，请参阅 Amazon Kinesis Video Streams 定价和Amazon定价。HLS 会话和传出Amazon数据均收取费用。

有关 HLS 的更多信息，请参阅 Apple 开发者网站上的 HTTP 直播。

重要

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

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

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

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

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

请求语法

POST /getDASHStreamingSessionURL HTTP/1.1
Content-type: application/json

{
   "DASHFragmentSelector": { 
      "FragmentSelectorType": "string",
      "TimestampRange": { 
         "EndTimestamp": number,
         "StartTimestamp": number
      }
   },
   "DisplayFragmentNumber": "string",
   "DisplayFragmentTimestamp": "string",
   "Expires": number,
   "MaxManifestFragmentResults": number,
   "PlaybackMode": "string",
   "StreamARN": "string",
   "StreamName": "string"
}

URI 请求参数

该请求不使用任何 URI 参数。

请求正文

请求接受采用 JSON 格式的以下数据。

DASHFragmentSelector

所请求片段的时间范围和时间戳的来源。

如果是ON_DEMAND或，则此参数PlaybackMode是必需的LIVE_REPLAY。如果是，则此参数是可选PlaybackMode的LIVE。如果PlaybackMode是LIVE，则FragmentSelectorType可以设置，但TimestampRange不应设置。如果PlaybackMode是ON_DEMAND或LIVE_REPLAY，则TimestampRange必须同时设置FragmentSelectorType和。

类型：DASHFragmentSelector 对象

必需：否

DisplayFragmentNumber

片段在清单文件中根据其在会话中的序列号进行识别。如果设置DisplayFragmentNumber为ALWAYS，则 Kinesis Video Streams 片段编号将添加到清单文件中的每个 S 元素中，其属性名称为 “kvs: fn”。这些片段编号可用于记录或与其他 API 一起使用（例如GetMedia和GetMediaForFragmentList）。要利用这些自定义属性，必须使用自定义 MPEG-DASH 媒体播放器。

默认值为 NEVER。

类型：字符串

有效值：ALWAYS | NEVER

必需：否

DisplayFragmentTimestamp

根据 MPEG-DASH 规范，可以使用清单本身中的属性推导清单文件中片段的挂钟时间。但是，通常，兼容 MPEG-DASH 的媒体播放器无法正确处理媒体时间轴中的空白。Kinesis Video Streams 调整清单文件中的媒体时间轴，以允许播放不连续的媒体。因此，从清单文件中得出的挂钟时间可能不准确。如果设置DisplayFragmentTimestamp为ALWAYS，则会将准确的片段时间戳添加到清单文件中的每个 S 元素，其属性名称为 “kvs: ts”。要利用此自定义属性，必须使用自定义 MPEG-DASH 媒体播放器。

默认值为 NEVER。如果DASHFragmentSelector是SERVER_TIMESTAMP，则时间戳将是服务器启动时间戳。同样，如果DASHFragmentSelector是PRODUCER_TIMESTAMP，则时间戳将是生产者启动时间戳。

类型：字符串

有效值：ALWAYS | NEVER

必需：否

Expires

请求的会话到期之前的时间（以秒为单位）。此值可以介于 300（5 分钟）和 43200（12 小时）之间。

会话到期后，无法对该会话发出新的呼叫GetDashManifestGetMP4InitFragment、或GetMP4MediaFragment呼叫。

默认值为 300 (5 分钟)。

类型：整数

有效值值值值值值值值值值值值值值值值 最大值为 43200。

必需：否

MaxManifestFragmentResults

在 MPEG-DASH 清单中返回的最大片段数。

如果PlaybackMode为LIVE，则返回不超过此值的最新片段。如果PlaybackMode为ON_DEMAND，则返回最旧的片段，最多返回此最大值。

当实时 MPEG-DASH 清单中有更多可用的片段时，视频播放器通常会在开始播放之前缓冲内容。增加缓冲区大小会增加播放延迟，但会降低播放期间发生重新缓冲的可能性。我们建议实时 MPEG-DASH 清单至少包含 3 个片段和最多 10 个片段。

如果是LIVE或，则默认为 5 个片段PlaybackMode，如果是LIVE_REPLAY，则默认为 1,000 个片段ON_DEMAND。PlaybackMode

1000 个片段的最大值对应于包含 1 秒片段的直播中超过 16 分钟的视频，以及包含 10 秒片段的直播中超过 2 个半小时的视频。

类型：长整型

有效范围：最小值为 1。值值值值值值值值值值值

必需：否

PlaybackMode

是检索实时数据、实时重播数据，还是存档的按需数据。

三种类型的会话的功能值值值值为：。

  • LIVE：对于此类会话，MPEG-DASH 清单会在可用的最新片段时不断更新。我们建议媒体播放器每隔一秒检索新的清单。在媒体播放器中播放此类会话时，用户界面通常会显示 “实时” 通知，没有用于在播放窗口中选择要显示的位置的清除器控件。

    注意

    在LIVE模式下，即使片段之间存在间隔（即缺少片段），最新的可用片段也会包含在 MPEG-DASH 清单中。像这样的间隙可能会导致媒体播放器停止或导致播放跳转。在此模式下，如果片段比播放列表中的最新片段更旧，则不会将其添加到 MPEG-DASH 清单中。如果在将后续片段添加到清单后缺失的片段变得可用，则不会添加较旧的片段，也不会填补空白。

  • LIVE_REPLAY：对于这种类型的会话，MPEG-DASH 清单的更新方式与LIVE模式更新方式类似，不同之处在于它从包含给定开始时间的片段开始。碎片不是在摄取时添加，而是在下一个片段的持续时间结束时添加碎片。例如，如果会话中的片段长度为两秒，则每两秒钟向清单中添加一个新片段。此模式非常有用，可以从检测到事件时开始播放，并继续直播截至创建会话时尚未收录的流媒体。此模式还可用于流式传输以前存档的媒体，而不受该ON_DEMAND模式中 1,000 个片段限制的限制。

  • ON_DEMAND：对于此类会话，MPEG-DASH 清单包含会话的所有片段，最多不超过中指定的数字。MaxManifestFragmentResults每个会话只能检索一次清单。在媒体播放器中播放此类会话时，用户界面通常会显示一个用于选择播放窗口中要显示的位置。

在所有播放模式下，如果FragmentSelectorType是PRODUCER_TIMESTAMP，并且有多个片段的开始时间戳相同，则片段编号较大的片段（即较新的片段）将包含在 MPEG-DASH 清单中。其他片段不包括在内。具有不同时间戳但持续时间重叠的片段仍包含在 MPEG-DASH 清单中。这可能会导致媒体播放器出现意外行为。

默认为 LIVE。

类型：字符串

有效值：LIVE | LIVE_REPLAY | ON_DEMAND

必需：否

StreamARN

要检索其MPEG-Dash清单网址的流的 Amazon 资源名称（ARN）。

必须指定StreamName或StreamARN。

类型：字符串

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

模式：arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

必需：否

StreamName

要检索其MPEG-Dash清单网址的视频流的名称。

必须指定StreamName或StreamARN。

类型：字符串

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

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

必需：否

响应语法

HTTP/1.1 200
Content-type: application/json

{
   "DASHStreamingSessionURL": "string"
}

响应元素

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

服务以 JSON 格式返回的以下数据。

DASHStreamingSessionURL

媒体播放器可用于检索 MPEG-DASH 清单的 URL（包含会话令牌）。

类型：字符串

错误

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

ClientLimitExceededException

Kinesis Video Streams 限制了请求，因为你已经超过了限制。稍后再试打电话。有关值值值值值值值值值值值值值值值值值值值 Kinesis Video Streams 值值值值

HTTP 状态代码：400

InvalidArgumentException

指定的参数超出了其限制、不受支持或无法使用。

HTTP 状态代码：400

InvalidCodecPrivateDataException

至少一个视频流轨道中的编解码器私有数据对此操作无效。

HTTP 状态代码：400

MissingCodecPrivateDataException

在视频流的至少一条曲目中未发现编解码器私有数据。

HTTP 状态代码：400

NoDataRetentionException

已为不保留数据（即 a 为 0）DataRetentionInHours的流请求流式传输会话。

HTTP 状态代码：400

NotAuthorizedException

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

HTTP 状态代码：400。

ResourceNotFoundException

GetImages当 Kinesis Video Streams 找不到你指定的直播时，会引发这个错误。

GetHLSStreamingSessionURL如果请求在请求的时间范围内没有分段PlaybackMode的流，ON_DEMAND或者LIVE_REPLAY请求带有或的会话来处理在请求的时间范围内没有片段的流，或者如果请求PlaybackMode的会话LIVE是针对过去 30 秒内没有分段的流，则会GetDASHStreamingSessionURL抛出这个错误。

HTTP 状态代码：404

UnsupportedStreamMediaTypeException

无法根据播放会话的第一个片段中轨道的编解码器 ID 来确定媒体的类型（例如，h.264 或 h.265 视频或 ACC 或 G.711 音频）。轨道 1 的编解码器 ID 应为V_MPEG/ISO/AVC，轨道 2 的编解码器 ID 应为（可选）。A_AAC

HTTP 状态代码：400

另请参阅

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