API данных YouTube позволяет интегрировать функции, обычно выполняемые на сайте YouTube, в ваш собственный сайт или приложение. В следующих разделах описаны различные типы ресурсов, которые можно получить с помощью API. API также поддерживает методы вставки, обновления и удаления многих из этих ресурсов.
В этом справочном руководстве объясняется, как использовать API для выполнения всех этих операций. Руководство структурировано по типам ресурсов. Ресурс представляет собой тип элемента, входящего в состав YouTube, например, видео, плейлист или подписка. Для каждого типа ресурса в руководстве перечислены одно или несколько представлений данных, а сами ресурсы представлены в виде JSON-объектов. В руководстве также перечислены один или несколько поддерживаемых методов ( LIST , POST , DELETE и т. д.) для каждого типа ресурса и объясняется, как использовать эти методы в вашем приложении.
Вызов API
К запросам API данных YouTube применяются следующие требования:
В каждом запросе необходимо либо указать ключ API (с параметром
key), либо предоставить токен OAuth 2.0. Ваш ключ API доступен на панели «Доступ к API» консоли разработчика для вашего проекта.Вы должны отправлять токен авторизации для каждого запроса на вставку, обновление и удаление. Вы также должны отправлять токен авторизации для любого запроса, извлекающего личные данные аутентифицированного пользователя.
Кроме того, некоторые методы API для извлечения ресурсов могут поддерживать параметры, требующие авторизации, или содержать дополнительные метаданные при авторизации запросов. Например, запрос на извлечение загруженных пользователем видео может также содержать приватные видео, если запрос авторизован этим пользователем.
API поддерживает протокол аутентификации OAuth 2.0. Вы можете предоставить токен OAuth 2.0 одним из следующих способов:
- Используйте параметр запроса
access_tokenследующим образом:?access_token=oauth2-token - Используйте заголовок HTTP
Authorizationследующим образом:Authorization: Beareroauth2-token
Полные инструкции по внедрению аутентификации OAuth 2.0 в ваше приложение можно найти в руководстве по аутентификации .
- Используйте параметр запроса
Типы ресурсов
Activities
Ресурс activity содержит информацию о действии, которое совершил конкретный канал или пользователь на YouTube. В лентах активности отображаются такие действия, как оценка видео, публикация видео, добавление видео в избранное, загрузка видео и т. д. Каждый ресурс activity определяет тип действия, канал, связанный с действием, и ресурсы, связанные с действием, например, видео, которое было оценено или загружено.
Дополнительную информацию об этом ресурсе см. в его представлении ресурса и списке свойств .
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI относительно https://www.googleapis.com/youtube/v3 | ||
list | GET /activities | Возвращает список событий активности канала, соответствующих критериям запроса. Например, вы можете получить события, связанные с конкретным каналом или с собственным каналом пользователя. |
Captions
Ресурс 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 | Обновляет раздел канала. |
Channels
Ресурс 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 . |
Comments
Ресурс 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. |
Members
Ресурс 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 | Возвращает коллекцию элементов плейлиста, соответствующих параметрам запроса API. Вы можете получить все элементы указанного плейлиста или один или несколько элементов плейлиста по их уникальным идентификаторам. |
update | PUT /playlistItems | Изменяет элемент плейлиста. Например, можно обновить позицию элемента в плейлисте. |
Playlists
Ресурс playlist представляет собой плейлист YouTube. Плейлист — это набор видео, которые можно просматривать последовательно и делиться ими с другими пользователями. По умолчанию плейлисты доступны для просмотра другим пользователям, но могут быть как общедоступными, так и закрытыми.
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 | Изменяет плейлист. Например, можно изменить название, описание или статус конфиденциальности плейлиста. |
Search
Результат поиска содержит информацию о видео, канале или плейлисте YouTube, соответствующих параметрам поиска, указанным в запросе API. Хотя результат поиска указывает на уникально идентифицируемый ресурс, например, видео, он не имеет собственных постоянных данных.
Дополнительную информацию об этом ресурсе см. в его представлении ресурса и списке свойств .
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI относительно https://www.googleapis.com/youtube/v3 | ||
list | GET /search | Возвращает коллекцию результатов поиска, соответствующих параметрам запроса, указанным в API-запросе. По умолчанию набор результатов поиска определяет соответствующие ресурсы video , channel и playlist , но вы также можете настроить запросы для извлечения только определённого типа ресурсов. |
Subscriptions
Ресурс subscription содержит информацию о подписке пользователя YouTube. Подписка уведомляет пользователя о добавлении новых видео на канал или о выполнении другим пользователем одного из нескольких действий на YouTube, например, о загрузке видео, оценке видео или комментировании видео.
Дополнительную информацию об этом ресурсе см. в его представлении ресурса и списке свойств .
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI относительно https://www.googleapis.com/youtube/v3 | ||
delete | DELETE /subscriptions | Удаляет подписку. |
insert | POST /subscriptions | Добавляет подписку на канал аутентифицированного пользователя. |
list | GET /subscriptions | Возвращает ресурсы подписки, соответствующие критериям запроса API. |
Thumbnails
Ресурс thumbnail определяет различные размеры миниатюрных изображений, связанных с ресурсом. Изображения миниатюр имеют следующие характеристики:
- Свойство
snippet.thumbnailsресурса — это объект, который идентифицирует миниатюрные изображения, доступные для этого ресурса. - Ресурс
thumbnailсодержит ряд объектов. Имя каждого объекта (default,medium,highи т. д.) соответствует размеру изображения миниатюры. - Различные типы ресурсов могут поддерживать различные размеры миниатюрных изображений.
- Разные типы ресурсов могут определять разные размеры миниатюр с одинаковым именем. Например, миниатюра
defaultдляvideoобычно имеет размер 120x90 пикселей, а миниатюраdefaultдля ресурсаchannel— 88x88 пикселей. - Ресурсы одного типа могут иметь разные размеры миниатюр для некоторых изображений в зависимости от разрешения исходного изображения или контента, загруженного на YouTube. Например, HD-видео может поддерживать более высокое разрешение миниатюр, чем видео в формате, отличном от 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. |
Videos
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 | Сообщить о видео, содержащем оскорбительный контент. |
Watermarks
Ресурс watermark определяет изображение, которое отображается при воспроизведении видео на определённом канале. Вы также можете указать целевой канал, с которым будет связано изображение, а также временные параметры, определяющие, когда и как долго водяной знак будет отображаться при воспроизведении видео.
Дополнительную информацию об этом ресурсе см. в его представлении ресурса и списке свойств .
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI относительно https://www.googleapis.com/youtube/v3 | ||
set | POST /watermarks/set | Загружает изображение водяного знака на YouTube и устанавливает его для канала. |
unset | POST /watermarks/unset | Удаляет водяной знак изображения канала. |