广播的生命周期

简介

本文档将引导您了解使用 YouTube Live Streaming API 和 YouTube Content ID API 创建和管理的 YouTube 直播的整个生命周期。

资源和资源类型

如使用入门指南中所述，资源是指具有唯一标识符的单个数据实体。如需在 YouTube 上创建和管理直播活动，您需要使用多种不同类型的资源，这些资源在 YouTube Data API 或 YouTube Content ID API 中定义。YouTube Live Streaming API 标题下列出的资源在技术上是在其他 API 中定义的，但由于它们仅用于直播，因此单独列出。

YouTube Live Streaming API 资源

• liveBroadcast
• liveStream
• cuepoint

YouTube Data API 资源

• video

YouTube Content ID API 资源

• asset
• claim
• policy
• videoAdvertisingOption

创建和管理直播

以下步骤介绍了如何在 YouTube 上创建和管理直播活动。 这些步骤分为以下几个阶段：

1. 设置广播
2. 声明内容所有权
3. 测试
4. 广播
5. 结束直播
6. 创建参考

第 1 阶段：设置直播

第 1.1 步：创建广播

调用 liveBroadcasts.insert 方法，将您的广播添加到 YouTube 的直播活动日程中。您要插入的 liveBroadcast 资源必须为下列属性定义值。

• snippet.title
• snippet.scheduledStartTime
• status.privacyStatus

设置广播时，请考虑以下准则：

• 如果您希望为广播设置测试阶段，以便您可以在不让其他观看者看到广播的情况下观看视频广播，则必须将 contentDetails.monitorStream.enableMonitorStream 属性设置为 true，并将 contentDetails.enableAutoStart 属性设置为 false。以下是这两个属性的默认值。

• 如果您想从录制的广播中创建参考，必须将广播的 contentDetails.recordFromStart 属性设置为 true。如果您希望在广播结束后立即播放录制的视频，还必须将 contentDetails.enableDvr 属性设置为 true。（这两个属性的默认值均为 true。）

• 只要广播的状态仍为 created 或 ready，您就可以更新任何 contentDetails 属性。

• 只要直播的状态为 created、ready 或 testing，您就可以更新直播的预定开始时间和预定结��时间。

• 直播的标题、说明、隐私状态以及属于直播 video 资源的其他元数据字段可以随时更新。
  
  注意：如果您只希望特定 YouTube 用户能够观看您的视频，请根据需要将 status.privacyStatus 属性值设置为 unlisted 或 private。

处理 API 响应

调用 liveBroadcasts.insert 方法时，API 响应包含您创建的 liveBroadcast 资源。您的代码应从该资源中提取并存储 id。您需要使用该值来识别未来的 API 请求中的广播。（您还可以使用相同的 ID 来标识与 liveBroadcast 资源对应的 video 资源。）

第 1.2 步：创建直播

liveStream 资源可让您将视频传输到 YouTube，并描述您传输的内容。每次直播都必须恰好与一个直播流相关联。

调用 liveStreams.insert 方法可为活动创建视频流。创建直播时，您必须为下列属性设置值：

• snippet.title
• cdn.frameRate
• cdn.ingestionType
• cdn.resolution

除了直播的标题之外，这些值在直播创建后便无法更新。如果您需要更改这些设置，则实际上需要重复此步骤来创建其他直播。本文档稍后将在第 3.5 步中更详细地讨论此流程。

您还可以选择为以下属性设置值：

• snippet.description - 与直播标题类似，直播说明可以在创建直播后进行更新。YouTube 用户看不到标题和说明。

• contentDetails.isReusable - 指示流是否可重用，这意味着它可以绑定到多个广播。此属性的值实际上决定了渠道在 liveBroadcast 和 liveStream 资源之间是多对一关系还是一对一关系：

  • 如果您使用该属性的默认值 true，则可以将同一 liveStream 资源用于频道的所有广播。这意味着您无需为每次广播重复执行此步骤 (1.2)。不过，您可以直接在后续直播中重复使用该直播 ID。
  • 如果您将该属性值设置为 false，则需要为每次广播创建新的直播。

