YouTube Data API позволяет добавлять на сайт или в приложение функции, которые обычно выполняются на сайте YouTube. В следующих разделах описаны разные типы ресурсов, которые можно получить с помощью API. API также поддерживает методы для вставки, обновления и удаления многих из этих ресурсов.
В этом справочном руководстве рассказывается, как использовать API для выполнения всех этих операций. Руководство разделено на разделы по типам ресурсов. Ресурс – это тип объекта, который является частью YouTube, например видео, плейлист или подписка. Для каждого типа ресурса в руководстве приведено одно или несколько представлений данных, а ресурсы представлены в виде объектов JSON. В руководстве также перечислены один или несколько поддерживаемых методов (LIST, POST, DELETE и т. д.) для каждого типа ресурса и объясняется, как использовать эти методы в приложении.
Вызов API
К запросам к YouTube Data API применяются следующие требования:
-
В каждом запросе должен быть указан ключ API (с параметром
key) или токен OAuth 2.0. Ключ API доступен на панели API Access (Доступ к API) в Developer Console. -
Вы должны отправлять токен авторизации для каждого запроса на вставку, обновление и удаление. Кроме того, вы должны отправлять токен авторизации для любого запроса, который извлекает конфиденциальные данные аутентифицированного пользователя.
Кроме того, некоторые методы API для получения ресурсов могут поддерживать параметры, требующие авторизации, или содержать дополнительные метаданные, когда запросы авторизованы. Например, запрос на получение загруженных пользователем видео может также содержать личные видео, если запрос авторизован этим пользователем.
-
API поддерживает протокол аутентификации OAuth 2.0. Вы можете предоставить токен OAuth 2.0 одним из следующих способов:
- Используйте параметр запроса
access_tokenследующим образом:?access_token=oauth2-token. - Используйте заголовок HTTP
Authorizationследующим образом:Authorization: Beareroauth2-token
Подробные инструкции по реализации аутентификации OAuth 2.0 в приложении можно найти в руководстве по аутентификации.
- Используйте параметр запроса
Типы ресурсов
Действия
Ресурс activity содержит информацию о действии, которое определенный канал или пользователь совершил на YouTube. В фиде действий отражаются такие действия, как оценка видео, его публикация, добавление в избранное, загрузка и т. д. Каждый ресурс activity определяет тип действия, канал, связанный с действием, и ресурсы, связанные с действием, например видео, которое было оценено или загружено.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /activities |
Возвращает список событий на канале, соответствующих критериям запроса. Например, вы можете получить события, связанные с определенным каналом или с каналом пользователя. |
Субтитры
Ресурс caption представляет собой дорожку субтитров YouTube. Одна дорожка субтитров связана только с одним видео на YouTube.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /captions |
Удаляет указанную дорожку субтитров. |
download |
GET /captions/id |
Скачивает дорожку субтитров. Дорожка субтитров возвращается в исходном формате, если в запросе не указано значение параметра tfmt, и на исходном языке, если в запросе не указано значение параметра tlang. |
insert |
POST /captions |
Загружает дорожку субтитров. |
list |
GET /captions |
Возвращает список дорожек субтитров, связанных с указанным видео. Ответ API не содержит фактических субтитров, а метод captions.download позволяет получить дорожку субтитров. |
update |
PUT /captions |
Обновляет дорожку субтитров. При обновлении дорожки субтитров можно изменить ее статус черновика, загрузить новый файл субтитров или сделать и то, и другое. |
ChannelBanners
Ресурс channelBanner содержит URL, который можно использовать, чтобы установить загруженное изображение в качестве баннера канала.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
insert |
POST /channelBanners/insert |
Загружает изображение баннера канала на YouTube. Этот метод представляет собой первые два шага в трехэтапном процессе обновления баннера канала:
|
ChannelSections
Ресурс channelSection содержит информацию о наборе видео, которые автор канала выбрал для продвижения. Например, в одном разделе могут быть последние загруженные видео, в другом – самые популярные, а в третьем – плейлисты.
Разделы видны только в режиме просмотра. Чтобы включить показ контента канала в режиме просмотра, задайте для свойства brandingSettings.channel.showBrowseView значение true.
На канале можно создать не более 10 разделов.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /channelSections |
Удаляет раздел канала. |
insert |
POST /channelSections |
Добавляет раздел на канал пользователя, прошедшего аутентификацию. На канале может быть не более 10 разделов. |
list |
GET /channelSections |
Возвращает список ресурсов channelSection, соответствующих критериям запроса к API. |
update |
PUT /channelSections |
Изменяет раздел канала. |
Каналы
Ресурс channel содержит информацию о канале YouTube.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /channels |
Возвращает коллекцию из нуля или более ресурсов channel, соответствующих критериям запроса. |
update |
PUT /channels |
Обновляет метаданные канала. Этот метод поддерживает только обновление объектов brandingSettings и invideoPromotion ресурса channel и их дочерних свойств. |
CommentThreads
Ресурс commentThread содержит информацию о цепочке комментариев YouTube, которая состоит из комментария верхнего уровня и ответов на него (если они есть). Ресурс commentThread может представлять комментарии к видео или каналу.
Комментарии верхнего уровня и ответы на них – это ресурсы comment, вложенные в ресурс commentThread. Ресурс commentThread не обязательно содержит все ответы на комментарий. Чтобы получить все ответы на определенный комментарий, используйте метод comments.list. Кроме того, у некоторых комментариев нет ответов.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /commentThreads |
Возвращает список цепочек комментариев, соответствующих параметрам запроса к API. |
insert |
POST /commentThreads |
Создает новый комментарий верхнего уровня. Чтобы добавить ответ на существующий комментарий, используйте метод comments.insert. |
Комментарии
Ресурс comment содержит информацию об одном комментарии на YouTube. comment может представлять собой комментарий к видео или каналу. Кроме того, комментарий может быть как основным, так и ответом на основной комментарий.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /comments |
Возвращает список комментариев, соответствующих параметрам запроса к API. |
setModerationStatus |
POST /comments/setModerationStatus |
Устанавливает статус модерации для одного или нескольких комментариев. Запрос к API должен быть авторизован владельцем канала или видео, с которыми связаны комментарии. |
insert |
POST /comments |
Создает ответ на существующий комментарий. Примечание. Чтобы создать комментарий верхнего уровня, используйте метод commentThreads.insert. |
delete |
DELETE /comments |
Удаляет комментарий. |
update |
PUT /comments |
Изменяет комментарий. |
I18nLanguages
Ресурс i18nLanguage определяет язык приложения, который поддерживается на сайте YouTube. Язык приложения также может называться языком интерфейса. На сайте YouTube язык приложения может выбираться автоматически на основе настроек аккаунта Google, языка браузера или IP-адреса. Пользователь также может вручную выбрать язык интерфейса в нижнем колонтитуле сайта YouTube.
Каждый ресурс i18nLanguage содержит код и название языка. Код языка можно использовать в качестве значения параметра hl при вызове методов API, таких как videoCategories.list.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /i18nLanguages |
Возвращает список языков, поддерживаемых сайтом YouTube. |
I18nRegions
i18nRegion – это ресурс, который определяет географическую область, которую пользователь YouTube может выбрать в качестве предпочтительного региона для просмотра контента. Регион контента также может называться языковым стандартом контента. На сайте YouTube регион контента может выбираться автоматически на основе эвристических данных, таких как домен YouTube или IP-адрес пользователя. Пользователь также может вручную выбрать регион в нижнем колонтитуле сайта YouTube.
Каждый ресурс i18nRegion содержит код и название региона. Код региона можно использовать в качестве значения параметра regionCode при вызове методов API, таких как search.list, videos.list, activities.list и videoCategories.list.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /i18nRegions |
Возвращает список регионов, поддерживаемых сайтом YouTube. |
Для спонсоров
Ресурс member представляет спонсора канала YouTube. Спонсор регулярно поддерживает автора финансово и получает за это бонусы. Например, если автор включил режим чата только для спонсоров, то отправлять сообщения могут только спонсоры.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /members |
Показывает список спонсоров канала. Запрос к API должен быть авторизован владельцем канала. |
MembershipsLevels
Ресурс membershipsLevel определяет уровень спонсорства для автора, который авторизовал запрос к API.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /membershipsLevels |
Возвращает коллекцию, содержащую ресурсы membershipsLevel (их может быть несколько или не быть вообще), которые принадлежат каналу, авторизовавшему запрос к API. Уровни возвращаются в неявном порядке отображения. |
PlaylistItems
Ресурс playlistItem идентифицирует другой ресурс, например видео, которое включено в плейлист. Кроме того, ресурс playlistItem содержит сведения о включенном ресурсе, которые относятся к тому, как он используется в плейлисте.
На YouTube плейлисты также используются для того, чтобы показывать список загруженных видео на канале. Каждое playlistItem в этом списке представляет собой одно загруженное видео. Идентификатор этого плейлиста можно получить из ресурса channel resource для определенного канала. Затем вы можете использовать метод playlistItems.list, чтобы получить список.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /playlistItems |
Удаляет элемент плейлиста. |
insert |
POST /playlistItems |
Добавляет ресурс в плейлист. |
list |
GET /playlistItems |
Возвращает коллекцию объектов playlistItem, соответствующих параметрам запроса к API. Вы можете получить все объекты из определенного плейлиста или один или несколько объектов по их уникальным идентификаторам. |
update |
PUT /playlistItems |
Изменить объект playlistItem. Например, вы можете изменить позицию элемента в плейлисте. |
Плейлисты
Ресурс playlist представляет плейлист YouTube. Плейлист – это подборка видео, которые можно смотреть по очереди и которыми можно делиться с другими пользователями. По умолчанию плейлисты видны всем пользователям, но вы можете сделать их доступными только вам.
Плейлисты также используются для создания специальных подборок видео на канале, например:
- загруженные видео;
- видео, которым вы поставили лайк;
- история просмотров
- Посмотреть позже
Эти списки связаны с каналом, который представляет собой коллекцию видео, плейлистов и другой информации о пользователе, группе или компании на YouTube. Идентификаторы этих плейлистов можно получить из ресурса channel resource для определенного канала.
Затем вы можете использовать метод playlistItems.list, чтобы получить любой из этих списков. Вы также можете добавлять и удалять элементы из этих списков, вызывая методы playlistItems.insert и playlistItems.delete.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /playlists |
Удаляет плейлист. |
list |
GET /playlists |
Возвращает коллекцию плейлистов, соответствующих параметрам запроса к API. Например, вы можете получить все плейлисты, принадлежащие пользователю, прошедшему аутентификацию, или один или несколько плейлистов по их уникальным идентификаторам. |
insert |
POST /playlists |
Создает плейлист. |
update |
PUT /playlists |
Изменяет плейлист. Например, вы можете изменить название, описание или настройки доступа. |
Поиск
Результат поиска содержит информацию о видео, канале или плейлисте YouTube, которые соответствуют параметрам поиска, указанным в запросе к API. Результат поиска указывает на однозначно идентифицируемый ресурс, например видео, но не имеет собственных постоянных данных.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /search |
Возвращает набор результатов поиска, соответствующих параметрам запроса, указанным в запросе к API. По умолчанию набор результатов поиска определяет соответствующие ресурсы video, channel и playlist, но вы также можете настроить запросы так, чтобы получать только определенный тип ресурса. |
Подписки
Ресурс subscription содержит информацию о подписке пользователя YouTube. Подписчики получают уведомления о новых видео на канале и о действиях других пользователей, например о загрузке видео, оценке или комментарии.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /subscriptions |
Удаляет подписку. |
insert |
POST /subscriptions |
Добавляет подписку на канал аутентифицированного пользователя. |
list |
GET /subscriptions |
Возвращает ресурсы подписок, соответствующие критериям запроса к API. |
Значки видео
Ресурс thumbnail определяет разные размеры значков, связанные с ресурсом. Значки видео имеют следующие характеристики:
- Свойство
snippet.thumbnailsресурса – это объект, который идентифицирует значки, доступные для этого ресурса. - Ресурс
thumbnailсодержит ряд объектов. Название каждого объекта (default,medium,highи т. д.) указывает на размер значка. - Для разных типов ресурсов могут поддерживаться разные размеры значков.
- Для разных типов ресурсов могут быть заданы разные размеры значков с одним и тем же названием. Например, значок
defaultдля ресурсаvideoобычно имеет размер 120 x 90 пикселей, а значокdefaultдля ресурсаchannel– 88 x 88 пикселей. - У ресурсов одного типа могут быть разные размеры значков, если исходное изображение или контент, загруженный на YouTube, имеет другое разрешение. Например, для HD-видео можно использовать значки с более высоким разрешением, чем для видео в стандартном качестве.
- Каждый объект, содержащий информацию о размере значка, имеет свойства
widthиheight. Однако свойства ширины и высоты могут не возвращаться для этого изображения. - Если загруженное изображение не соответствует требованиям к размеру, оно будет автоматически изменено без искажения соотношения сторон. Изображение не обрезается, но может содержать черные полосы, чтобы размер был правильным.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
set |
POST /thumbnails/set |
Загружает на YouTube собственный значок видео и устанавливает его для видео. |
VideoAbuseReportReasons
Ресурс videoAbuseReportReason содержит информацию о причине, по которой видео может быть помечено как содержащее недопустимый контент. Когда ваше приложение вызывает метод videos.reportAbuse, чтобы сообщить о видео с нарушениями, запрос использует информацию из ресурса videoAbuseReportReason, чтобы определить причину жалобы.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /videoAbuseReportReasons |
Получить список причин, по которым можно пожаловаться на видео с нарушениями. |
VideoCategories
Ресурс videoCategory определяет категорию, которая была или может быть связана с загруженными видео.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
list |
GET /videoCategories |
Возвращает список категорий, которые можно связать с видео на YouTube. |
Видео
Ресурс video представляет видео на YouTube.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
insert |
POST /videos |
Загружает видео на YouTube и при необходимости задает его метаданные. |
list |
GET /videos |
Возвращает список видео, соответствующих параметрам запроса к API. |
delete |
DELETE /videos |
Удаляет видео на YouTube. |
update |
PUT /videos |
Обновляет метаданные видео. |
rate |
POST /videos/rate |
Ставить лайки и дизлайки. |
getRating |
GET /videos/getRating |
Получает оценки, которые авторизованный пользователь поставил указанным видео. |
reportAbuse |
POST /videos/reportAbuse |
Пожаловаться на видео с недопустимым контентом. |
Водяные знаки
Ресурс watermark представляет собой изображение, которое показывается во время воспроизведения видео на определенном канале. Вы также можете указать целевой канал, на который будет вести водяной знак, а также время его появления и продолжительность показа.
Дополнительную информацию об этом ресурсе можно найти в его представлении и списке свойств.
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI, относящиеся к https://www.googleapis.com/youtube/v3 |
||
set |
POST /watermarks/set |
Загружает изображение водяного знака на YouTube и устанавливает его для канала. |
unset |
POST /watermarks/unset |
Удаляет водяной знак канала. |