LiveBroadcasts

该 API 现在支持将直播标记为“面向儿童的内容”，而且 liveBroadcast 资源现在包含一个属性，用于标识直播的“面向儿童的内容”状态。YouTube API 服务的《服务条款》和《开发者政策》也于 2020 年 1 月 10 日进行了更新。如需了解详情，请参阅 YouTube Live Streaming API 服务和 YouTube API 服务的服务条款的修订历史记录。

liveBroadcast 资源代表将通过直播视频在 YouTube 上直播的活动。

方法

对于 liveBroadcasts 资源，该 API 支持以下方法：

list

返回与 API 请求参数匹配的 YouTube 广播列表。立即试用。

插入

创建广播。 立即试用。

update

更新广播。例如，您可以修改 liveBroadcast 资源的 contentDetails 对象中定义的广播设置。立即试用。

delete

删除广播。 立即试用。

bind

将 YouTube 直播与直播绑定，或移除直播与直播之间的现有绑定。一个广播只能绑定到一个视频流，但一个视频流可以绑定到多个广播。立即试用。

transition

更改 YouTube 直播的状态并启动与新状态相关的任何流程。例如，当您将广播的状态转换为 testing 后，YouTube 就会开始向该广播的监控流传输视频。在调用此方法之前，您应该确认绑定到广播的数据流的 status.streamStatus 属性的值为 active。立即试用。

广告插入点

在直播中插入广告插入点。广告插入点可能会触发广告插播。

资源表示法

以下 JSON 结构显示了 liveBroadcasts 资源的格式：

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
    "cuepointSchedule": {
      "enabled": boolean,
      "pauseAdsUntil": datetime,
      "scheduleStrategy": string,
      "repeatIntervalSecs": unsigned integer,
    }
  }
}

属性

下表定义了此资源中显示的属性：

