此页面由 Cloud Translation API 翻译。

LiveBroadcasts: control

注意：liveBroadcasts.control 方法已弃用，将于 2020 年 10 月 1 日当天或之后停止工作。在该日期之后，对此方法的所有调用都将返回“禁止”(403) 错误，系统稍后会彻底移除此方法。

客户仍可以通过向发送到 YouTube 提取服务器的视频添加叠加层来实现自己的可选广告。请参阅弃用公告。

控制可在直播视频流中显示的可选广告的相关设置。

常见使用场景

请求

HTTP 请求

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/control

授权

此请求需要获得以下至少一个范围的授权（详细了解身份验证和授权）。

范围
`https://www.googleapis.com/auth/youtube`
`https://www.googleapis.com/auth/youtube.force-ssl`

参数

下表列出了此查询支持的参数。列出的所有参数都是查询参数。

参数
必需参数
`id`	`string` `id` 参数用于指定 YouTube 直播 ID，该 ID 用于唯一标识正在更新可选广告的直播。
`part`	`string` `part` 参数指定一个逗号分隔列表，其中包含 API 响应将包含的一个或多个 `liveBroadcast` 资源属性。您可以在参数值中包含的 `part` 名称包括 `id`、`snippet`、`contentDetails` 和 `status`。
可选参数
`displaySlate`	`boolean` `displaySlate` 参数用于指定要启用还是停用可选广告。
`offsetTimeMs`	`unsigned long` `offsetTimeMs` 参数会指定将发生指定的可选广告更改的时间偏移。该值从广播的监控流开始（即广播测试阶段的开始时间）开始计算，以毫秒为单位。虽然此参数是以毫秒为单位指定的，但其值实际上是一个近似值，YouTube 会尽可能快地完成请求的操作。如果你没有为此参数指定值，YouTube 会尽快执行该操作。如需了解详情，请参阅使用入门指南。重要提示：只有当直播延迟时，你才应该为此参数指定值。
`onBehalfOfContentOwner`	`string` 此参数只能在正确授权的请求中使用。注意：此参数仅适用于 YouTube 内容合作伙伴。 `onBehalfOfContentOwner` 参数用于指明该请求的授权凭据会标识代表参数值中指定的内容所有者执行操作的 YouTube 内容管理系统用户。此参数适用于拥有和管理众多不同 YouTube 频道的 YouTube 内容合作伙伴。它可让内容所有者在一次身份验证后获得访问其所有视频和频道数据的权限，而无需为每个频道提供身份验证凭据。用户进行身份验证时所用的 CMS 账号必须与指定的 YouTube 内容所有者相关联。
`onBehalfOfContentOwnerChannel`	`string` 此参数只能在正确授权的请求中使用。此参数只能在正确授权的请求中使用。注意：此参数仅适用于 YouTube 内容合作伙伴。 `onBehalfOfContentOwnerChannel` 参数用于指定要添加视频的频道的 YouTube 频道 ID。当请求为 `onBehalfOfContentOwner` 形参指定值时，此形参是必需项，并且只能与形参结合使用。此外，该请求还必须通过与 `onBehalfOfContentOwner` 参数指定的内容所有者相关联的 CMS 账号进行授权。最后，`onBehalfOfContentOwnerChannel` 参数值指定的频道必须与 `onBehalfOfContentOwner` 参数指定的内容所有者相关联。此参数适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。这样一来，内容所有者只需进行一次身份验证，即可代表参数值中指定的频道执行操作，而无需为每个单独的频道提供身份验证凭据。
`walltime`	`datetime` `walltime` 参数用于指定指定可选广告更改的挂钟时间。该值以 ISO 8601 (`YYYY-MM-DDThh:mm:ss.sZ`) 格式指定。

请求正文

调用此方法时，请勿提供请求正文。

响应

如果成功，此方法将在响应正文中返回 liveBroadcast 资源。

错误

下表列出了 API 在响应对此方法的调用时可能会返回的错误消息。如需了解详情，请参阅错误消息文档。

错误类型	错误详情	说明
`backendError`	`errorDisplaySlate`	执行请求的操作时出错。
`forbidden (403)`	`liveBroadcastControlNotAllowed`	只有当广播的状态为 `live` 时，才可以执行所请求的操作。
`insufficientPermissions`	`insufficientLivePermissions`	用户无权执行请求的操作，这可能是因为用户无权进行直播。
`insufficientPermissions`	`liveStreamingNotEnabled`	向请求授权的用户未启用在 YouTube 上直播视频的权限。用户可以访问 https://www.youtube.com/features 了解详情。
`invalidValue (400)`	`conflictingTimeFields`	只能指定 `offsetTimeMs` 和 `walltime` 中的一个。
`invalidValue (400)`	`invalidOffsetTimeMs`	`offsetTimeMs` 参数的值无效。参数值必须为正数，但只有在启用了广播的监控流的情况下才能指定该参数。
`invalidValue (400)`	`invalidWalltime`	`walltime` 参数的值无效。
`notFound (404)`	`liveBroadcastNotFound`	`id` 参数指定的广播不存在。
`required (400)`	`actionRequired`	API 请求需要指定至少一个操作。目前，唯一支持的操作就是启用或停用可选广告。
`required (400)`	`idRequired`	必需的 `id` 参数必须标识要更新的广播。

试试看！

使用 APIs Explorer 调用此 API 并查看 API 请求和响应。