此页面由 Cloud Translation API 翻译。

LiveBroadcasts: cuepoint

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

注意：此方法取代了 liveCuepoints.insert 方法，该方法需要请求获得与 YouTube 内容所有者帐号相关联的授权。此方法具有相同的授权要求。

请求

HTTP 请求

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

授权

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

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

参数

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

参数
必需参数
`id`	`string` `id` 参数用于标识插入广告插入点的广播。插入广告插入点时，广播必须处于活跃状态。
可选参数
`onBehalfOfContentOwner`	`string` 此参数只能在适当的授权请求中使用。注意：此参数仅适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。它让内容所有者可以执行一次身份验证，代表参数值中指定的频道执行操作，而无需为每个单独的频道提供不同的身份验证凭据。用户用于进行身份验证的帐号必须与指定的 YouTube 内容所有者相关联。 `onBehalfOfContentOwner` 参数表示请求的授权凭据用于标识代表参数值中指定的 YouTube 内容所有者的 YouTube 用户。此参数适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。
`onBehalfOfContentOwnerChannel`	`string` 此参数只能在适当的授权请求中使用。注意：此参数仅适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。它让内容所有者可以执行一次身份验证，代表参数值中指定的频道执行操作，而无需为每个单独的频道提供身份验证凭据。 `onBehalfOfContentOwnerChannel` 参数指定与插入广告插入点的广播相关联的频道的 YouTube 频道 ID。当请求为 `onBehalfOfContentOwner` 参数指定值时，必须提供此参数，并且该参数只能与该参数结合使用。以及下列要求：必须使用与 `onBehalfOfContentOwner` 参数指定的内容所有者关联的用户帐号为该请求授权。 `onBehalfOfContentOwnerChannel` 参数值指定的频道必须关联到 `onBehalfOfContentOwner` 参数指定的内容所有者。

请求正文

在请求正文中提供 cuepoint 资源。以下 JSON 结构显示了 cuepoint 资源的格式：

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }

在请求正文中，cueType 字段是必填字段，并且必须设置为 cueTypeAd。您还可以为以下属性设置值：

durationSecs
insertionOffsetTimeMs（如果设置了 walltimeMs，则不得设置）
walltimeMs（如果设置了 insertionOffsetTimeMs，则不得设置）

属性

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

属性
`id`	`string` YouTube 为唯一标识广告插入点而分配的值。请注意，此值与必需的 `id` 参数不同，此参数用于标识广播。发送插入广告插入点的请求时，可以省略此值。系统将在 API 响应中填充该值。
`insertionOffsetTimeMs`	`long` 属性值用于标识应插入广告插入点的时间偏移量（以毫秒为单位）。该值从监视器数据流的开头处测量，默认值为 `0`，这表示应插入广告插入点。如果您的广播没有监控流，则不应指定此参数的值。虽然以毫秒为单位进行衡量，但该值实际上是近似值，YouTube 会在尽可能接近该时间点时插入广告插入点。只有广播流延迟时，此字段才支持非零值。如果您的广播流没有延迟，则 `0` 是唯一的有效值。如需了解详情，请参阅入门指南。注意：如果您的广播有测试阶段，则偏移量是从测试阶段开始的时间算起的。如果请求尝试插入用于指定此属性和 `walltimeMs` 属性的值的广告插入点，则 API 会返回错误。
`walltimeMs`	`integer` 该属性值用于指定应插入广告插入点的挂钟时间。该值是一个表示周期时间戳（以毫秒为单位）的整数。如果请求尝试插入用于指定此属性的值和 `insertionOffsetTimeMs` 属性的值的广告，则 API 会返回错误。
`durationSecs`	`unsigned integer` 广告插入点的时长（以秒为单位）。该值必须是正整数。默认值为 `30`。
`cueType`	`string` 广告插入点的类型。属性值必须设为 `cueTypeAd`。

响应

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

错误

下表列出了 API 可能会在调用该方法时返回的错误消息。错误消息文档用于标识 Live Streaming API 可以返回的所有错误。

错误类型	错误详情	说明
`insufficientPermissions (403)`	`insufficientLivePermissions`	您无权在直播中插入广告插入点。
`insufficientPermissions (403)`	`liveStreamingNotEnabled`	授权请求的用户未启用在 YouTube 上直播视频的功能。用户可以访问 https://support.google.com/youtube/answer/2474026 和 https://www.youtube.com/features 了解详情。
`rateLimitExceeded (403)`	`userRequestsExceedRateLimit`	用户在指定时间范围内发送的请求过多。
`required (400)`	`idRequired`	必需的 `id` 参数必须标识要在其中插入广告插入点的广播。
`required (400)`	`cueTypeRequired`	API 请求正文中必须指定必需的 `cueType` 字段。
`notFound (404)`	`liveBroadcastNotFound`	通过 `id` 参数指定的广播不存在。
`invalidValue (400)`	`conflictingTimeFields`	只能指定 `insertionOffsetTimeMs` 和 `walltimeMs` 中的一个。设置两个值都会导致错误。如果您未设置这两个值，YouTube 会使用默认的 `insertionOffsetTimeMs` 时间 (`0`)，这意味着广告插入点将尽快插入。
`invalidValue (400)`	`invalidInsertionOffsetTimeMs`	`cuepoint` 资源为 `insertionOffsetTimeMs` 属性指定了无效值。值必须为 `0` 或正整数。
`invalidValue (400)`	`invalidWalltimeMs`	`cuepoint` 资源为 `walltimeMs` 属性指定了无效值。该值必须是表示周期时间戳（以毫秒为单位）的整数。
`backendError (5xx)`	`serviceUnavailable`	无法使用该服务。请过几分钟后重试您的请求。

试试看！

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