发出 API 请求后，API 响应会包含您创建的 liveStream 资源。您的代码应从该资源中提取并存储 id。您需要使用该值来标识未来的 API 请求中的直播。

第 1.3 步：将广播绑定到其直播

创建 liveBroadcast 和 liveStream 资源后，您现在需要使用 liveBroadcasts.bind 方法将两者关联起来。此操作会将您将要传输到 YouTube 的视频位与相应视频的活动广播相关联。

在调用 liveBroadcasts.bind 方法时，将 id 参数设置为在第 1.1 步中获得的广播 ID，并将 streamId 参数设置为在第 1.2 步中获得的直播 ID。

第 2 阶段：声明您的内容

如果您想在直播期间展示广告，需要在活动开始前声明直播视频。以下步骤介绍了此过程。请注意，此阶段讨论的所有 API 调用都在 YouTube Content ID API 中定义。

第 2.1 步：创建资产

asset 资源表示一项知识产权。在这种情况下，资源就是您的广播。调用 assets.insert 方法以创建您的资产。

API 响应将包含您创建的 asset 资源。您的代码应从该资源中提取并存储 id，因为您需要使用该值来识别未来的 API 请求中的资源。

第 2.2 步：说明您对相应资产的所有权

资产的所有权数据用于标识资产的所有者以及他们拥有资产的国家/地区。YouTube 会使用这些数据来确定所有者可以在哪些地区为已声明版权的视频设置政策。

例如，如果您有权在美国境内直播某个活动，而另一位广播公司有权在加拿大境内直播同一活动，那么您和对方可以分别为直播视频和与直播视频匹配的用户上传视频定义不同的政策。您的匹配政策将应用于美国境内匹配的用户上传视频，而另一位所有者的政策将应用于加拿大境内匹配的视频。

如需为资产定义所有权地区，请调用 ownership.update 方法。在该请求中，将 assetId 参数设置为您在第 2.1 步中存储的 id。

第 2.3 步：设置资产的匹配政策

资产的匹配政策用于说明当用户上传的视频与关联到该资产的参考文件相匹配时，YouTube 应采取的措施。在这种情况下，匹配政策将指示 YouTube 应如何处理与您的直播内容相符的上传视频。

注意：如果您计划从直播视频中创建参考，并使用该参考来识别与您的直播匹配的用户上传的视频，则应设置匹配政策。否则，您可以跳过此步骤。

如需设置匹配政策，您首先需要确定要应用的政策。您可以调用 policies.list 方法检索现有政策的列表，也可以调用 policies.insert 方法定义新政策。无论哪种情况，您都需要捕获要应用的政策的 id。

确定政策后，调用 assetMatchPolicy.update 方法。在该请求中，将 assetId 参数设置为您在第 2.1 步中存储的 id。

第 2.4 步：声明视频版权

在此步骤中，您将创建版权声明，将要直播的视频与您在第 2.1 步中创建的资产相关联。相应版权主张设置的政策仅适用于您的直播视频。（与您的广播视频匹配的用户上传视频受上一步中设置的匹配政策的约束。）

如需创建声明，请调用 claims.insert 方法。在您插入的 claim 资源中，您需要为以下属性设置值：

• assetId - 您在第 2.1 步中获得了此值。
• videoId - 这是您在第 1.1 步中获得的广播 ID。
• policy - 这是 policy 资源。您可以通过将相应资源的 id 属性设置为现有政策的 ID 来应用现有政策。上一步介绍了如何检索现有政策的 ID。
• contentType - 将此值设置为 audiovisual。

处理 API 响应

插入版权主张时，API 响应将包含您创建的 claim 资源。您的代码应从该资源中提取并存储 id。您稍后将使用该值从处理后的视频创建参考。

第 2.5 步：更新广播的广告设置

如果您想在观看者开始观看直播时投放前贴片广告，或者在直播期间的插播时间点投放广告，则需要为视频设置广告选项。

• 如果您为直播启用了前贴片广告，那么所有观看者在开始观看您的直播时都会看到广告，即使他们是在直播中途开始观看的。
• 如果您为直播启用中贴片广告，则可以在直播期间插入广告提示点。