属性
kind	string 标识 API 资源类型。其值为 youtube#liveBroadcast。
etag	etag 此资源的 Etag。
id	string YouTube 分配的 ID，用于唯一标识广播。
snippet	object snippet 对象包含活动的基本详情，包括活动标题、说明、开始时间和结束时间。
snippet.publishedAt	datetime 将直播添加到 YouTube 直播时间表的日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.channelId	string YouTube 用来唯一标识发布直播的频道的 ID。
snippet.title	string 广播的标题。请注意，广播仅表示一个 YouTube 视频。您可以通过修改广播资源或设置相应视频资源的 title 字段来设置此字段。
snippet.description	string 广播的说明。与 title 一样，您可以通过修改广播资源或设置相应视频资源的 description 字段来设置此字段。
snippet.thumbnails	object 与直播相关联的缩略图的地图。对于此对象中的每个嵌套对象，键是缩略图的名称，值是包含有关缩略图的其他信息的对象。
snippet.thumbnails.(key)	object 有效的键值对包括： default - 默认缩略图。视频（或引用视频的资源，例如播放列表项或搜索结果）的默认缩略图为 120 像素宽 90 像素高。频道的默认缩略图为 88 像素宽 88 像素高。 medium – 更高分辨率版本的缩略图。对于视频（或引用视频的资源），此图片的宽度为 320 像素，高度为 180 像素。对于频道，此图片的宽度为 240 px，高度为 240 px。 high - 缩略图的高分辨率版本。对于视频（或引用视频的资源），此图片的宽度为 480 像素，高度为 360 像素。对于频道，此图片的宽度为 800 px，高度为 800 px。
snippet.thumbnails.(key).url	string 图片的网址。
snippet.thumbnails.(key).width	unsigned integer 图片的宽度。
snippet.thumbnails.(key).height	unsigned integer 图片的高度。
snippet.scheduledStartTime	datetime 预定开始直播的日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。创作者工作室支持在不安排开始时间的情况下创建直播。在这种情况下，每当频道所有者开始直播时，直播就会开始。对于这些广播，datetime 值对应 UNIX 时间 0，并且无法通过 API 或创作者工作室更改此值。
snippet.scheduledEndTime	datetime 预定结束直播的日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。如果 liveBroadcast 资源没有为此属性指定值，则系统将安排无限期地继续广播。同样，如果您没有为该属性指定值，则 YouTube 会将此广播视为无限期进行。
snippet.actualStartTime	datetime 直播的实际开始日期和时间。只有当广播的状态为 live 时，此信息才可用。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.actualEndTime	datetime 直播实际结束的日期和时间。只有当广播的状态为 complete 时，此信息才可用。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.isDefaultBroadcast	boolean 此属性将于 2020 年 9 月 1 日当天或之后弃用。届时，如果频道启用了直播功能，YouTube 将停止创建默认直播和默认直播。如需了解详情，请参阅弃用公告。 此属性指示此广播是否是默认广播。 默认直播的运作方式 YouTube 频道启用直播功能后，YouTube 会为该频道创建默认直播和默认直播。直播定义了频道所有者向 YouTube 发送直播视频的方式，直播决定了观看者看到默认直播的方式。频道所有者可以使用 liveStreams.list 和 liveBroadcasts.list 方法来标识这些资源。 当频道开始将视频流式传输到其默认视频流时，该视频会显示在频道的默认广播中。直播结束后，YouTube 会将完成的直播转换为 YouTube 视频，并为该视频分配一个 YouTube 视频 ID。 转换完成后，该视频会添加到频道的已上传视频列表中。视频在直播结束后并不会立即播放，并且延迟时长与直播的实际时长有关。
snippet.liveChatId	string 直播的 YouTube 实时聊天 ID。通过此 ID，您可以使用 liveChatMessage 资源的方法检索、插入或删除聊天消息。您还可以添加或移除聊天管理员、禁止用户参与实时聊天，或者移除现有的黑名单。
status	object status 对象包含有关事件状态的信息。
status.lifeCycleStatus	string 广播的状态。您可以使用 API 的 liveBroadcasts.transition 方法更新状态。 此属性的有效值包括： complete – 直播已结束。 created – 广播的设置不完整，因此尚未准备好转换为 live 或 testing 状态，但是广播已创建且在其他方面有效。 live – 广播正在进行。 liveStarting – 广播正在转换为 live 状态。 ready – 广播设置已完成，广播可以转换为 live 或 testing 状态。 revoked - 此广播已被管理员移除。 testStarting – 广播正在转换为 testing 状态。 testing - 只有合作伙伴可以看到广播。
status.privacyStatus	string 广播的隐私状态。请注意，直播仅代表一个 YouTube 视频，因此视频的隐私设置与支持的隐私设置相同。此外，您还可以通过修改广播资源或设置相应视频资源的 privacyStatus 字段来设置此字段。 此属性的有效值包括： private public unlisted
status.recordingStatus	string 广播的录制状态。 此属性的有效值包括： notRecording recorded recording
status.madeForKids	boolean 此值指示广播是否被指定为面向儿童。此属性值为只读。
status.selfDeclaredMadeForKids	boolean 在 liveBroadcasts.insert 请求中，此属性允许频道所有者将广播指定为面向儿童。在 liveBroadcasts.list 请求中，只有在频道所有者为 API 请求授权的情况下，系统才会返回属性值。
contentDetails	object contentDetails 对象包含与活动的视频内容有关的信息，例如内容是否可以显示在嵌入式视频播放器中，或者内容是否会被归档以便在活动结束后可供观看。
contentDetails.boundStreamId	string 此值唯一标识绑定到广播的 live stream。
contentDetails.boundStreamLastUpdateTimeMs	datetime boundStreamId 引用的直播活动的上次更新时间。
contentDetails.monitorStream	object monitorStream 对象包含监控视频流的相关信息，直播方可以使用这些信息在直播视频流公开显示之前查看事件内容。
contentDetails.monitorStream.enableMonitorStream	boolean 此值用于确定是否针对广播启用监控流。如果启用了监控流，那么 YouTube 将通过一个仅供广播公司观看的特殊视频流来播送活动内容。直播方可以根据视频流查看活动内容，并确定插入广告插入点的最佳时机。 如果您打算为直播设置 testing 阶段或者希望活动有直播延迟，则需要将此值设为 true。此外，如果此属性的值为 true，则必须先将广播转换为 testing 状态，然后才能将其转换为 live 状态。（如果属性的值为 false，则广播不能有 testing 阶段，因此您可以直接将广播转换为 live 状态。） 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选属性，默认值为 true。 重要提示：一旦广播处于 testing 或 live 状态，此属性便无法更新。
contentDetails.monitorStream.broadcastStreamDelayMs	unsigned integer 如果您已将 enableMonitorStream 属性设置为 true，则此属性会确定直播延迟的时长。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选属性，默认值为 0。此值表示广播没有广播延迟。注意：一旦广播处于 testing 或 live 状态，此属性便无法更新。
contentDetails.monitorStream.embedHtml	string 用于嵌入用于播放监控视频流的播放器的 HTML 代码。
contentDetails.enableEmbed	boolean 此设置用于指明能否在嵌入式播放器中播放广播视频。如果您选择归档视频（使用 enableArchive 属性），则此设置也适用于归档视频。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选属性，默认值为 true。 注意：一旦广播处于 testing 或 live 状态，此属性便无法更新。
contentDetails.enableDvr	boolean 此设置决定观看者能否在观看视频时访问 DVR 控件。借助 DVR 控件，观看者可以通过暂停、快退或快进内容来控制视频播放体验。此属性的默认值为 true。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选属性，默认值为 true。 重要提示：如果您希望在直播结束后立即播放，则必须将值设置为 true 并将 enableArchive 属性的值设置为 true。此外，一旦广播处于 testing 或 live 状态，此属性便无法更新。
contentDetails.recordFromStart	boolean 此设置用于指明在活动状态变为直播后，YouTube 是否自动开始录制直播。 此属性的默认值为 true，只有在允许广播频道停用直播录制功能时，才能将其设置为 false。 如果您的频道没有停用录制功能的权限，并且您尝试插入将 recordFromStart 属性设置为 false 的直播，API 会返回 Forbidden 错误。此外，如果您的频道没有该权限，并且您尝试更新广播以将 recordFromStart 属性设置为 false，则 API 会返回 modificationNotAllowed 错误。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选属性，默认值为 true。 重要提示：如果您希望在广播结束后立即播放，还必须将 enableDvr 属性的值设置为 true。如果您将此属性的值设为 true，但未同时将 enableDvr 属性设置为 true，则归档视频可能会延迟一天左右才能播放。 注意：一旦广播处于 testing 或 live 状态，此属性便无法更新。
contentDetails.enableClosedCaptions	boolean 此属性自 2015 年 12 月 17 日起已弃用。请改用 contentDetails.closedCaptionsType 属性。 此设置用于指明是否为此广播启用 HTTP POST 字幕。对于已使用此属性的 API 客户端： 将属性值设置为 true 相当于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsHttpPost。 将属性值设置为 false 相当于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsDisabled。
contentDetails.closedCaptionsType	string 注意：此属性会替换 contentDetails.enableClosedCaptions 属性。 此属性指示您的直播是否启用了字幕，如果是，则指明您提供的字幕类型： closedCaptionsDisabled：为直播停用了字幕。 closedCaptionsHttpPost：您将通过 HTTP POST 将字幕发送到与您的直播相关联的提取网址。 closedCaptionsEmbedded：字幕将采用 EIA-608 和/或 CEA-708 格式在视频流中进行编码。
contentDetails.projection	string 此广播的投影格式。此属性的默认值为 rectangular。 此属性的有效值包括： 360 rectangular
contentDetails.enableLowLatency	boolean 指示是否应对此广播进行编码以实现低延迟流式传输。低延迟的视频流可以缩短观看直播的用户看到视频所需的时间，但也可能会影响视频流的观看者的分辨率。
contentDetails.latencyPreference	string 指示要为此广播使用哪种延迟时间设置。此属性可用于代替 enableLowLatency，后者不支持 ultraLow。 低延迟的数据流可以缩短向观看直播的用户显示视频所需的时间，但也可能会影响播放的流畅性。 超低延迟时间数据流可进一步缩短视频向观看者显示的时间，使与观看者的互动更加轻松，但超低延迟时间与字幕相比， 0 的有效分辨率不支持字幕。 0 normal low ultraLow
contentDetails.enableAutoStart	boolean 指明当您开始在绑定的 live stream 上流式传输视频时，此广播是否应自动开始。
contentDetails.enableAutoStop	boolean 指明在频道所有者停止流式传输所绑定视频流中的视频后一分钟左右，此广播是否应自动停止。
statistics	object statistics 对象包含与直播相关的统计信息。这些统计信息的值在直播期间可能会发生变化，并且只能在直播直播时检索。
statistics.totalChatCount	unsigned long 与直播相关的实时聊天消息总数。如果直播对用户可见、启用了实时聊天功能并且至少有一条消息，则此属性及其值会显示。请注意，在广播结束后，此属性将不再指定值。因此，对于已完成的直播，此媒体资源无法识别归档视频的聊天消息数量。
monetizationDetails	object monetizationDetails 对象包含与视频流的创收详情有关的信息，例如自动广告生成工具是否处于启用状态，或者中贴片广告插入是否延迟。 重要提示：若要为视频启用自动广告，频道必须符合通过视频创收的条件。在直播期间创建直播或修改直播时，可以在 YouTube 工作室中设置直播的创收设置，例如启用创收功能或广告自动化工具（即“让 YouTube 为您插入中贴片广告”或“按设定的频率安排中贴片广告”）。
monetizationDetails.cuepointSchedule	object cuepointSchedule 对象指定广播的广告自动化设置。
monetizationDetails.cuepointSchedule.enabled	boolean 此值用于确定是否在广播中自动插入广告。如果值为 true，YouTube 会自动在直播中插入中贴片广告。广告的投放时间安排将由 monetizationDetails.cuepointSchedule 对象中其他字段的值决定。
monetizationDetails.cuepointSchedule.pauseAdsUntil	datetime 此值指定 YouTube 在指定日期和时间之前不会在广播中插入中贴片广告。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。该值必须设置为未来的日期时间才能暂停广告；字段值还可以设置为近期的日期时间，以便在时间经过时取消暂停广告。
monetizationDetails.cuepointSchedule.scheduleStrategy	string 此值用于指定 YouTube 在安排广告插入点时应遵循的策略。有效值包括： CONCURRENT：为所有观看者安排在同一时间显示广告插入点 NON_CONCURRENT：为不同的观看者安排不同的广告插入点。这种方法可以提高广告展示频率，让观看者在符合条件时收到广告插入点。
monetizationDetails.cuepointSchedule.repeatIntervalSecs	unsigned integer 此值指定广播期间自动插入广告的时间间隔（以秒为单位）。例如，如果值为 300，YouTube 可以每隔 5 分钟插入中贴片广告插入点。 请注意，该值指定的是连续广告插入点的开始时间之间的时间间隔。也就是说，不会测量从一个广告插入点结束到下一个广告插入点的开始的时间间隔。