YouTube Live Streaming API 概览

借助 YouTube Live Streaming API，您可以在 YouTube 上创建、更新和管理直播活动。使用此 API，您可以安排活动（直播）时间，并将其与代表实际直播内容的视频流关联在一起。

Live Streaming API 实际上由 YouTube Data API 和 YouTube Content ID API 组成。通过 Data API，YouTube 用户可以管理自己的 YouTube 帐号，而YouTube Content ID API让 YouTube 的用户可以与 YouTube 的权利管理系统互动。不过，构成 Live Streaming API 的所有资源都仅用于创建和管理直播活动。

本文档适用于想要编写应用来促进 YouTube 直播的开发者。其中解释了 YouTube 和 API 本身的基本概念。还简要介绍了该 API 支持的不同函数。

核心概念

广播
“广播”表示可以在 YouTube 上观看发生的事件。系统还可以将广播录制并另存为 YouTube 视频，以便用户在直播结束后观看。
溪流
流用于标识正在向 YouTube 传送的音频-视频内容。每个广播都与一个视频流相关联。
广告插入点
广告插入点表示可以插入到直播中的广告插播时间点。

API 用例

以下列表介绍了几种在应用中使用 API 的方法：

  • 安排直播时间并定义直播设置。您的应用可以让用户预定义广播设置，然后选择要应用于特定广播的设置。

  • 关联视频流和广播。

  • 让广播方可以（使用 YouTube Data API）同时定义有关广播及其视频的信息。

  • 简化广播状态（testing、live 等）之间的转换，并允许用户插入广告插入点。

准备工作

  1. 您需要 Google 帐号才能访问 Google API Console、请求 API 密钥以及注册您的应用。

  2. 通过 Google 注册您的应用以提交 API 请求。

  3. 注册应用后，选择 YouTube Data API 作为应用使用的一项服务：

    1. 转到 API Console 并选择您刚刚注册的项目。
    2. 访问“已启用的 API”页面。 在 API 列表中，确保 YouTube Data API v3 和 YouTube Content ID API（如果您是 YouTube 内容合作伙伴）的状态为开启。

  4. 熟悉 JSON（JavaScript 对象表示法）数据格式的核心概念。JSON 是一种与语言无关的常见数据格式，可通过简单的文本方式来表示任意数据结构。如需了解详情，请参阅 json.org。

为 API 请求授权

如上所述，Live Streaming API 使用的技术在 YouTube Data API 或 YouTube Content ID API 中。您可以使用 Content ID API 向 YouTube 提供资产的元数据、所有权信息和政策信息。（直播视频是资产的一个例子。）您还可以通过该 API 为视频声明版权并为您的视频设置广告政策。

本部分介绍了向 Content ID API 发出的请求的授权要求，这与对其他 Live Streaming API 请求进行授权的要求不同。

调用 Data API
API 请求必须由拥有广播 YouTube 频道的 Google 帐号授权。
调用 Content ID API
该 API 请求必须由一个 Google 帐号进行授权，且该帐号需要与广播 YouTube 频道的内容所有者关联。

资源和资源类型

资源是指具有唯一标识符的单个数据实体。下表介绍了您将使用 Live Streaming API 与之互动的不同类型的资源。从技术上讲，所有这些资源都实际定义为 YouTube Data API 或 YouTube Content ID API 的一部分。不过，liveBroadcast、liveStream 和 cuepoint 资源仅用于创建和管理直播活动。

资源
liveBroadcast 包含您在 YouTube 上播放的活动的相关信息。liveBroadcast 资源是 YouTube 视频资源的扩展，可设置与直播相关但与其他 YouTube 视频无关的视频元数据。

因此，一项 liveBroadcast 资源仅对应一个 YouTube 视频资源。 实际上，liveBroadcast 资源和 video 资源具有相同的 ID。使用 Live Streaming API 创建广播后，您可以使用 YouTube Data API 提供有关视频的其他元数据。
liveStream 包含您要向 YouTube 传输的视频串流的相关信息。视频流会提供将向 YouTube 用户广播的内容。创建后，一个 liveStream 资源只能绑定到一个 liveBroadcast 资源。（同样，liveBroadcast 资源只能绑定到一个 liveStream 资源。
cuepoint 在直播视频流中插入广告插入点，可能会触发广告插播时间点。在广播期间，使用 liveBroadcasts.cuepoint 方法插入广告插入点。
video 表示单个 YouTube 视频。如上所述，liveBroadcast 资源是 video 资源的扩展。您可以使用 YouTube Data API 更新有关视频的元数据，例如录制地点或直播观看地区。
videoAdvertisingOptions 定义视频（或广播）的广告设置。您可以使用 YouTube Content ID API 设置广告选项。
asset 代表知识产权，例如电影或电视节目的某一集。在本例中，广播视频是资产。您将使用 YouTube Content ID API 创建和管理 asset 资源。
claim 将视频与视频匹配的资产相关联。您使用 YouTube Content ID API 创建版权主张，以表明自己是广播视频的所有者。
policy 指定相应规则，规定您希望自己的内容在哪些情况下会在 YouTube 上显示，或禁止在 YouTube 上展示。您需要对广播视频应用政策，同时指定 YouTube 将对与您的广播视频匹配的用户上传视频应用政策。

