Обзор 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.

Обратите внимание, что во многих случаях ресурс содержит ссылки на другие ресурсы. Например, свойство snippet.resourceId.videoId ресурса playlistItem идентифицирует видеоресурс, который, в свою очередь, содержит полную информацию о видео. Другой пример: результат поиска содержит свойство videoId , playlistId или channelId , которое идентифицирует конкретное видео, список воспроизведения или ресурс канала.

Поддерживаемые операции

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

В настоящее время API поддерживает методы для перечисления каждого из поддерживаемых типов ресурсов, а также поддерживает операции записи для многих ресурсов.

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

Использование квоты

YouTube Data API использует квоту, чтобы гарантировать, что разработчики используют службу по назначению и не создают приложения, которые несправедливо снижают качество услуги или ограничивают доступ для других. Все запросы API, включая недействительные запросы, включают стоимость квоты как минимум в один балл. Квоту, доступную вашему приложению, можно найти в API Console .

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

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

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

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 ресурса.

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

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

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

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

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

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