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 的权利管理系统互动。不过，构成 Live Streaming API 的所有资源都仅用于创建和管理直播活动。
本文档面向希望编写应用以方便在 YouTube 上进行直播的开发者。它介绍了 YouTube 和 API 本身的基本概念，还概述了 API 支持的不同功能。
核心概念
- 广播
- 广播 表示可以在 YouTube 上观看的实时活动。广播也可以录制并保存为 YouTube 视频，以便用户在活动结束后观看。
- 视频流
- 视频流 用于标识向 YouTube 传输的音频视频内容。每个广播都与一个视频流相关联。
- 提示点
- cuepoint 表示可以插入到直播中的广告插播时间点。
API 使用场景
以下列表列出了在应用中使用 API 的几种方式：
-
安排广播并定义广播设置。您的应用可以允许用户预先定义广播设置，然后选择要应用于特定广播的设置。
-
将视频流与广播相关联。
-
允许广播者同时定义有关广播及其视频的信息（使用 YouTube Data API）。
-
简化广播状态（例如
testing或live）之间的转换，并允许用户插入提示点。
前期准备
-
您需要一个 Google 账号才能访问 Google Cloud console、请求 API 密钥和注册应用。
-
通过 Google 注册您的应用以提交 API 请求。
-
注册应用后，选择 YouTube Data API 作为应用使用的服务之一：
- 前往 Cloud console，然后选择您刚刚注册的项目。
- 访问“已启用的 API”页面。 在 API 列表中，确保 YouTube Data API v3 和（如果您是 YouTube 内容合作伙伴）YouTube Content ID API 的状态为开启 。
-
熟悉 JavaScript 对象表示法 (JSON) 数据格式的核心概念。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 请求必须由与拥有广播 YouTube 频道的内容所有者相关联的 Google 账号授权。
资源和资源类型
资源是指具有唯一标识符的单个数据实体。下表介绍了您将使用
交互的不同类型的资源。
Live Streaming API从技术上讲，所有这些资源实际上都定义为
YouTube Data API
或 YouTube Content ID API 的一部分。不过，
liveBroadcast、
liveStream 和
cuepoint 资源
仅用于创建和管理直播活动。
| 资源 | |
|---|---|
liveBroadcast |
包含有关您在 YouTube 上广播的活动的信息。A
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 | |
| liveBroadcast | |||||||
| liveStream | |||||||
部分资源
API 允许（实际上是要求）检索部分资源，以便应用避免传输、解析和存储不需要的数据。这种方法还可以确保 API 更高效地使用网络、CPU 和内存资源。
part 参数是检索或返回 YouTube Data API 资源的任何 API 请求的必需参数。该参数用于标识应包含在 API 响应中的一个或多个顶级（非嵌套）资源属性。例如，liveStream 资源具有以下部分：
snippetcdnstatus
所有这些部分都是包含嵌套属性的对象，您可以将这些对象视为 API 服务器可能会（也可能不会）检索的元数据字段组。因此，part 参数要求您选择应用实际使用的资源组件。此要求有两个重要用途：
- 它可以防止 API 服务器花费时间检索应用不使用的元数据字段，从而减少延迟。
- 它可以减少应用可能检索的不必要数据量，从而减少带宽使用量。
随着时间的推移，随着资源添加更多部分，这些优势只会增加，因为您的应用不会请求它不支持的新引入的属性。
技巧和最佳做法
声明您的内容
如果您想在广播期间展示广告，则需要在活动开始前声明广播视频的所有权。如需声明内容的所有权，您必须是参与 Content ID 计划的 YouTube 内容合作伙伴。
声明直播视频所有权的过程与声明普通视频所有权的过程不同。声明实时视频所有权时，您需要在视频实际存在之前创建版权主张。API 支持此操作，广播文档的生命周期介绍了可让您创建版权主张的 YouTube Content ID API 调用。
预览和测试您的内容
收到入站视频流后，YouTube 可以在两个不同的出站视频流中广播该视频：
-
监控视频流 可让您预览（和测试）视频广播。这是一个私密视频流，只有您可以访问。只有在广播的监控视频流已启用时，您才能将广播转换为
testing阶段。监控视频流不会显示广告插播时间点。 -
广播视频流 是您的受众群体可见的视频流。您可以将广播的隐私状态设置为
public、private或unlisted。（私密广播仅对明确受邀观看的用户可见，而不公开列出的广播对拥有观看链接的任何人可见。）您可以选择延迟广播视频流，使其不与监控视频流同时运行。通过延迟广播视频流，您可以更精细地控制将提示点插入广播的时间。
不过，延迟广播视频流会使您的直播演示者难以与观看受众互动。此外，延迟广播会增加观看者从广播以外的来源发现活动关键细节的可能性。例如，如果您以 60 秒的延迟广播体育赛事，观看者可能会在广播中实际看到赛事关键时刻之前，从其他实时新闻来源了解这些时刻。
YouTube 建议您为广播启用监控视频流，以便测试内容。您应根据自己对控制提示点时间的意愿，而不是与受众互动或提供活动实时报道的意愿，来决定是否也延迟广播。
在广播视频流期间投放中贴片广告
在广播期间，您可以插入cuepoint ，以表明应尽快或在指定时间开始广播中的广告插播时间点。广告插播时间点可让 YouTube 在广播期间投放 中贴片广告。
广告插播具有以下特征：
-
它具有预定义的时长，您可以使用
cuepoint资源的durationSecs属性进行设置。广告插播时间点结束后，观看者会返回到直播。 -
发生广告插播时间点时，广告仅在视频播放器中播放，供在插入提示点时观看广播的观看者观看。当观看者刷新播放广播的页面时 或者当访客在插入提示点后开始观看广播时 广告不会播放。
以下步骤顺序反映了在广播期间插入广告插播时间点的最佳做法：
设置时间偏移值
插入提示点时，您可以指定应立即插入提示点，还是应在广播中的特定时间点插入提示点。 您的选项取决于视频的 广播视频流是否延迟。
-
如果广播视频流未延迟，则您可以立即插入提示点，也可以使用
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 秒缓冲区。例如：
- 广播有 5 分钟的测试阶段。
- 广播视频流在监控视频流之后延迟 60 秒。
- 广播者在广播转换为
live状态后 4 分钟插入提示点。（这是广播视频流可见后 3 分钟。）
在这种情况下，偏移时间的可能范围为 [(485,000), (535,000)]。
这些时间以毫秒为单位指定，并使用以下值计算得出：
elapsed_time=540000- 调用liveBroadcasts.cuepoint方法时，监控视频流已运行九 分钟（540 秒，540, 000 毫秒）。broadcast_delay=60000- 广播视频流延迟 60 秒，即 60, 000 毫秒。Δ=5000- 无法可靠插入提示点时的 5 秒缓冲区。
问题排查和错误处理
以下准则介绍了如何解决可能出现的特定问题。如需查看每个 API 方法可能会返回的错误列表 ，请参阅YouTube Live Streaming API - 错误。
-
当广播从一种 状态 转换为另一种状态时，在 YouTube 完成与转换相关的操作期间，广播可能会暂时被分配为另一种状态。例如，如果您发送
liveBroadcasts.transition请求将广播的状态从ready更改为testing，YouTube 会将广播的状态设置为testStarting，然后完成与状态更改相关的操作。完成所有这些操作后，YouTube 会将广播的状态更新为testing，从而表明转换已完成。如果广播卡在
testStarting或liveStarting状态，您需要调用liveBroadcasts.delete方法并删除广播。然后，创建一个新广播，将其绑定到直播，然后继续进行测试过程。如
liveBroadcasts.transition方法的文档中所述，在调用该方法之前，您应确认绑定到广播的视频流的status.streamStatus属性的值为active。