Эта страница переведена с помощью Cloud Translation API.

Обзор API потокового вещания YouTube

YouTube Live Streaming API позволяет создавать, обновлять и управлять прямыми трансляциями на YouTube. Используя API, вы можете планировать события (трансляции) и связывать их с видеопотоками, которые представляют реальный контент трансляции.

Live Streaming API на самом деле состоит из компонентов API данных YouTube и API идентификации контента YouTube. Data API позволяет пользователям YouTube управлять своими учетными записями YouTube, а YouTube Content ID API позволяет взаимодействовать с системой управления правами YouTube. Однако все ресурсы, входящие в состав Live Streaming API, используются только для создания прямых трансляций и управления ими.

Этот документ предназначен для разработчиков, которые хотят писать приложения для облегчения прямых трансляций на YouTube. В нем объясняются основные понятия YouTube и самого API. Он также предоставляет обзор различных функций, поддерживаемых API.

Основные концепции

трансляции: Трансляция представляет собой событие, которое можно посмотреть на YouTube, как оно происходит. Трансляции также можно записывать и сохранять в виде видео на YouTube, чтобы пользователи могли просмотреть их после того, как они произошли.
потоки: Поток идентифицирует аудио-видео контент, который передается на YouTube. Каждая трансляция связана с одним видеопотоком.
ключевые точки: Ключевая точка представляет собой рекламную паузу, которую можно вставить в прямую трансляцию.

Варианты использования API

В приведенном ниже списке предлагается несколько способов использования API в вашем приложении:

Планируйте трансляции и определяйте настройки трансляции. Ваше приложение может позволить пользователям предварительно определить настройки трансляции, а затем выбрать настройки, которые будут применяться к конкретной трансляции.
Свяжите видеопотоки и трансляции.
Разрешить вещателям одновременно определять информацию о трансляции и ее видео (с помощью API данных YouTube ).
Упростите переходы между состояниями трансляции ( testing , live и т. д.) и разрешите пользователям вставлять ключевые точки.

Прежде чем ты начнешь

Вам потребуется учетная запись Google , чтобы получить доступ к Google API Console , запросить ключ API и зарегистрировать свое приложение.
Зарегистрируйте свое приложение в Google, чтобы оно могло отправлять запросы API.
После регистрации приложения выберите YouTube Data API в качестве одной из служб, которые использует ваше приложение:
1. Перейдите в API Console и выберите проект, который вы только что зарегистрировали.
2. Посетите страницу «Включенные API» . Убедитесь, что в списке API-интерфейсов включен статус YouTube Data API v3 и, если вы являетесь контент-партнером YouTube, API-интерфейс YouTube Content ID.
Ознакомьтесь с основными понятиями формата данных JSON (нотация объектов JavaScript). JSON — это распространенный независимый от языка формат данных, обеспечивающий простое текстовое представление произвольных структур данных. Для получения дополнительной информации см. json.org .

Авторизация запросов API

Как отмечалось выше, Live Streaming API использует функции, которые технически являются частью либо API данных YouTube, либо API идентификации контента YouTube. Вы можете использовать Content ID API, чтобы предоставить YouTube метаданные, информацию о праве собственности и информацию о правилах для ваших объектов. (Прямая видеотрансляция является примером актива.) API также позволяет заявлять права на видео и устанавливать политики рекламы для ваших видео.

В этом разделе объясняются требования к авторизации для запросов к Content ID API , которые отличаются от требований для авторизации других запросов Live Streaming API .

Вызов Data API: Запрос API должен быть авторизован учетной записью Google, которой принадлежит транслируемый канал YouTube.
Вызов Content ID API: Запрос API должен быть авторизован учетной записью Google, связанной с владельцем контента, которому принадлежит транслируемый канал YouTube.

Ресурсы и типы ресурсов

Ресурс — это отдельный объект данных с уникальным идентификатором. В таблице ниже описаны различные типы ресурсов, с которыми вы будете взаимодействовать с помощью Live Streaming API . Технически все эти ресурсы на самом деле определены как часть либо YouTube Data API , либо YouTube Content ID API . Однако ресурсы liveBroadcast , liveStream и cuepoint используются только для создания событий в реальном времени и управления ими.