支持的操作

下表显示了该 API 支持的不同方法：

运维
list 检索 (GET) 零个或多个资源的列表。
insert 创建 (POST) 新资源。
update 修改 (PUT) 现有资源以反映请求中的数据。
bind 将 liveBroadcast 资源与 liveStream 资源相关联，或移除此类关联。
transition 更改 liveBroadcast 资源的状态并启动与新状态关联的所有进程。例如，当您将某广播的状态转换为 testing 时，YouTube 就会开始将视频传送至该广播的监视器流中。
delete 移除 (DELETE) 特定资源。

下表列出了不同类型的资源支持的操作。插入、更新或删除资源的操作始终需要用户授权。在某些情况下，list 方法支持授权请求和未授权请求，在这种情况下，未经授权的请求仅检索公开数据，而授权请求也可以检索仅限当前通过身份验证的用户的信息。

支持的操作
list insert update bind transition cuepoint delete
直播
直播

部分资源

该 API 允许且实际上需要检索部分资源，因此应用可避免传输、解析和存储不需要的数据。此方法还可确保 API 更高效地使用网络、CPU 和内存资源。

对于检索或返回 YouTube Data API 资源的任何 API 请求，part 参数都是必需参数。参数用于标识应该包含在 API 响应中的一个或多个顶级（非嵌套）资源属性。例如，liveStream 资源包含以下几个部分：

  • snippet
  • cdn
  • status

所有这些部分都是包含嵌套属性的对象，您可以将这些对象视为 API 服务器可能（也可能不会）检索的元数据字段组。因此，part 参数要求您选择应用实际使用的资源组件。此要求有以下两个重要用途：

  • 它能防止 API 服务器花费时间检索您的应用不使用的元数据字段，从而缩短延迟时间。
  • 它会减少（或消除）应用可能检索到的不必要的数据量，从而减少带宽用量。

随着时间的推移，随着资源添加更多组件，这些优势只会增加，因为您的应用将不再请求它不支持的新属性。

技巧和最佳做法

声明您的内容

如果您希望在直播期间展示广告，则需要在直播开始前声明对广播视频的所有权。如需申领内容，您必须是参与 Content ID 计划的 YouTube 内容合作伙伴。

申领直播视频的流程与认领视频的流程不同。对直播视频提出版权主张时，您需要在视频实际存在之前创建版权主张。此 API 支持这种做法，而广播生命周期文档介绍了可让您创建声明的 YouTube Content ID API 调用。

预览和测试您的内容

收到您的入站视频流后，YouTube 就可以在两个不同的出站视频流中广播该视频：

  • 监控视频流让您可以预览（和测试）视频广播。这是一个只有您自己才能访问的私享直播。仅当广播的监控数据流处于启用状态时，您才能将广播过渡到 testing 阶段。监控流不会显示广告插播时间点。

  • 直播视频流是观众可以看到的直播。您可以将广播的隐私状态设置为 public、private 或 unlisted。。

    您可以选择延迟直播，使其不会与监控视频流同时运行。通过延迟直播，您可以更精细地控制在广播中插入广告插入点的时间。

    但是，延迟直播会导致现场演示者很难与观看的观众互动。此外，延迟直播会增加观看者找到您直播以外来源的重要细节的可能性。例如，如果您直播体育赛事时延迟 60 秒，观看者可能会先通过其他实时新闻媒体了解该赛事中的重要时刻，然后再实际观看。

YouTube 建议您启用直播的监控视频流，以便测试内容。您应该选择自己是否希望控制广告插入点的时间来推迟直播，而不是根据与观众互动或提供活动的实时报道进行延迟。

在直播过程中投放中贴片广告

