此页面由 Cloud Translation API 翻译。

LiveBroadcasts: cuepoint

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

注意：此方法取代了 liveCuepoints.insert 方法，后者要求请求必须由与 YouTube 内容所有者关联的账号授权。此方法没有相同的授权要求。

请求

HTTP 请求

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

授权

此请求需要获得以下至少一个范围的授权。如需详细了解身份验证和授权，请参阅实现 OAuth 2.0 身份验证。

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

参数

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

参数
必需参数
`id`	`string` `id` 参数用于标识要插入 cue 点的广播。插入 cue 点时，直播必须处于流式传输状态。
可选参数
`onBehalfOfContentOwner`	`string` 此参数只能在经过适当授权的请求中使用。注意：此参数仅适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。借助此功能，内容所有者只需进行一次身份验证，即可代表参数值中指定的频道执行操作，而无需为每个单独的频道提供不同的身份验证凭据。用户进行身份验证时使用的账号必须与指定的 YouTube 内容所有者相关联。 `onBehalfOfContentOwner` 参数表示请求的授权凭据可识别代表参数值中指定的 YouTube 内容所有者行事的 YouTube 用户。此参数适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。
`onBehalfOfContentOwnerChannel`	`string` 此参数只能在经过适当授权的请求中使用。注意：此参数仅适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。借助此功能，内容所有者只需进行一次身份验证，即可代表参数值中指定的频道执行操作，而无需为每个单独的频道提供身份验证凭据。 `onBehalfOfContentOwnerChannel` 参数用于指定与要插入 cue 点的直播相关联的频道的 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 分配的值，用于唯一标识 cue 点。请注意，此值不同于用于标识广播的必需 `id` 参数。发送用于插入 cue 点的请求时，可以省略此值。该值将填充在 API 响应中。
`insertionOffsetTimeMs`	`long` 此属性值用于标识应插入广告插入点的时间偏移（以毫秒为单位）。此值从监视串流的开头开始测量，其默认值为 `0`，表示应尽快插入 cue 点。如果您的直播没有监控串流，则不应为此参数指定值。虽然以毫秒为单位，但该值实际上只是一个近似值，YouTube 会尽可能在该时间插入 cue 点。只有在直播流延迟时，此字段才支持非零值。如果您的广播流没有延迟，则 `0` 是唯一有效的值。如需了解详情，请参阅使用入门。注意：如果您的直播有测试阶段，则偏移量是从测试阶段开始的时间算起。如果请求尝试插入用于为此属性和 `walltimeMs` 属性指定值的 cuepoint，则 API 会返回错误。
`walltimeMs`	`integer` 此属性值指定应插入 cue 点的标准时间。此值是一个整数，表示公元纪年时间戳（以毫秒为单位）。如果请求尝试插入一个 cue 点，为此属性和 `insertionOffsetTimeMs` 属性指定值，则 API 会返回错误。
`durationSecs`	`unsigned integer` 标记点的时长（以秒为单位）。该值必须为正整数。默认值为 `30`。
`cueType`	`string` 提示点的类型。属性值必须设置为 `cueTypeAd`。

响应

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

错误

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

错误类型	错误详情	说明
`insufficientPermissions (403)`	`insufficientLivePermissions`	请求无权在直播中插入 cuepoint。
`insufficientPermissions (403)`	`liveStreamingNotEnabled`	授权该请求的用户未获准在 YouTube 上直播视频。用户可以参阅开始使用直播和功能使用资格条件，了解详情。
`rateLimitExceeded (403)`	`userRequestsExceedRateLimit`	用户在指定时间范围内发送的请求过多。
`required (400)`	`idRequired`	必需的 `id` 参数必须标识您要插入 cue 点的直播。
`required (400)`	`cueTypeRequired`	必须在 API 请求正文中指定必需的 `cueType` 字段。
`notFound (404)`	`liveBroadcastNotFound`	`id` 参数指定的广播不存在。
`invalidValue (400)`	`conflictingTimeFields`	只能指定 `insertionOffsetTimeMs` 和 `walltimeMs` 中的一个。同时设置这两个值会导致错误。如果您未设置这两个值，YouTube 将使用默认的 `insertionOffsetTimeMs` 时间 (`0`)，这意味着系统会尽快插入 cue 点。
`invalidValue (400)`	`invalidInsertionOffsetTimeMs`	`cuepoint` 资源为 `insertionOffsetTimeMs` 属性指定的值无效。该值必须为 `0` 或正整数。
`invalidValue (400)`	`invalidWalltimeMs`	`cuepoint` 资源为 `walltimeMs` 属性指定的值无效。该值必须为一个整数，表示纪元时间戳（以毫秒为单位）。
`backendError (5xx)`	`serviceUnavailable`	该服务不可用。请过几分钟后重试。

试试看！

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