API данных YouTube позволяет интегрировать функции, обычно выполняемые на веб-сайте YouTube, в ваш собственный веб-сайт или приложение. В следующих разделах описаны различные типы ресурсов, которые можно получить с помощью API. API также поддерживает методы для добавления, обновления или удаления многих из этих ресурсов.
В этом справочном руководстве объясняется, как использовать API для выполнения всех этих операций. Руководство организовано по типам ресурсов. Ресурс представляет собой тип элемента, составляющего часть функционала YouTube, например, видео, плейлист или подписка. Для каждого типа ресурса в руководстве перечислены одно или несколько представлений данных, а ресурсы представлены в виде объектов JSON. В руководстве также перечислены один или несколько поддерживаемых методов ( LIST , POST , DELETE и т. д.) для каждого типа ресурса и объясняется, как использовать эти методы в вашем приложении.
Вызовите API
К запросам через YouTube Data API применяются следующие требования:
В каждом запросе необходимо либо указать ключ 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
An i18nLanguage resource identifies an application language that the YouTube website supports. The application language can also be referred to as a UI language. For the YouTube website, an application language could be automatically selected based on Google Account settings, browser language, or IP location. A user could also manually select the UI language from the YouTube site footer.
Каждый ресурс 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 | Удаляет изображение водяного знака канала. |