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: Bearer
oauth2-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. Плейлист — это набор видео, которые можно просматривать последовательно и делиться ими с другими пользователями. Список воспроизведения может содержать до 200 видео, и 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 на 90 пикселей, а миниатюраdefault
для ресурсаchannel
обычно имеет размер 88 на 88 пикселей. - Ресурсы одного типа могут по-прежнему иметь разные размеры эскизов для определенных изображений в зависимости от разрешения исходного изображения или контента, загруженного на 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 | Удаляет изображение водяного знака канала. |