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

Введение

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

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

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

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

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

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

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

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

  6. Ознакомьтесь с основными понятиями формата данных JSON (JavaScript Object Notation). 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 .

Для проектов, использующих YouTube Data API, по умолчанию выделяется квота в 10 000 единиц в день, чего достаточно для подавляющего большинства пользователей нашего API. Эта квота по умолчанию, которая может быть изменена, помогает нам оптимизировать распределение квот и масштабировать нашу инфраструктуру таким образом, чтобы это было более удобно для пользователей API. Вы можете отслеживать использование своей квоты на странице «Квоты» в консоли API.

Примечание: Если вы достигли лимита квоты, вы можете запросить дополнительную квоту, заполнив форму запроса на расширение квоты для сервисов YouTube API.

Расчет использования квоты

Google рассчитывает использование вашей квоты, присваивая каждому запросу стоимость. Разные типы операций имеют разную стоимость квоты. Например:

  • Операция чтения, которая извлекает список ресурсов — каналов, видео, плейлистов — обычно стоит 1 единицу.
  • Операция записи, которая создает, обновляет или удаляет ресурс, обычно стоит 50 единиц.
  • Поисковый запрос стоит 100 единиц.
  • Загрузка видео стоит 100 единиц.

В таблице «Стоимость квот для запросов 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 ).

На практике эти правила часто позволяют получать один и тот же ответ API с несколькими различными значениями параметров fields . Например, если вы хотите получить идентификатор элемента плейлиста, название и позицию для каждого элемента в плейлисте, вы можете использовать любое из следующих значений:

  • 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"
   }
  }
 ]
}

Оптимизация производительности

Использование ETags

ETags , являющиеся стандартной частью протокола HTTP , позволяют приложениям ссылаться на конкретную версию определенного ресурса API. Ресурсом может быть весь фид или отдельный элемент в этом фиде. Эта функциональность поддерживает следующие варианты использования:

  • Кэширование и условное получение — ваше приложение может кэшировать ресурсы API и их ETag. Затем, когда ваше приложение снова запрашивает сохраненный ресурс, оно указывает связанный с этим ресурсом ETag. Если ресурс изменился, API возвращает измененный ресурс и ETag, связанный с этой версией ресурса. Если ресурс не изменился, API возвращает HTTP-ответ 304 ( Not Modified ), который указывает на то, что ресурс не изменился. Ваше приложение может уменьшить задержку и потребление полосы пропускания, предоставляя кэшированные ресурсы таким образом.

    Клиентские библиотеки для API Google различаются по поддержке ETags. Например, библиотека JavaScript поддерживает ETags через белый список разрешенных заголовков запроса, который включает If-Match и If-None-Match . Белый список позволяет осуществлять обычное кэширование в браузере, так что если ETag ресурса не изменился, ресурс может быть предоставлен из кэша браузера. Клиент на Objective-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)