Общие сведения о YouTube Data API

Введение

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

Подготовка

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

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

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

    1. Откройте Cloud Console и выберите проект, который вы только что зарегистрировали.
    2. Откройте страницу включенных API. Убедитесь, что YouTube Data API есть в списке включенных API. Если нет, откройте библиотеку API и включите его.

  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. Подписчики получают уведомления о новых видео на канале и о действиях других пользователей, например о загрузке видео, оценке или комментарии.
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, по умолчанию имеют квоту в 100 вызовов search.list,100 вызовов videos.insert и 10 000 единиц в день для всех остальных конечных точек. Квота по умолчанию, которая может быть изменена, помогает нам оптимизировать распределение квот и масштабировать инфраструктуру так, чтобы это было удобно пользователям API. Данные об использовании квоты представлены на странице Quotas (Квоты) в API Console.

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

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

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

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

В таблице Стоимость квоты для запросов к 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 должно быть закодировано. В целях наглядности в приведенных здесь примерах кодировка не используется.

Примеры частичных запросов

В примерах ниже показано, как использовать параметры part и fields, чтобы ответы API содержали только те данные, которые используются в вашем приложении.

  1. В примере 1 возвращается видеоресурс, который включает четыре части, а также свойства kind и etag.
  2. Во втором примере возвращается ресурс video, который включает две части, а также свойства kind и etag.
  3. В примере 3 возвращается ресурс video, который включает две части, но не содержит свойства 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, что позволяет использовать ETag в контексте обычного кеширования в браузере.

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

Вы также можете уменьшить объем ответов API, включив сжатие GZIP. На распаковку ответов API требуется дополнительное процессорное время, однако экономия сетевых ресурсов того стоит.

Чтобы получить ответ в архиве GZIP, необходимо:

  • Установите для заголовка HTTP-запроса Accept-Encoding значение gzip.
  • Добавьте в агент пользователя строку gzip.

Пример правильного оформления заголовков HTTP, которое обеспечивает сжатие GZIP, приведен ниже.

Accept-Encoding: gzip
User-Agent: my program (gzip)