Youtube data api: добавьте функциональность YouTube в свое приложение.

Опубликовано 10 March 2020

Добавьте функциональность YouTube на свой сайт.


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


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


Вступление


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


Прежде чем вы начнете.


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


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


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


a. Перейдите в консоль API и выберите проект, который вы только что зарегистрировали.

b. Посетите страницу Enabled APIs. В списке 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 идентифицирует видеоресурс, который, в свою очередь, содержит полную информацию о видео. В качестве другого примера, результат поиска содержит свойство videoIdplaylistId или channelId, которое идентифицирует конкретное видео, список воспроизведения или ресурс канала.


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


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


list
Получает (GET) список из нуля или более ресурсов.
insert
Создает (POST) новый ресурс.
update
Изменяет (PUT) существующий ресурс, чтобы отразить данные в вашем запросе.
delete
Удаляет (DELETE) определенный ресурс.

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


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


Youtube data api: добавьте функциональность YouTube в свое приложение.

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


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


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

Примечание. Если вы достигнете предела квоты, вы можете запросить дополнительную квоту на вкладке «Квоты» в консоли разработчика.

Обратите внимание, что проекты, в которых API данных YouTube был включен до 20 апреля 2016 года, имеют другую квоту по умолчанию для этого API.


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


Google рассчитывает использование вашей квоты, назначая стоимость для каждого запроса, но стоимость не является одинаковой для каждого запроса. Два основных фактора влияют на стоимость квоты запроса:


1. Разные виды операций имеют разные квоты.

  • Простая операция чтения, которая извлекает только идентификатор каждого возвращенного ресурса, стоит приблизительно 1 единицу.
  • Операция записи имеет стоимость около 50 единиц.
  • Стоимость загрузки видео составляет около 1600 единиц.

2. Операции чтения и записи используют различное количество квоты в зависимости от количества частей ресурса, которые получает каждый запрос. Обратите внимание, что операции insert и update записывают данные, а также возвращают ресурс. Так, например, вставка списка воспроизведения имеет стоимость квоты в 50 единиц для операции записи плюс стоимость возвращенного ресурса списка воспроизведения.


Как обсуждалось в следующем разделе, каждый ресурс API разделен на части. Например, ресурс списка воспроизведения playlist состоит из двух частей: фрагмента snippet и состояния status, в то время как ресурс канала channel состоит из шести частей, а видео ресурс video состоит из 10. Каждая часть содержит группу связанных свойств, и группы разработаны так, что вашему приложению требуется только получить типы данных, которые он фактически использует.


Запрос API, который возвращает данные ресурса, должен указывать части ресурса, которые запрос получает. Затем каждая часть добавляет примерно 2 единицы к стоимости квоты запроса. Таким образом, запрос videos.list, который извлекает только часть фрагмента snippet для каждого видео, может стоить 3 единицы. Однако запрос videos.list, который извлекает все части для каждого ресурса, может стоить около 21 единицы квоты.


Имея в виду эти правила, вы можете оценить количество запросов на чтение, запись или загрузку, которые ваше приложение может отправлять в день, не превышая квоту. Например, если у вас есть дневная квота в 1 000 000 единиц, ваше приложение может иметь следующие приблизительные ограничения:

  • 200 000 операций чтения, каждая из которых получает две части ресурса.
  • 10 000 операций записи и 90 000 дополнительных операций чтения, каждая из которых получает две части ресурса.
  • 400 загрузок видео, 1500 операций записи и 50000 операций чтения, каждая из которых извлекает две части ресурса.

Важное замечание. Извлечение только тех частей ресурса, в которых нуждается ваше приложение, сохраняет дневную квоту и повышает эффективность всей системы.


Частичные ресурсы


API позволяет и фактически требует извлечения частичных ресурсов, чтобы приложения избегали передачи, анализа и хранения ненужных данных. Этот подход также обеспечивает более эффективное использование API, ресурсов сети и памяти.


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


  • Параметр part определяет группы свойств, которые должны быть возвращены для ресурса.
  • Параметр fields фильтрует ответ API, чтобы возвращать только определенные свойства в запрошенных частях ресурса.


Как использовать параметр part


Параметр part является обязательным параметром для любого запроса API, который извлекает или возвращает ресурс. Параметр определяет одно или несколько свойств ресурса верхнего (не вложенного) ресурса, которые должны быть включены в ответ API. Например, видеоресурс video состоит из следующих частей:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

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


  • Это позволяет вам управлять использованием квоты API. Если вы увеличиваете количество частей, которые вы получаете в ответах API, ваше использование API соответственно увеличивается, а доступная квота уменьшается.
  • Это уменьшает задержку, не позволяя серверу API тратить время на поиск полей метаданных, которые ваше приложение не использует.
  • Это уменьшает использование полосы пропускания за счет уменьшения (или устранения) количества ненужных данных, которые может извлечь ваше приложение.

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


Как использовать параметр fields


Параметр fields фильтрует ответ API, который содержит только часть ресурса part. Параметры fields позволяют вам использовать свойства полосы пропускания. (Параметр 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. Возвращает видео ресурс, который включает четыре части, а также свойства kind и etag.

Пример 2. Возвращает видео ресурс, который состоит из двух частей, а также свойств kind и etag.

Пример 3. Возвращает видео ресурс, который состоит из двух частей, но исключает свойства kind и etag.

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


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


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

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

Клиентская библиотека API Google для 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)