如需启用广告，请调用 videoAdvertisingOptions.update 方法。在请求中，将 videoId 参数设置为您在第 1.1 步中获得的广播 id。使用 videoAdvertisingOption 资源的 adFormats[] 属性来标识要启用的广告格式（preroll、midroll 或 postroll）。

第 3 阶段：测试

在此阶段，您将嵌入一个播放器，用于显示广播的监视器流，以便测试观看体验。监控直播是一种私���直播，可让您预览广播视频在 YouTube 观看者眼中的效果。

请注意，只有在启用视频广播的监控流后，您才能测试视频广播。默认情况下，广播的监控流处于启用状态。您可以在创建或更新直播时，将 contentDetails.monitorStream.enableMonitorStream 属性设置为 false，以停用直播的监控数据流。

第 3.1 步：嵌入监控视频播放器

使用 liveBroadcasts.list 方法检索广播，并提取 contentDetails.streamDetails.monitorStreamEmbedHtml 属性的值。该值包含您需要嵌入的 HTML，用于嵌入显示监控视频流的 YouTube 播放器。

第 3.2 步：开始录制视频

开始在视频流中传输视频。

第 3.3 步：确认视频流处于有效状态

调用 liveStreams.list 方法可检索与您的广播相关联的 liveStream 资源。确认 status.streamStatus 属性的值为 active，这表示 YouTube 服务器正在从您的编码器正确接收数据。

第 3.4 步：将广播的状态转换为测试

调用 liveBroadcasts.transition 方法以更新广播的状态。将 id 形参值设置为在第 1.1 步中获得的广播 ID，并将 broadcastStatus 形参值设置为 testing。

调用 liveBroadcasts.transition 方法后，该过渡可能需要几秒钟甚至长达一分钟的时间才能完成。在此期间，您应轮询 API 以检查广播的状态。在过渡完成之前，直播的状态将为 testStarting。改换完成后，状态将变为 testing。

第 3.5 步：完成测试

如果测试顺利完成，您可以继续执行第 4 阶段。 不过，在某些情况下，您可能需要进行进一步测试。例如，如果测试显示视频流配置不正确，您需要先解决此问题，然后再继续进行直播。

如果视频流配置不正确，您需要取消绑定（并删除）现有视频流，然后创建新的视频流。例如，如果某个直播指定了错误的视频格式，则该直播可能未正确配置。

1. 如需取消绑定视频流，请调用步骤 1.3 中的 liveBroadcasts.bind 方法。在 API 请求中，将 id 参数设置为在步骤 1.1 中获得的 id。请勿在请求中添加 streamId 参数。

2. 如需删除视频流，请调用 liveStreams.delete 方法。在请求中，将 id 参数设置为在第 1.2 步中获得的 id。

3. 重复执行步骤 1.2，以创建新的、配置正确的 liveStream 资源。然后重复执行第 1.3 步，将新直播流绑定到您的广播，并重复执行第 3.1 步到第 3.3 步，测试新直播流。

第 3.6 步：启用 autoStart 和 autoStop ���性

成功完成测试阶段后，您可以选择在实际广播开始之前将广播的 contentDetails.enableAutoStart 和 contentDetails.enableAutoStop 属性设置为 true。在测试阶段之前，这些属性不能设置为 true，因为测试实际上会导致广播开始。

第 4 阶段：广播

在此阶段，您的直播视频可供观众观看。

第 4.1 步：开始录制视频

开始在视频流中传输视频。

第 4.2 步：确认视频流处于有效状态

调用 liveStreams.list 方法可检索与您的广播相关联的 liveStream 资源。确认 status.streamStatus 属性的值为 active，这表示 YouTube 服务器正在从您的编码器正确接收数据。

第 4.3 步：将广播状态转换为直播

重要提示：此步骤会使您的视频对观众可见。

调用 liveBroadcasts.transition 方法以更新广播的状态。将 id 形参值设置为在第 1.1 步中获得的广播 ID，并将 broadcastStatus 形参值设置为 live。

