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 | Возвращает список событий активности канала, соответствующих критериям запроса. Например, вы можете получить события, связанные с определенным каналом или с собственным каналом пользователя. |
insert | POST /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 . |
markAsSpam | POST /comments/markAsSpam | Примечание. Этот метод устарел и больше не поддерживается. |
delete | DELETE /comments | Удаляет комментарий. |
update | PUT /comments | Изменяет комментарий. |
GuideCategories
guideCategory определяет категорию, которую YouTube алгоритмически присваивает на основе контента канала или других показателей, таких как популярность канала. Список аналогичен категориям видео , с той разницей, что пользователь, загрузивший видео, может назначить категорию видео, а категорию канала может назначить только YouTube.
Дополнительные сведения об этом ресурсе см. в его представлении ресурса и списке свойств .
| Метод | HTTP-запрос | Описание |
|---|---|---|
URI относительно https://www.googleapis.com/youtube/v3 | ||
list | GET /guideCategories | Возвращает список категорий, которые можно связать с каналами YouTube. |
I18nLanguages
Ресурс i18nLanguage определяет язык приложения, который поддерживает веб-сайт YouTube. Язык приложения также можно назвать языком пользовательского интерфейса. Для веб-сайта YouTube язык приложения может выбираться автоматически на основе настроек учетной записи Google, языка браузера или местоположения IP. Пользователь также может вручную выбрать нужный язык пользовательского интерфейса в нижнем колонтитуле сайта YouTube.
Каждый ресурс i18nLanguage идентифицирует код языка и имя. Код языка можно использовать в качестве значения параметра hl при вызове таких методов API, как videoCategories.list guideCategories.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 также использует плейлисты для определения специальных коллекций видео для канала, например:
- загруженные видео
- видео с положительной оценкой (лайками)
- смотреть историю
- посмотреть позже
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обычно имеет размер 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. |
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 | Удаляет изображение водяного знака канала. |