Введение
Этот документ предназначен для разработчиков, которые хотят писать приложения, взаимодействующие с YouTube. В нем объясняются основные концепции YouTube и самого API. Здесь также представлен обзор различных функций, поддерживаемых API.
Прежде чем начать
Вам понадобится учетная запись Google , чтобы получить доступ к консоли Google API, запросить ключ API и зарегистрировать свое приложение.
Создайте проект в консоли разработчиков Google и получите учетные данные для авторизации , чтобы ваше приложение могло отправлять запросы API.
После создания проекта убедитесь, что API данных YouTube является одним из сервисов, для использования которых зарегистрировано ваше приложение:
- Перейдите в консоль API и выберите проект, который вы только что зарегистрировали.
- Посетите страницу «Включенные API» . Убедитесь, что в списке API для API данных YouTube v3 включен статус «ВКЛ» .
Если ваше приложение будет использовать какие-либо методы API, требующие авторизации пользователя, прочтите руководство по аутентификации , чтобы узнать, как реализовать авторизацию OAuth 2.0.
Выберите клиентскую библиотеку , чтобы упростить реализацию API.
Ознакомьтесь с основными понятиями формата данных JSON (нотация объектов JavaScript). JSON — это распространенный, независимый от языка формат данных, который обеспечивает простое текстовое представление произвольных структур данных. Для получения дополнительной информации посетите json.org .
Ресурсы и типы ресурсов
Ресурс — это отдельный объект данных с уникальным идентификатором. В таблице ниже описаны различные типы ресурсов, с которыми вы можете взаимодействовать с помощью API.
Ресурсы | |
---|---|
activity | Содержит информацию о действии, которое совершил конкретный пользователь на сайте YouTube. Действия пользователя, о которых сообщается в лентах активности, включают, среди прочего, оценку видео, публикацию видео, пометку видео как избранного, публикацию бюллетеня канала. |
channel | Содержит информацию об одном канале YouTube. |
channelBanner | Идентифицирует URL-адрес, который будет использоваться для установки только что загруженного изображения в качестве изображения баннера для канала. |
channelSection | Содержит информацию о наборе видеороликов, выбранных каналом для показа. Например, в разделе могут быть представлены последние загрузки канала, самые популярные загрузки или видео из одного или нескольких плейлистов. |
guideCategory | Определяет категорию, которую YouTube связывает с каналами на основе их контента или других показателей, например популярности. Категории справочников призваны организовать каналы таким образом, чтобы пользователям YouTube было легче находить нужный им контент. Хотя каналы могут быть связаны с одной или несколькими категориями гидов, их попадание в какую-либо из категорий гидов не гарантируется. |
i18nLanguage | Определяет язык приложения, который поддерживает веб-сайт YouTube. Язык приложения также можно назвать языком пользовательского интерфейса. |
i18nRegion | Определяет географическую область, которую пользователь YouTube может выбрать в качестве предпочтительного региона контента. Область контента также может называться локалью контента. |
playlist | Представляет один список воспроизведения YouTube. Плейлист — это набор видеороликов, которые можно просматривать последовательно и делиться ими с другими пользователями. |
playlistItem | Идентифицирует ресурс, например видео, который является частью списка воспроизведения. Ресурс playlistItem также содержит сведения, объясняющие, как включенный ресурс используется в списке воспроизведения. |
search result | Содержит информацию о видео, канале или плейлисте YouTube, соответствующем параметрам поиска, указанным в запросе API. Хотя результат поиска указывает на уникально идентифицируемый ресурс, например видео, он не имеет собственных постоянных данных. |
subscription | Содержит информацию о подписке пользователя YouTube. Подписка уведомляет пользователя, когда на канал добавляются новые видео или когда другой пользователь выполняет одно из нескольких действий на YouTube, например загружает видео, оценивает видео или комментирует видео. |
thumbnail | Идентифицирует миниатюры изображений, связанные с ресурсом. |
video | Представляет одно видео YouTube. |
videoCategory | Определяет категорию, которая была или могла быть связана с загруженными видео. |
watermark | Идентифицирует изображение, которое отображается во время воспроизведения видео указанного канала. Владелец канала также может указать целевой канал, на который ссылается изображение, а также сведения о времени, которые определяют, когда водяной знак появляется во время воспроизведения видео, а затем продолжительность его видимости. |
Обратите внимание, что во многих случаях ресурс содержит ссылки на другие ресурсы. Например, свойство snippet.resourceId.videoId
ресурса playlistItem
идентифицирует видеоресурс, который, в свою очередь, содержит полную информацию о видео. Другой пример: результат поиска содержит свойство videoId
, playlistId
или channelId
, которое идентифицирует конкретное видео, список воспроизведения или ресурс канала.
Поддерживаемые операции
В следующей таблице показаны наиболее распространенные методы, поддерживаемые API. Некоторые ресурсы также поддерживают другие методы, выполняющие функции, более специфичные для этих ресурсов. Например, метод videos.rate
связывает рейтинг пользователя с видео, а метод thumbnails.set
загружает миниатюру видео на YouTube и связывает ее с видео.
Операции | |
---|---|
list | Получает ( GET ) список из нуля или более ресурсов. |
insert | Создает ( POST ) новый ресурс. |
update | Изменяет ( PUT ) существующий ресурс для отражения данных в вашем запросе. |
delete | Удаляет ( DELETE ) определенный ресурс. |
В настоящее время API поддерживает методы для перечисления каждого из поддерживаемых типов ресурсов, а также поддерживает операции записи для многих ресурсов.
В таблице ниже указаны операции, которые поддерживаются для разных типов ресурсов. Операции по вставке, обновлению или удалению ресурсов всегда требуют авторизации пользователя . В некоторых случаях методы list
поддерживают как авторизованные, так и неавторизованные запросы, при этом неавторизованные запросы извлекают только общедоступные данные, тогда как авторизованные запросы могут также получать информацию о текущем аутентифицированном пользователе или личную для него.
Поддерживаемые операции | ||||
---|---|---|---|---|
list | insert | update | delete | |
activity | ||||
caption | ||||
channel | ||||
channelBanner | ||||
channelSection | ||||
comment | ||||
commentThread | ||||
guideCategory | ||||
i18nLanguage | ||||
i18nRegion | ||||
playlist | ||||
playlistItem | ||||
search result | ||||
subscription | ||||
thumbnail | ||||
video | ||||
videoCategory | ||||
watermark |
Использование квоты
YouTube Data API использует квоту, чтобы гарантировать, что разработчики используют службу по назначению и не создают приложения, которые несправедливо снижают качество услуги или ограничивают доступ для других. Все запросы API, включая недействительные запросы, включают стоимость квоты как минимум в один балл. Квоту, доступную вашему приложению, можно найти в API Console .
Проекты, в которых используется API данных YouTube, имеют квоту по умолчанию, равную 10 000 единиц в день, что достаточно для подавляющего большинства пользователей нашего API. Квота по умолчанию, которая может быть изменена, помогает нам оптимизировать распределение квот и масштабировать нашу инфраструктуру таким образом, чтобы это было более значимо для пользователей нашего API. Вы можете увидеть использование квоты на странице «Квоты» в консоли API.
Примечание. Если вы достигли предела квоты, вы можете запросить дополнительную квоту, заполнив форму запроса на расширение квоты для служб API YouTube.
Расчет использования квоты
Google рассчитывает использование квоты, назначая стоимость каждому запросу. Разные виды операций имеют разную стоимость квот. Например:
- Операция чтения, извлекающая список ресурсов — каналов, видео, плейлистов — обычно стоит 1 единицу.
- Операция записи, которая создает, обновляет или удаляет ресурс, обычно стоит
50
единиц. - Поисковый запрос стоит
100
единиц. - Загрузка видео стоит
1600
единиц.
В таблице «Стоимость квоты для запросов API» указана стоимость квоты для каждого метода API. Помня об этих правилах, вы можете оценить количество запросов, которые ваше приложение может отправлять в день, не превышая квоты.
Частичные ресурсы
API позволяет и фактически требует извлечения частичных ресурсов, чтобы приложения избегали передачи, анализа и хранения ненужных данных. Этот подход также гарантирует, что API более эффективно использует ресурсы сети, CPU и памяти.
API поддерживает два параметра запроса, которые описаны в следующих разделах и которые позволяют вам идентифицировать свойства ресурса, которые следует включать в ответы API.
- Параметр
part
определяет группы свойств, которые должны быть возвращены для ресурса. - Параметр
fields
фильтрует ответ API, чтобы возвращать только определенные свойства в запрошенных частях ресурса.
Как использовать параметр part
Параметр part
является обязательным параметром для любого запроса API, который извлекает или возвращает ресурс. Этот параметр определяет одно или несколько свойств ресурса верхнего уровня (не вложенных), которые следует включить в ответ API. Например, video
состоит из следующих частей:
-
snippet
-
contentDetails
-
fileDetails
-
player
-
processingDetails
-
recordingDetails
-
statistics
-
status
-
suggestions
-
topicDetails
Все эти части представляют собой объекты, содержащие вложенные свойства, и вы можете думать об этих объектах как о группах полей метаданных, которые сервер API может (или не может) получить. Таким образом, параметр part
требует, чтобы вы выбрали компоненты ресурсов, которые фактически использует ваше приложение. Это требование служит двум ключевым целям:
- Это уменьшает задержку, не позволяя серверу API тратить время на получение полей метаданных, которые ваше приложение не использует.
- Это снижает использование полосы пропускания за счет уменьшения (или устранения) объема ненужных данных, которые может получить ваше приложение.
Со временем, по мере того, как ресурсы добавляют больше частей, эти преимущества будут только увеличиваться, поскольку ваше приложение не будет запрашивать новые свойства, которые оно не поддерживает.
Как использовать параметр fields
Параметр fields
фильтрует ответ API, который содержит только части ресурса, указанные в значении параметра part
, так что ответ включает только определенный набор полей. Параметр fields
позволяет удалить вложенные свойства из ответа API и тем самым еще больше снизить использование полосы пропускания. (Параметр part
нельзя использовать для фильтрации вложенных свойств из ответа.)
Следующие правила объясняют поддерживаемый синтаксис для значения параметра fields
, который во многом основан на синтаксисе XPath :
- Используйте список, разделенный запятыми (
fields=a,b
), чтобы выбрать несколько полей. - Используйте звездочку (
fields=*
) в качестве подстановочного знака для обозначения всех полей. - Используйте круглые скобки (
fields=a(b,c)
), чтобы указать группу вложенных свойств, которые будут включены в ответ API. - Используйте косую черту (
fields=a/b
) для обозначения вложенного свойства.
На практике эти правила часто позволяют нескольким различным значениям параметров fields
получать один и тот же ответ API. Например, если вы хотите получить идентификатор, заголовок и позицию элемента списка воспроизведения для каждого элемента в списке воспроизведения, вы можете использовать любое из следующих значений:
-
fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
-
fields=items(id,snippet/title,snippet/position)
-
fields=items(id,snippet(title,position))
Примечание. Как и все значения параметров запроса, значение параметра fields
должно быть закодировано в URL-адресе. Для лучшей читаемости в примерах в этом документе кодировка не указана.
Примеры частичных запросов
В приведенных ниже примерах показано, как можно использовать part
и fields
, чтобы ответы API включали только те данные, которые использует ваше приложение:
- Пример 1 возвращает видеоресурс, который включает четыре части, а также свойства
kind
иetag
. - Пример 2 возвращает видеоресурс, который включает в себя две части, а также свойства
kind
иetag
. - Пример 3 возвращает видеоресурс, который состоит из двух частей, но не включает свойства
kind
иetag
. - Пример 4 возвращает видеоресурс, который состоит из двух частей, но исключает
kind
иetag
, а также некоторые вложенные свойства в объектеsnippet
ресурса.
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Description: This example retrieves avideo
resource and identifies several resource parts that should be included in the API response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "contentDetails": { "duration": "PT15M51S", "aspectRatio": "RATIO_16_9" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" }, "status": { "uploadStatus": "STATUS_PROCESSED", "privacyStatus": "PRIVACY_PUBLIC" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics Description: This example modifies thepart
parameter value so that thecontentDetails
andstatus
properties are not included in the response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics&fields=items(id,snippet,statistics) Description: This example adds thefields
parameter to remove allkind
andetag
properties from the API response. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics Description: This example modifies thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
properties. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
Оптимизация производительности
Использование ETag
ETags , стандартная часть протокола HTTP , позволяет приложениям ссылаться на определенную версию определенного ресурса API. Ресурсом может быть весь фид или элемент в этом фиде. Эта функция поддерживает следующие варианты использования:
Кэширование и условное извлечение . Ваше приложение может кэшировать ресурсы API и их ETag. Затем, когда ваше приложение снова запрашивает сохраненный ресурс, оно указывает ETag, связанный с этим ресурсом. Если ресурс изменился, API возвращает измененный ресурс и ETag, связанный с этой версией ресурса. Если ресурс не изменился, API возвращает ответ HTTP 304 (
Not Modified
), который указывает, что ресурс не изменился. Ваше приложение может уменьшить задержку и использование полосы пропускания, обслуживая кэшированные ресурсы таким образом.Клиентские библиотеки для API Google отличаются поддержкой ETags. Например, клиентская библиотека JavaScript поддерживает ETags через белый список разрешенных заголовков запросов, который включает
If-Match
иIf-None-Match
. Белый список позволяет осуществлять обычное кэширование браузера, поэтому, если ETag ресурса не изменился, ресурс может обслуживаться из кэша браузера. С другой стороны, клиент Obj-C не поддерживает ETags.Защита от непреднамеренной перезаписи изменений . ETags помогают гарантировать, что несколько клиентов API не будут случайно перезаписывать изменения друг друга. При обновлении или удалении ресурса ваше приложение может указать ETag ресурса. Если ETag не соответствует самой последней версии этого ресурса, запрос API не будет выполнен.
Использование ETags в вашем приложении дает несколько преимуществ:
- API быстрее реагирует на запросы кэшированных, но неизмененных ресурсов, что обеспечивает меньшую задержку и более низкое использование полосы пропускания.
- Ваше приложение не будет случайно перезаписывать изменения в ресурсе, внесенные из другого клиента API.
Google APIs Client Library for JavaScript поддерживает заголовки HTTP-запросов If-Match
и If-None-Match
, что позволяет ETags работать в контексте обычного кэширования браузера.
Использование gzip
Вы также можете уменьшить пропускную способность, необходимую для каждого ответа API, включив сжатие gzip. Хотя вашему приложению потребуется дополнительное время ЦП для распаковки ответов API, выгода от потребления меньшего количества сетевых ресурсов обычно перевешивает эти затраты.
Чтобы получить ответ в кодировке gzip, вам необходимо сделать две вещи:
- Установите для заголовка HTTP-запроса
Accept-Encoding
значениеgzip
. - Измените свой пользовательский агент, чтобы он содержал строку
gzip
.
Примеры HTTP-заголовков ниже демонстрируют эти требования для включения сжатия gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)