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/2474026https://www.youtube.com/features 了解详情。
rateLimitExceeded (403) userRequestsExceedRateLimit 用户在指定时间范围内发送的请求过多。
required (400) idRequired 必需的 id 参数必须标识要在其中插入广告插入点的广播。
required (400) cueTypeRequired API 请求正文中必须指定必需的 cueType 字段。
notFound (404) liveBroadcastNotFound 通过 id 参数指定的广播不存在。
invalidValue (400) conflictingTimeFields 只能指定 insertionOffsetTimeMswalltimeMs 中的一个。设置两个值都会导致错误。如果您未设置这两个值,YouTube 会使用默认的 insertionOffsetTimeMs 时间 (0),这意味着广告插入点将尽快插入。
invalidValue (400) invalidInsertionOffsetTimeMs cuepoint 资源为 insertionOffsetTimeMs 属性指定了无效值。值必须为 0 或正整数。
invalidValue (400) invalidWalltimeMs cuepoint 资源为 walltimeMs 属性指定了无效值。该值必须是表示周期时间戳(以毫秒为单位)的整数。
backendError (5xx) serviceUnavailable 无法使用该服务。请过几分钟后重试您的请求。

试试看!

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