LiveBroadcasts: cuepoint

Вставляет рекламную паузу в прямую трансляцию. Временная точка может запустить рекламную паузу.

Примечание. Этот метод заменяет метод 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 определяет трансляцию, в которую вставляется маркер. В момент вставки метки трансляция должна быть активна.
Необязательные параметры
onBehalfOfContentOwner string
Этот параметр можно использовать только в авторизованном запросе.
Примечание. Этот параметр предназначен исключительно для партнеров YouTube, которые владеют и управляют множеством разных каналов YouTube. Он позволяет владельцам контента пройти аутентификацию один раз и выполнять действия от имени канала, указанного в значении параметра, без необходимости предоставлять разные учетные данные для каждого отдельного канала. Аккаунт, с помощью которого пользователь проходит аутентификацию, должен быть связан с указанным владельцем контента YouTube.
Параметр onBehalfOfContentOwner указывает, что учетные данные для авторизации запроса идентифицируют пользователя YouTube, действующего от имени владельца контента YouTube, указанного в значении параметра. Этот параметр предназначен для партнеров YouTube, которые владеют большим количеством каналов и управляют ими.
onBehalfOfContentOwnerChannel string
Этот параметр можно использовать только в авторизованном запросе.
Примечание. Этот параметр предназначен исключительно для партнеров YouTube, которые владеют большим количеством каналов и управляют ими. Он позволяет владельцам контента пройти аутентификацию один раз и выполнять действия от имени канала, указанного в значении параметра, без необходимости предоставлять учетные данные для каждого отдельного канала.
Параметр onBehalfOfContentOwnerChannel указывает идентификатор канала YouTube, связанного с трансляцией, в которую вставляется рекламная пауза. Этот параметр обязателен, если в запросе указано значение параметра 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 может возвращать в ответ на вызов этого метода. Подробную информацию можно найти в статье YouTube Live Streaming API – Errors.

Тип ошибки Сведения об ошибке Описание
insufficientPermissions (403) insufficientLivePermissions Запрос не авторизован для вставки рекламной паузы в прямую трансляцию.
insufficientPermissions (403) liveStreamingNotEnabled У пользователя, авторизовавшего запрос, нет разрешения на проведение прямых трансляций на YouTube. Дополнительную информацию можно найти на страницах Как начать работу с прямыми трансляциями и Требования к каналам.
rateLimitExceeded (403) userRequestsExceedRateLimit Пользователь отправил слишком много запросов за определенный период времени.
required (400) idRequired Обязательный параметр id должен определять трансляцию, в которую вы хотите вставить точку вставки.
required (400) cueTypeRequired Обязательное поле cueType должно быть указано в теле запроса к API.
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 и ответ.