Ресурсы
`liveBroadcast`	Содержит информацию о событии, которое вы транслируете на YouTube. Ресурс `liveBroadcast` является расширением видеоресурса YouTube и устанавливает метаданные видео, которые относятся к прямой трансляции, но не к другим видео YouTube. Таким образом, ресурс `liveBroadcast` соответствует ровно одному видеоресурсу YouTube. На самом деле ресурс `liveBroadcast` и ресурс `video` имеют один и тот же идентификатор. А после создания трансляции с помощью API Live Streaming вы можете использовать API данных YouTube для предоставления дополнительных метаданных о видео.
`liveStream`	Содержит информацию о видеопотоке, который вы передаете на YouTube. Поток предоставляет контент, который будет транслироваться пользователям YouTube. После создания ресурс `liveStream` может быть привязан только к одному ресурсу `liveBroadcast` . (Аналогичным образом ресурс `liveBroadcast` может быть привязан только к одному ресурсу `liveStream` .
`cuepoint`	Вставляет ключевую точку в транслируемый видеопоток, которая может вызвать рекламную паузу. Используйте метод `liveBroadcasts.cuepoint` , чтобы вставить ключевую точку во время трансляции.
`video`	Представляет одно видео YouTube. Как отмечалось выше, ресурс `liveBroadcast` является расширением `video` . Вы можете использовать API данных YouTube для обновления метаданных о видео, таких как место записи или регионы, в которых трансляция будет доступна для просмотра.
`videoAdvertisingOptions`	Определяет настройки рекламы для видео (или трансляции). Вы используете YouTube Content ID API для настройки параметров рекламы.
`asset`	Представляет объект интеллектуальной собственности, например фильм или эпизод шоу. В этом случае транслируемое видео является активом. Вы будете использовать YouTube Content ID API для создания ресурсов `asset` и управления ими.
`claim`	Связывает видео с ресурсом, которому соответствует видео. Вы создаете заявку с помощью YouTube Content ID API , чтобы идентифицировать себя как владельца транслируемого видео.
`policy`	Определяет правила, определяющие обстоятельства, при которых вы хотите, чтобы ваш контент был доступен для просмотра на YouTube или заблокирован от показа на YouTube. Вам необходимо применить политику к транслируемому видео, а также можно указать политику, которую YouTube будет применять к загруженным пользователями видео, соответствующим вашему транслируемому видео.

Поддерживаемые операции

В следующей таблице показаны различные методы, поддерживаемые API:

Операции
`list`	Извлекает ( `GET` ) список из нуля или более ресурсов.
`insert`	Создает ( `POST` ) новый ресурс.
`update`	Изменяет ( `PUT` ) существующий ресурс, чтобы отразить данные в вашем запросе.
`bind`	Связывает ресурс `liveBroadcast` с ресурсом `liveStream` или удаляет такую ссылку.
`transition`	Изменяет статус ресурса `liveBroadcast` и инициирует любые процессы, связанные с новым статусом. Например, когда вы переводите трансляцию в статус `testing` , YouTube начинает передавать видео в поток монитора этой трансляции.
`delete`	Удаляет ( `DELETE` ) определенный ресурс.

В таблице ниже указаны операции, которые поддерживаются для различных типов ресурсов. Операции по вставке, обновлению или удалению ресурсов всегда требуют авторизации пользователя . В некоторых случаях методы list поддерживают как авторизованные, так и неавторизованные запросы, где неавторизованные запросы извлекают только общедоступные данные, тогда как авторизованные запросы также могут извлекать информацию, которая ограничена текущим аутентифицированным пользователем.

Поддерживаемые операции
	list	insert	update	bind	transition	cuepoint	delete
прямая трансляция
прямой эфир

Частичные ресурсы

API позволяет и фактически требует частичного извлечения ресурсов, чтобы приложения избегали передачи, анализа и хранения ненужных данных. Этот подход также гарантирует, что API более эффективно использует ресурсы сети, ЦП и памяти.

Параметр part является обязательным параметром для любого запроса API, который извлекает или возвращает ресурс YouTube Data API . Параметр определяет одно или несколько свойств ресурсов верхнего уровня (невложенных), которые должны быть включены в ответ API. Например, ресурс liveStream состоит из следующих частей:

snippet
cdn
status

Все эти части являются объектами, которые содержат вложенные свойства, и вы можете думать об этих объектах как о группах полей метаданных, которые сервер API может (или не может) извлекать. Таким образом, параметр part требует от вас выбора компонентов ресурсов, которые фактически использует ваше приложение. Это требование служит двум важным целям:

Это уменьшает задержку, не позволяя серверу API тратить время на получение полей метаданных, которые не используются вашим приложением.
Это снижает использование полосы пропускания за счет уменьшения (или устранения) объема ненужных данных, которые может получить ваше приложение.

Со временем, когда ресурсы добавляют больше частей, эти преимущества будут только увеличиваться, поскольку ваше приложение не будет запрашивать новые введенные свойства, которые оно не поддерживает.

Советы и рекомендации

Заявите права на свой контент

Если вы хотите показывать рекламу во время трансляции, вам необходимо заявить права на транслируемое видео до начала мероприятия. Чтобы претендовать на контент, вы должны быть контент-партнером YouTube , участвующим в программе Content ID .

Процесс подачи заявки на видео в прямом эфире отличается от обычного процесса подачи заявки на видео. При подаче заявки на видео в прямом эфире вам необходимо создать заявку до того, как видео действительно появится. API поддерживает это, и жизнь документа трансляции объясняет вызовы YouTube Content ID API , которые позволяют вам создать свою заявку.

Предварительный просмотр и тестирование вашего контента

После получения вашего входящего видеопотока YouTube может транслировать это видео в двух разных исходящих потоках:

Поток монитора позволяет вам просматривать (и тестировать) вашу видеотрансляцию. Это частный поток, доступный только вам. Вы можете перевести трансляцию в фазу testing только в том случае, если включен поток монитора трансляции. В потоке мониторинга не отображаются рекламные паузы.
Трансляционный поток — это поток, видимый вашей аудитории. Вы можете установить статус конфиденциальности трансляции: public , private или unlisted . (Частная трансляция видна только пользователям, которые были явно приглашены для ее просмотра, в то время как незарегистрированная трансляция видна всем, у кого есть ссылка для ее просмотра.)
Вы можете выбрать задержку широковещательного потока, чтобы он не запускался одновременно с потоком монитора. Задерживая трансляцию, вы можете более точно контролировать время, в течение которого вы вставляете ключевые точки в трансляцию.
Однако задержка трансляции затрудняет взаимодействие ваших выступающих в прямом эфире с вашей аудиторией. Кроме того, задержка трансляции повышает вероятность того, что зрители узнают ключевые подробности о мероприятии из источников, отличных от вашей трансляции. Например, если вы транслируете спортивное событие с 60-секундной задержкой, зрители могут узнать о важных моментах события из других источников новостей в режиме реального времени, прежде чем они увидят их в трансляции.

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

Запуск рекламы в середине трансляции во время трансляции

Во время трансляции вы можете вставить ключевую точку , чтобы указать, что рекламная пауза должна начаться в трансляции как можно скорее или в указанное время. Рекламная пауза позволяет YouTube показывать рекламу в середине трансляции во время трансляции.

Рекламные паузы имеют следующие характеристики:

Он имеет предопределенную продолжительность, которую вы устанавливаете с помощью свойства durationSecs ресурса cuepoint . После окончания рекламной паузы зрители возвращаются к прямому эфиру.
Когда происходит рекламная пауза, реклама воспроизводится в видеоплеере только для зрителей, которые смотрят трансляцию, когда вставлена ключевая точка. Объявление не показывается, когда зрители обновляют страницу, на которой идет трансляция, или когда посетители начинают смотреть трансляцию после того, как вставлена ключевая точка.

Приведенная ниже последовательность шагов отражает наилучшую практику вставки рекламной паузы во время трансляции:

Установите смещения времени

При вставке точки метки вы можете указать, что она должна быть вставлена сразу или что она должна быть вставлена в определенный момент трансляции. Ваши варианты зависят от того, задерживается ли трансляция вашего видео.

Если ваш транслируемый поток не задерживается, то вы можете сразу же вставить ключевую точку или использовать свойство walltimeMs , чтобы рекламная пауза начиналась в определенное время.
- Чтобы немедленно начать рекламную паузу, вызовите метод liveBroadcasts.cuepoint . В ресурсе в тексте запроса установите для свойства insertionOffsetTimeMs значение 0 или не указывайте значение для этого свойства и не указывайте значение для свойства walltimeMs .
  Важно: обратите внимание, что зрители не сразу увидят итоговое рекламное содержание. Может быть задержка около 30 секунд, прежде чем содержание объявления станет видимым для пользователей. Во время этой задержки ваш транслируемый поток все еще будет виден вашим зрителям, и вам необходимо просмотреть транслируемый поток, чтобы определить, когда на самом деле отображается рекламный контент вместо вашего мониторного потока.
- Чтобы начать рекламную паузу в определенное время, вызовите метод liveBroadcasts.cuepoint и используйте свойство walltimeMs , чтобы указать нужное время. Значение свойства — это целое число, представляющее отметку времени эпохи.
Если ваш широковещательный поток задерживается, вы можете сразу же вставить ключевую точку, как описано выше, указать время на часах, как описано выше, или вы можете указать смещение по времени, чтобы определить, когда начнется рекламная пауза. Смещение по времени указывает точку в вашей трансляции, когда зрители должны увидеть рекламу.
Значение смещения измеряется в миллисекундах от начала потока монитора для вашей трансляции. Обратите внимание, что если ваша трансляция находится в стадии тестирования, то поток мониторинга запускается, когда ваша трансляция переходит в статус testing . В противном случае поток вашего монитора запускается, когда ваша трансляция переходит в статус live трансляции.
При вставке ключевой точки задайте для свойства insertionOffsetTimeMs ресурса cuepoint желаемое смещение.

Рассчитать значение смещения времени

Чтобы получить значение смещения, вызовите функцию getCurrentTime API проигрывателя YouTube для проигрывателя, воспроизводящего поток монитора. Используйте полученное значение, чтобы вставить ключевую точку в поток вещания в это время.

Возможные значения времени смещения могут быть рассчитаны как следующий диапазон:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ — это пятисекундный буфер в начале и в конце возможных временных смещений, когда YouTube не может точно вставить ключевую точку. Например:

Трансляция имеет пятиминутную фазу тестирования.
Поток вещания задерживается на 60 секунд после потока монитора.
Вещательная компания вставляет ключевую точку через четыре минуты после перехода трансляции в режим live . (Это происходит через три минуты после того, как трансляция становится видимой.)

В этом случае возможный диапазон времени смещения равен [(485,000), (535,000)] .

Это время указывается в миллисекундах и рассчитывается с использованием следующих значений:

elapsed_time=540000 — поток монитора выполнялся в течение девяти минут (540 секунд, 540000 миллисекунд), когда вызывается метод liveBroadcasts.cuepoint .
broadcast_delay=60000 — широковещательный поток задерживается на 60 секунд или 60000 миллисекунд.
Δ=5000 — пятисекундный буфер, когда точка метки не может быть надежно вставлена.

Устранение неполадок и обработка ошибок

Следующие рекомендации объясняют, как решить конкретные проблемы, которые могут возникнуть. Также см. в документации по ошибкам списки ошибок, которые может возвращать каждый метод API.

Когда трансляция переходит из одного статуса в другой, ей может быть временно присвоен другой статус, пока YouTube завершает действия, связанные с переходом. Например, если вы отправляете запрос liveBroadcasts.transition для изменения статуса трансляции с ready на testing , YouTube установит для трансляции статус testStarting , а затем выполнит действия, связанные с изменением статуса. Когда все эти действия будут выполнены, YouTube изменит статус трансляции на testing , тем самым показывая, что переход завершен.
Если трансляция застревает со статусом testStarting или liveStarting , вам необходимо вызвать метод liveBroadcasts.delete и удалить трансляцию. Затем создайте новую трансляцию, привяжите ее к своей прямой трансляции и продолжите процесс тестирования.
Как указано в документации метода liveBroadcasts.transition , перед вызовом этого метода следует убедиться, что значение свойства status.streamStatus для потока, связанного с вашей трансляцией, active .