在广播期间，您可以插入广告插入点，以指明广告插播时间点应尽早或在特定时间在广播中开始。通过广告插播时间点，YouTube 可以在直播期间投放中贴片广告。

广告插播时间点具有以下特征：

  1. 该元素具有预定义的时长，您可以使用 cuepoint 资源的 durationSecs 属性来设置该时长。广告插播结束后，观看者会返回直播。

  2. 发生广告插播时间点后，只有在插入广告插入点时在观看广播的观看者才会在视频播放器中播放广告。观看者刷新播放广播的页面时，或访问者在插入广告插入点后开始观看广播时，广告不会投放。

以下步骤的顺序反映了在直播期间插入广告插播时间点的最佳做法：

设置时间偏移

插入广告插入点时，您可以指定是立即插入广告插入点，还是应插入广播中的特定点。具体选项取决于视频的广播直播是否延迟。

  • 如果您的直播视频流未延迟，您可以立即插入广告插入点，也可以使用 walltimeMs 属性让广告插播时间点开始于特定时间开始。

    • 如需立即启动广告插播时间点，请调用 liveBroadcasts.cuepoint 方法。在请求正文中的资源内，将 insertionOffsetTimeMs 属性的值设为 0，或不要为该属性的值指定 walltimeMs 属性的值。

      重要提示：请注意，观看者不会立即看到生成的广告内容。我们可能要延迟约 30 秒才能将广告内容显示给用户。在此延迟期间，您的直播视频流仍对观看者可见，您需要观看直播视频流来确定广告内容实际显示的时间，而非监控视频流。

    • 如需在特定时间开始此广告插播时间点，请调用 liveBroadcasts.cuepoint 方法，然后使用 walltimeMs 属性指定所需的时间。属性值是一个表示周期时间戳的整数。

  • 如果您的广播流出现延迟，那么您可以立即插入广告插入点（如上所述），指定时钟时间（如上所述），也可以指定时间偏移以确定广告插播时段的开始时间。时间偏移指定了直播中观看者应该看到广告的时间。

    偏移量值以毫秒为单位，从广播的监控信息流的开头算起。请注意，如果您的广播有测试阶段，则监控广播会在您的广播转换为 testing 状态时开始。否则，您的监控信息流会在您的广播转换为 live 状态时开始。

    插入广告插入点时，请将 cuepoint 资源的 insertionOffsetTimeMs 属性设置为所需的偏移量。

计算时间偏移值

如需检索偏移值，请针对正在播放监控流的播放器调用 YouTube Player API 的 getCurrentTime 函数。使用检索到的值将当时的广告插入点插入到广播流中。

可能的偏移时间值的计算公式如下：

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

在 YouTube 无法精确插入广告插入点时，Δ 是可能时间偏移开始和结束的 5 秒钟缓冲区。例如：

  • 广播有五分钟的测试阶段。
  • 广播流会在监控流之后延迟 60 秒。
  • 广播方在转换为 live 状态四分钟后，插入广告插入点。（直播视频流显示三分钟后。）

在本例中，偏移时间可能的值为 [(485,000), (535,000)]。

这些时间以毫秒为单位，并且使用以下值进行计算：

  • elapsed_time=540000 - 调用 liveBroadcasts.cuepoint 方法时，监控流已运行九分钟（540 秒，540000 毫秒）。
  • broadcast_delay=60000 - 直播信息流延迟 60 秒（即 60000 毫秒）。
  • Δ=5000 - 无法可靠地插入广告插入点时的 5 秒钟缓冲区。

问题排查和错误处理

以下准则介绍了如何解决可能出现的具体问题。另请参阅错误文档，了解各个 API 方法可能返回的错误。

  • 当广播从一个状态状态转换到另一个状态时，可能会在 YouTube 完成与转换相关的操作时，暂时为它分配其他状态。例如，如果您发送 liveBroadcasts.transition 请求，将广播状态从 ready 更改为 testing，则 YouTube 会将广播的状态设置为 testStarting，然后完成与状态更改相关的操作。当所有这些操作都完成后，YouTube 会将广播的状态更新为 testing，这表示此次转换已完成。

    如果广播卡住了 testStarting 或 liveStarting 状态，您需要调用 liveBroadcasts.delete 方法并删除该广播。然后创建新广播，将其绑定到您的直播，并继续执行测试流程。

    如 liveBroadcasts.transition 方法的文档中所述，在调用该方法之前，您应确认绑定到广播的流的 status.streamStatus 属性的值为 active。