如果您将 liveBroadcast 资源的 contentDetails.enableAutoStart 属性设置为 true，则无需调用 liveBroadcasts.transition 方法。

发出此 API 调用后，或者如果您已将 contentDetails.enableAutoStart 属性设置为 true，则在开始流式传输后，您通常需要等待 5 到 10 秒才能完成该过渡。过渡过程可能需要长达 1 分钟的时间。在此期间，您应轮询 API 以检查广播的状态。在转换完成之前，广播的状态将为 liveStarting。转换完成后，状态将变为 live，观看者可以从监控器视频流中的该时间点开始观看广播。

请注意此命令的以下影响：

• 如果您已为直播启用监控串流（请参阅第 3.1 步），则可以在嵌入式播放器中看到监控串流。
• 如果您为广播的 contentDetails.streamDetails.broadcastStreamDelayMs 属性设置了值，则其他观看者看到的广播流将延迟相应的时间。

第 4.4 步：在直播中插入广告插播时间点

调用 liveBroadcasts.cuepoint 方法以插入提示点。cuepoint 可能会触发广告插播。在请求正文中提供的 cuepoint 资源中，将 durationSecs 属性设置为您希望展示的广告插播时长（以秒为单位）。（默认值为 30。）

此时，YouTube 会尝试在视频播放器中向所有在插入广告提示点时正在观看直播的观看者播放广告。广告是否播放取决于多种因素，例如广告供应情况和观看者的广告观看记录。看到广告插播的观看者会在广告插播结束后返回您的直播，而没有看到广告的观看者会在休息期间继续观看直播。

入门指南详细介绍了直播期间广告插播时的观看体验。

第 5 阶段：结束直播

第 5.1 步：停止流式传输

至此，您对 YouTube 直播系统的测试已结束。

第 5.2 步：将广播状态转换为“完成”

准备好停止广播时，请调用 API 的 liveBroadcasts.transition 方法来更新广播的状态。将 id 参数值设置为在第 1.1 步中获得的广播 ID，并将 broadcastStatus 参数值设置为 complete。

如果您已将广播的 contentDetails.recordFromStart 和 contentDetails.enableDvr 属性设置为 true，那么当直播活动结束时，您的观众可以立即观看直播活动回放。

阶段 6：创建参考

实时录制完成后，您可以根据录制的视频创建参考文件。此操作会指示 YouTube 查找与广播内容匹配的用户上传视频，并根据您在第 2.3 步中设置的匹配政策处理这些视频。

重要提示：如需创建引用，您必须将广播的 contentDetails.recordFromStart 属性设置为 true。

第 6.1 步：轮询 Data API 以获取视频的状态

YouTube 必须先完成对直播或上传视频的处理，然后您才能根据该视频创建参考内容。如需确定视频是否已完成处理，请轮询 YouTube Data API 的 videos.list 方法，并将 part 参数设置为 status，将 id 参数设置为您在第 1.1 步中存储的广播 ID。

针对轮询请求的 API 响应将包含 video 资源。当相应资源的 status.uploadStatus 属性的值为 processed 时，继续执行步骤 6.2。

第 6.2 步：根据处理后的视频创建参考文件

如需创建参考，请调用 Content ID API 的 references.insert 方法，并将 claimId 参数设置为您在第 2.4 步中存储的版权主张 ID。

直播 Content ID 提交

部分 YouTube 合作伙伴能够在广播过渡到 testing 状态之前创建参考，但并非所有合作伙伴都能使用此功能。在该流程中，YouTube 会在直播进行期间生成并不断更新直播活动的广播流参考。此外，YouTube 还会查找与直播内容匹配的用户上传视频。请注意，在直播开始前创建引用会自动为直播启用录制功能，并且在创建引用后无法关闭录制功能。

如需为直播启用 Content ID 实时投放，请在第 2.4 步中声明视频版权后，尝试执行第 6.2 步中所述的操作。 如果您的合作伙伴账号在直播开始之前未获准为直播创建参考，则 API 会返回 fingerprintingNotAllowed 错误。在这种情况下，您需要等到直播结束后（如上文步骤 6.1 和 6.2 中所述），才能创建参考。