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

Введение

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

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

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

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

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

    1. Перейдите в консоль API и выберите проект, который вы только что зарегистрировали.
    2. Посетите страницу «Включенные API» . Убедитесь, что в списке API для API данных YouTube 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 отличаются поддержкой 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)