Обзор API данных YouTube

Введение

Этот документ предназначен для разработчиков, которые хотят писать приложения, взаимодействующие с YouTube. В нем объясняются основные понятия YouTube и самого API. Он также предоставляет обзор различных функций, поддерживаемых API.

Прежде чем ты начнешь

  1. Вам нужна учетная запись Google , чтобы получить доступ к консоли Google API, запросить ключ API и зарегистрировать свое приложение.

  2. Создайте проект в Google Developers Console и получите учетные данные авторизации , чтобы ваше приложение могло отправлять запросы API.

  3. После создания проекта убедитесь, что API данных YouTube является одной из служб, для использования которых зарегистрировано ваше приложение:

    1. Перейдите в Консоль API и выберите проект, который вы только что зарегистрировали.
    2. Посетите страницу «Включенные API» . В списке API убедитесь, что для YouTube Data API v3 включен статус .

  4. Если ваше приложение будет использовать какие-либо методы API, требующие авторизации пользователя, прочтите руководство по аутентификации , чтобы узнать, как реализовать авторизацию OAuth 2.0.

  5. Выберите клиентскую библиотеку , чтобы упростить реализацию API.

  6. Ознакомьтесь с основными понятиями формата данных 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. Пример 1 возвращает видеоресурс, который включает четыре части, а также свойства kind и etag .
  2. Пример 2 возвращает видеоресурс, который включает две части, а также свойства kind и etag .
  3. Пример 3 возвращает видеоресурс, который включает две части, но не включает свойства kind и etag .
  4. Пример 4 возвращает видеоресурс, который включает две части, но не включает kind и etag , а также некоторые вложенные свойства в объекте snippet ресурса.
Пример 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status
Description: This example retrieves a video 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" } } ] }
Пример 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics
Description: This example modifies the part parameter value so that the contentDetails and status 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" } } ] }
Пример 3
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 the fields parameter to remove all kind and etag 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" } } ] }
Пример 4
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 the fields parameter from example 3 so that in the API response, each video resource's snippet object only includes the channelId, title, and categoryId 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 отличаются поддержкой ETag. Например, клиентская библиотека JavaScript поддерживает ETag через белый список разрешенных заголовков запросов, который включает If-Match и If-None-Match . Белый список позволяет выполнять обычное кэширование браузера, так что, если ETag ресурса не изменился, ресурс можно обслуживать из кэша браузера. С другой стороны, клиент Obj-C не поддерживает ETag.

  • Защита от непреднамеренной перезаписи изменений — ETag помогают гарантировать, что несколько клиентов API не будут непреднамеренно перезаписывать изменения друг друга. При обновлении или удалении ресурса ваше приложение может указать ETag ресурса. Если ETag не соответствует самой последней версии этого ресурса, запрос API завершается ошибкой.

Использование ETag в вашем приложении дает несколько преимуществ:

  • 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)