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, которые владеют и управляют множеством различных каналов YouTube.
onBehalfOfContentOwnerChannel string
Этот параметр можно использовать только в должным образом авторизованном запросе .
Примечание. Этот параметр предназначен исключительно для контент-партнеров YouTube, которые владеют и управляют множеством различных каналов 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 . Дополнительные сведения см. в разделе Начало работы .

Примечание. Если в вашей трансляции была фаза тестирования, смещение измеряется с момента начала фазы тестирования.

API возвращает ошибку, если запрос пытается вставить точку разметки, указывающую значение для этого свойства и свойства walltimeMs .
walltimeMs integer
Значение свойства определяет время на настенных часах, в которое должна быть вставлена ​​точка разметки. Значение представляет собой целое число, представляющее временную метку эпохи (в миллисекундах).

API возвращает ошибку, если запрос пытается вставить точку разметки, указывающую значение для этого свойства и свойства insertionOffsetTimeMs .
durationSecs unsigned integer
Продолжительность ключевой точки в секундах. Значение должно быть положительным целым числом. Значение по умолчанию — 30 .
cueType string
Тип ключевой точки. Значение свойства должно быть установлено в cueTypeAd .

Ответ

В случае успеха этот метод возвращает вставленный ресурс cuepoint в тексте ответа.

Ошибки

В следующей таблице указаны сообщения об ошибках, которые API может вернуть в ответ на вызов этого метода. Дополнительные сведения см. в разделе API потоковой передачи YouTube Live — ошибки .

Тип ошибки Детализация ошибки Описание
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.