Этот документ предназначен для программистов, создающих клиентские приложения, взаимодействующие с YouTube. Этот документ дополняет информацию протокола руководства разработчика, а также руководства разработчиков для языков Java и PHP.
Этот документ приводит различные типы каналов, которые можно получить с помощью API данных YouTube. В нем также приведены схемы, поясняющие, как переходить между различными каналами, например, на схемах показано, что канал плейлистов пользователя содержит URL, ссылающиеся на отдельные плейлисты и такие данные, как профиль пользователя. Схемы указывают, как перейти с одного канала на другой. Наконец, этот документ определяет параметры, использующиеся в запроса API данных YouTube, а также теги XML, возвращаемые в ответе API. Для разработчиков на Java и PHP, теги XML могут соответствовать непосредственно свойству VideoEntry, ProfileEntry или другого типа объектов.
API данных YouTube предоставляет различные просмотры, или проекции, данных, доступных в API. Руководство разработчика и примеры в этом документе используют проекцию api, которая поддерживает все теги, определенные в разделе элементов XML этого документа.
Большинство разработчиков, использующих эту документацию, будут использовать проекцию api. Но если вы разрабатываете приложения для мобильных устройств, вы можете заменить во всех примерах запросов в документации API "api" на "mobile". Также, если вы предпочитаете использовать проекцию base, хорошо подходящую для программ чтения каналов, можно заменить "api" на "base" во всех примерах запросов в документации API.
В следующей таблице описаны поддерживаемые значения проекций.
| Название проекции | Описание |
|---|---|
api |
Эта проекция выдает каналы, поддерживающие все элементы XML, определенные в этом документе, в том числе все теги YouTube и схемы Media RSS. Все свойства содержат обычный текст, а не HTML. |
base |
Эта проекция выдает базовые каналы Atom без дополнительных элементов. Ее свойства <atom:summary> и <atom:content> содержат закодированный HTML. |
mobile |
Эта проекция поддерживает большинство элементов XML, определенных в этом документе; ее следует использовать разработчикам приложений для мобильных устройств. |
Из API данных YouTube можно получить следующие типы каналов:
API позволяет получать все эти каналы без аутентификации. В некоторых случаях, однако, аутентифицированный запрос получит больше дополнительной информации. Например, если вы подаете аутентифицированный запрос на список видео, добавленных самим пользователем, канал будет содержать частные видео, а также отклоненные и ожидающие обработки видео. Частные, ожидающие обработки и отклоненные видео не появятся в ответе на неаутентифицированный запрос API или запрос видео, добавленных кем-либо помимо аутентифицированного пользователя.
Для добавления или обновления видео, плейлистов, подписок, оценок, комментариев или других элементов, необходимо аутентифицировать все запросы, включая запросы GET, используя ключ разработчика и аутентификацию AuthSub или ClientLogin.
Каналы видео возвращают набор записей видео. В свою очередь, каждая запись видео содержит сведения об определенном видео в наборе результатов канала видео. API данных YouTube позволяет получать следующие типы каналов видео:
API возвращает канал видео в ответ на запрос поиска видео. Канал видео содержит до 999 записей. Для получения результатов поиска, отправьте запрос API на следующий URL:
http://gdata.youtube.com/feeds/projection/videos
Запросы поиска могут использовать любой из параметров запроса, определенных в разделе Справка по параметрам запросов этого документа, кроме параметра time. Например, этот URL запрашивает все видео, относящиеся к критерию поиска "skateboarding dog", начинающиеся с 21 результата поиска и возвращает 10 результатов:
| 
http://gdata.youtube.com/feeds/api/videos?
vq=skateboarding+dog
&start-index=21
&max-results=10
Канал похожих видео содержит список видео, похожих на другое видео. YouTube использует алгоритм, отбирающий похожие видео.
Каждое видео в ответе API содержит набор тегов <link>. Тег <link>, имеющий значение http://gdata.youtube.com/schemas/2007/#video.related атрибута rel, определяет URL для получения других видео, похожих на это. (Атрибут href тега <link> определяет URL.)
<link rel="http://gdata.youtube.com/schemas/2007#video.related"
type="application/atom+xml"
href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/>
Канал похожих видео содержит до 100 записей.
Канал видеоответов содержит видео, обозначенные как ответы на другое видео. Видео может быть обозначено как ответ только на одно видео, а некоторые видео могут не иметь видеоответов.
Каждое видео в ответе API содержит набор тегов <link>. Тег <link>, имеющий значение http://gdata.youtube.com/schemas/2007/#video.responses атрибута rel, определяет URL для получения видеоответов на это видео. (Атрибут <link> тега href определяет URL, как в следующем примере.)
<link rel="http://gdata.youtube.com/schemas/2007#video.responses"
type="application/atom+xml"
href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/>
Стандартные каналы содержат списки видео, которые либо отражают поведение пользователей, как каналы с лидерами просмотров или лучшими оценками, либо отобранные сотрудниками YouTube, как каналы "в центре внимания" и с мобильными видео. Многие из них можно видеть во вкладке Видео на веб-сайте YouTube.
Для получения стандартного канала отправьте запрос HTTP GET на URL, связанный с этим каналом. В таблице перечислены URL, связанные со стандартными каналами.
| Название | Идентификатор канала | Пример |
|---|---|---|
| Лучшие оценки | top_rated | http://gdata.youtube.com/feeds/api/standardfeeds/top_rated |
| Лидеры в избранном | top_favorites | http://gdata.youtube.com/feeds/api/standardfeeds/top_favorites |
| Лидеры просмотров | most_viewed | http://gdata.youtube.com/feeds/api/standardfeeds/most_viewed |
| Последние добавления | most_recent | http://gdata.youtube.com/feeds/api/standardfeeds/most_recent |
| Лидеры обсуждений | most_discussed | http://gdata.youtube.com/feeds/api/standardfeeds/most_discussed |
| Лидеры по ссылкам | most_linked | http://gdata.youtube.com/feeds/api/standardfeeds/most_linked |
| Лидеры по ответам | most_responded | http://gdata.youtube.com/feeds/api/standardfeeds/most_responded |
| В центре внимания | recently_featured | http://gdata.youtube.com/feeds/api/standardfeeds/recently_featured |
| Видео для мобильных телефонов | watch_on_mobile | http://gdata.youtube.com/feeds/api/standardfeeds/watch_on_mobile |
API позволяет получать стандартные каналы для определенного региона путем добавления в URL стандартного канала идентификатор региона. В этом URL показан формат URL, который нужно использовать для получения стандартных каналов для определенного региона:
http://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID
Например, получить видео с лучшими оценками в Японии можно, отправив запрос HTTP GET на следующий URL:
http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated
Note: Нет региональных версий стандартного канала watch_on_mobile.
В следующей таблице перечислены страны и regionID для каждой из стран, для которых API данных YouTube поддерживает местные каналы.
| Страна | Идентификатор региона |
|---|---|
| Австралия | AU |
| Бразилия | BR |
| Канада | CA |
| Франция | FR |
| Германия | DE |
| Великобритания | GB |
| Голландия | NL |
| Гонконг | HK |
| Ирландия | IE |
| Италия | IT |
| Япония | JP |
| Мексика | MX |
| Новая Зеландия | NZ |
| Польша | PL |
| Россия | RU |
| Южная Корея | KR |
| Испания | ES |
| Тайвань | TW |
| США | US |
Все стандартные каналы поддерживают параметр запросов time, позволяющий ограничить канал результатами только прошедшего дня, недели или месяца. Например, получить видео с лучшими оценками за прошедший день можно, отправив запрос HTTP GET на следующий URL:
http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?time=today
Канал избранных видео получает список видео, которые определенный пользователь обозначил как избранные. На веб-сайте YouTube пользователь может смотреть и изменять список избранных видео на странице своего аккаунта. Избранные видео также доступны для просмотра другими пользователями YouTube.
Для запроса канала с избранными видео вошедшего в систему пользователя, отправьте запрос HTTP GET на следующий URL. Note: В этом запросе необходимо включить идентификатор аутентификации в заголовок HTTP запроса Authorization. Идентификатор аутентификации позволяет YouTube определить пользователя.
http://gdata.youtube.com/feeds/api/users/default/favorites
Для запроса канала с избранными видео другого пользователя, отправьте запрос HTTP GET на следующий URL. Этот запрос не требует аутентификации.
http://gdata.youtube.com/feeds/api/users/username/favorites
В URL выше нужно заменить текст именем пользователя YouTube.username
Канал избранных возвращает до 50 записей. Мы настоятельно рекомендуем разделять канал на страницы с помощью параметров start-index и max-results для оптимизации размера и скорости получения ответа. Рекомендуемое значение max-results – 10, что дает ответ, содержащий приблизительно 60 Кб данных.
Канал плейлистов содержит информацию о наборе 200 или менее видео, которые можно просматривать подряд. Пользователь может смотреть и изменять список плейлистов на странице своего аккаунта. Плейлисты также доступны для просмотра другими пользователями YouTube. Кроме того, пользователи могут изменять отдельный плейлист, добавляя или удаляя видео.
Плейлист может быть доступен для всех или для избранных. API позволяет получать плейлисты для всех без аутентификации или с ней. Однако плейлист для избранных можно получить только для пользователя, корректно аутентифициорванного и имеющего полномочия просматривать плейлист.
Перед получением канала плейлиста, сперва нужно получить канал плейлистов пользователя, содержащий список плейлистов, созданных этим пользователем. В канале плейлистов пользователя каждая запись описывает один плейлист. (При этом канал плейлиста описывает отдельные видео, составляющие один плейлист.) Каждая запись в канале плейлистов пользователя содержит тег <gd:feedLink>, определяющий URL, позволяющий получить канал этого плейлиста.
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist'
href='http://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID'/>
Note: Фактический URL вместо термина PLAYLIST_ID содержит идентификатор, однозначно определяющий плейлист.
Канал плейлистов пользователя содержит список плейлистов, созданных этим пользователем. Если вы запрашиваете канал плейлистов аутентифицированного в данный момент пользователя, канал будет содержать как плейлисты для всех, так и для избранных. Однако если вы отправляете неаутентифицированный запрос или запрашиваете плейлисты, созданные не аутентифицированным в настоящий момент пользователем, канал будет содержит только плейлисты для всех.
В канале плейлистов, каждая entry содержит информацию об отдельном плейлисте, включая его название, описание и автора. Тег <gd:feedLink> в записи определяет URL, позволяющий получить канал плейлиста, указывающий информацию о видео в плейлисте.
Для запроса канала с плейлистами вошедшего в систему пользователя, отправьте запрос HTTP GET на следующий URL. Note: В этом запросе необходимо включить идентификатор аутентификации в заголовок HTTP запроса Authorization. Идентификатор аутентификации позволяет YouTube определить пользователя.
http://gdata.youtube.com/feeds/api/users/default/playlists
Для запроса канала с плейлистами другого пользователя, отправьте запрос HTTP GET на следующий URL. Этот запрос не требует аутентификации.
http://gdata.youtube.com/feeds/api/users/username/playlists
В URL выше нужно заменить текст username именем пользователя YouTube.
Канал подписок пользователя содержит список каналов, списков избранных видео и критериев поиска, на которые подписался пользователь.
Для запроса канала с подписками вошедшего в систему пользователя, отправьте запрос HTTP GET на следующий URL. Note: В этом запросе необходимо включить идентификатор аутентификации в заголовок HTTP запроса Authorization. Идентификатор аутентификации позволяет YouTube определить пользователя.
http://gdata.youtube.com/feeds/api/users/default/subscriptions
Для запроса канала с подписками другого пользователя, отправьте запрос HTTP GET на следующий URL. Этот запрос не требует аутентификации.
http://gdata.youtube.com/feeds/api/users/username/subscriptions
В URL выше нужно заменить текст username именем пользователя YouTube.
В канале подписок, каждая entry содержит сведения об одной подписке. Каждая запись содержит следующие ключевые теги:
Тег <gd:feedLink> определяет URL, позволяющий получить видео в подписке.
Для одного их тегов <category> в записи, значение атрибута scheme будет http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Атрибут term тега означает, описывает ли запись подписку на канал (term="channel"), на список избранных видео другого пользователя (term="favorites") или на видео, соответствующие определенным ключевым словам (term="query").
Если подписка – на канал или список избранных видео другого пользователя, тег <yt:username> определяет пользователя, владеющего каналом или списком избранных видео.
Если подписка – на ключевые слова, элемент <yt:queryString> будет содержать термины-критерии подписки.
Каждое видео содержит тег <gd:comments>, включающий URL, на который нужно отправлять запросы API для получения (или добавления к нему) списка комментариев к видео. В примере XML ниже показано, как этот URL выглядит в канале видео:
<feed>
<entry>
...
<media:group>
...
</media:group>
<gd:comments>
<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments'/>
</gd:comments>
</entry>
</feed>
Каждая запись в канале комментариев содержит информацию об одном комментарии. У каждого комментария есть автор, название и содержание.
Профиль пользователя содержит информацию, которую пользователь разместил на странице своего профиля YouTube.
Для запроса профиля вошедшего в систему пользователя, отправьте запрос HTTP GET на следующий URL. Note: В этом запросе необходимо включить идентификатор аутентификации в заголовок HTTP запроса Authorization. Идентификатор аутентификации позволяет YouTube определить пользователя.
http://gdata.youtube.com/feeds/api/users/default
Для запроса профиля другого пользователя, отправьте запрос HTTP GET на следующий URL. Этот запрос не требует аутентификации.
http://gdata.youtube.com/feeds/api/users/username
В URL выше нужно заменить текст username именем пользователя YouTube. В зависимости от типа ответа API YouTube, имена пользователей будут находится в теге <name> или в теге <yt:username>.
Note: Многие ответы API содержат сведения о канале ответа и список записей, но запрос на получение профиля содержит только одну запись. Поэтому корневой тег в ответе API для этого запроса – <entry>.
Канал знакомых пользователя состоит из всех знакомых указанного пользователя.
Для запроса списка знакомых вошедшего в систему пользователя, отправьте запрос HTTP GET на следующий URL. Note: В этом запросе необходимо включить идентификатор аутентификации в заголовок HTTP запроса Authorization. Идентификатор аутентификации позволяет YouTube определить пользователя.
http://gdata.youtube.com/feeds/api/users/default/contacts
Для запроса списка знакомых другого пользователя, отправьте запрос HTTP GET на следующий URL. Этот запрос не требует аутентификации.
http://gdata.youtube.com/feeds/api/users/username/contacts
В URL выше нужно заменить текст username именем пользователя YouTube.
Знакомые могут относится к категории Friends или Family.
Каждый канал и запись использует теги <link rel="relationshipID"> и элементы <gd:feedLink rel="relationshipID">, содержащие ссылки на похожие каналы и записи. В целом, тег <link> определяет связь между похожими, но не вложенными, каналами. С другой стороны, тег <gd:feedLink> определяет канал, который мог бы быть вложен в исходный ответ, но канал бы тогда стал слишком велик.
Эти теги определяют URL, позволяющие реализовать функции API, не добавляя URL в код своего приложения. Например, следующий элемент <link>, который может появится в записи видео, дает ссылку на канал, содержащий видеоответы на это видео.
<link rel="http://gdata.youtube.com/schemas/2007#video.responses"
type="application/atom+xml"
href="http://gdata.youtube.com/feeds/api/videos/UwOA8H5Vaak/responses"/>
Сходно, следующий элемент <gd:feedLink> может появится записи профиля пользователя. Этот тег определяет URL, с которого можно получить канал знакомых этого пользователя.
<gd:feedLink
rel="http://gdata.youtube.com/schemas/2007#user.contacts"
href="http://gdata.youtube.com/feeds/api/users/liz/contacts"/>
Случаи использования в Руководстве разработчика могут помочь понять, как переходить между каналами. Кроме того, схема ниже показывает взаимосвязи между каналами API данных YouTube. Сплошные стрелки обозначают элементы <link>, а пунктирные – элементы <gd:feedLink>. Синие стрелки обозначают ссылки <link rel="related">. Запись в подписке может содержать тег <gd:feedLink>, указывающий на один из нескольких типов каналов, в зависимости от типа подписки.
Последний термин в каждом кружке – это "тип" записей данных Google в данном канале. Например, канал подписок содержит записи типа "подписки", а канал "видео" содержит записи типа "видео".
В этом разделе описаны HTTP-коды ответов, возвращаемых YouTube на разные типы запросов API.
Код ответа 200 означает, что запрос HTTP GET для получения канала был успешно обработан YouTube.
Код ответа 400 указывает на неправильный запрос. Например, вы получите код ответа 400, если подадите запрос на неправильный URL или включите в него неподдерживаемый или несуществующий параметр. Содержимое ответа API пояснит причину, по которой API вернул код ответа 400.
Загрузка через браузер
200 – API возвращает код ответа 200, если метаданные видео добавлены успешно. Раздел руководства разработчика Добавление метаданных видео рассказывает об этом процессе подробнее.
301 – Когда пользователь добавляет видеофайл прямо на YouTube через форму на вашем сайте, YouTube отправляет браузеру пользователя перенаправление 301, что заставляет браузер запросить и загрузить URL, который вы указали в параметре nexturl формы добавления. (Больше сведений о форме добавления.) YouTube добавит в этому URL следующие переменные, которые нужно извлечь, чтобы обеспечить пользователю реализацию всех возможностей:
Прямая загрузка
201 – API возвращает код ответа 201, если видео успешно добавлено.
400 (неправильный запрос) – Код ответа 400 означает, что запрос имел неправильный формат или содержал некорректные данные. Например, API вернет код ответа 400, если ваш запрос содержал неверно отформатированный XML или если вы попытались подать ключевые слова, содержащие недопустимые символы.
API возвращает приведенные ниже коды ответов на запросы добавления таких элементов, как оценки, комментарии, видеоответы, жалобы, избранные видео, плейлисты, записи в плейлисты, подписки и знакомые.
201 (создано) – Код ответа 201 означает, что запрос HTTP POST для добавления оценки, комментария, видеоответа, жалобы, плейлиста, подписки или знакомого был обработан успешно.
400 (неправильный запрос) – Код ответа 400 означает, что запрос имел неправильный формат или содержал некорректные данные. Например, API вернет код ответа 400, если ваш запрос содержал неверно отформатированный XML или вы попытались подать для видео оценку "16" (оценка должна быть от 1 до 5). Содержимое ответа API пояснит причину, по которой API вернул код ответа 400.
API возвращает следующие коды ответов на запросы обновления таких элементов, как видео, плейлисты, записи в плейлистах и знакомые.
200 (ОК) – Код ответа 200 означает, что YouTube успешно выполнил запрос обновления элемента HTTP PUT.
400 (неправильный запрос) – Код ответа 400 означает, что запрос имел неправильный формат или содержал некорректные данные. Содержимое ответа API пояснит причину, по которой API вернул код ответа 400.
API возвращает приведенные ниже коды ответов на запросы удаления таких элементов, как видео, видеоответы, избранные видео, плейлисты, записи в плейлисты, подписки и знакомые.
200 (ОК) – Код ответа 200 означает, что YouTube успешно выполнил запрос удаления элемента HTTP DELETE.
401 (нет полномочий) – Код ответа 401 означает, что запрос не содержал заголовка Authorization, что формат заголовка Authorization был неверным, либо что идентификатор аутентификации, приведенный в заголовке, был недействителен.
403 (запрещено) – Код ответа 403 означает, что вы подали запрос, не имеющий подобающей аутентификации для запрошенной операции.
404 (не найдено) – Код ответа 404 означает, что вы попытались изменить несуществующий элемент. Например, вы получите код ответа 404 при попытке удалить подписку с указанием неправильного URL подписки.
API также может вернуть следующие коды ответов:
401 (нет полномочий) – Код ответа 401 означает, что запрос не содержал заголовка Authorization, что формат заголовка Authorization был неверным, либо что идентификатор аутентификации, приведенный в заголовке, был недействителен.
403 (запрещено) – Код ответа 403 означает, что вы подали запрос, не имеющий подобающей аутентификации для запрошенной операции.
500 (внутренняя ошибка) – Код ответа 500 означает, что при выполнении запроса на YouTube произошла ошибка. Запрос можно попробовать повторить позже.
501 (невозможно выполнить) – Код ответа 501 означает, что вы попытались выполнить не поддерживаемую операцию, например, получить список оценок или обновить жалобу.
503 (служба недоступна) – Код ответа 503 означает, что служба API данных YouTube недоступна. Запрос можно попробовать повторить позже.
Для поиска видео, направьте запрос HTTP GET на этот URL, добавив к запросу подходящие параметры:
http://gdata.youtube.com/feeds/api/videos
Например, запрос на следующий URL ищет второй десяток недавно добавленных видео, соответствующих критерию "football", но не соответствующих критерию "soccer":
http://gdata.youtube.com/feeds/api/videos?
vq=football+-soccer
&orderby=published
&start-index=11
&max-results=10
API данных YouTube поддерживает следующие стандартные параметры запросов данных Google.
| Название | Определение |
|---|---|
| alt | Параметр alt указывает формат возвращаемого канала. Возможные значения – atom, rss и json. Значение по умолчанию – atom; в этом документе описывается только формат ответов Atom. |
| author | Параметр author ограничивает поиск видео, добавленными определенным пользователем YouTube. Этот параметр более подробно описан в разделе "Видео, добавленное определенным пользователем". |
| max-results | Параметр max-results указывает наибольшее число результатов, которые должны быть включены в набор. Этот параметр работает вместе с параметром start-index, опредляя, какие результаты вернуть. Например, для того, чтобы получить вторую порцию в 10 результатов, т.е. результаты 11-20, параметр max-results устанавливается как 10, а параметр start-index как 11. Значение этого параметра по умолчанию для всех API данных Google – 25, а максимальное значение – 50. Для отображения списка видео мы рекомендуем выставлять значение 10 параметра max-results. |
| start-index | Параметр start-index указывает порядковый номер первого результата, включаемого в набор результатов. В этом параметре первый порядковый номер – 1, то есть первый результат – 1, второй – 2 и так далее. Параметр работает вместе с параметром max-results, определяя, какие результаты возвращать. Например, для того, чтобы получить вторую порцию в 10 результатов, т.е. результаты 11-20, параметр start-index устанавливается как 11, а параметр start-index как 10. |
Более подробные сведения о стандартных функциях API данных Google или об этих параметрах можно найти в Справке по протоколу API данных Google.
Кроме стандартных параметров запросов данных Google, API данных YouTube определяет следующие специальные параметры. Эти параметры доступны только для каналов видео и плейлиста.
| Название | Определение | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| vq | Параметр vq определяет критерий поиска. YouTube ищет все метаданные видео для видео, соответствующих критерию. Метаданные видео включают названия, ключевые слова, описания, имена пользователей-авторов и категории. Заметьте, что все пробелы, кавычки и другие знаки препинания в значении параметра должны быть переведены в URL. Для поиска точной фразы, включите ее в кавычки. Например, для поиска видео, соответствующих фразе "spy plane" (самолет-шпион), установите параметр vq на значение %22spy+plane%22. В запросе можно применять логические операторы NOT (-) и OR (|), для того, чтобы исключить видео или найти видео, связанные с одним из нескольких критериев. Например, для поиска видео, соответствующих "boating" или "sailing" (хождение на веслах или под парусами), установите параметр vq на значение boating%7Csailing. (Заметьте, что символ вертикальной черты должен быть переведен в URL.) Таким же образом, для поиска видео, соответствующих "boating" или "sailing", но не "fishing", установите параметр vq на "boating&7Csailing+-fishing". |
||||||||
| orderby | Параметр orderby указывает значение, которое используется для сортировки видео в наборе результатов. Возможные значения – relevance, published, viewCount и rating. Кроме того, можно делать запрос на результаты, наиболее подходящие для определенного языка, выставив значение параметра relevance_lang_languageCode, где languageCode – двухбуквенный код языка по ISO 639-1. (Используйте значения zh-Hans для упрощенного китайского и zh-Hant для традиционного китайского.) Также, заметьте, что будут возвращены и результаты на других языках, если он имеют высокое соответствие критерию поиска. Значение этого параметра по умолчанию для канала результатов поиска – relevance. Для канала плейлиста, сортировка по умолчанию основана на положении отдельных видео в плейлисте. Для каналов плейлистов или подписок, порядок по умолчанию – произвольный. |
||||||||
| format | Параметр format указывает, что видео должны быть в определенном формате. Запрос может указывать любой из этих форматов:
| ||||||||
| lr | Параметр lr ограничивает поиск видео, имеющими определенный язык названия, описания или ключевых слов. Возможные значения параметра lr – двухбуквенные коды языка по ISO 639-1. Используйте значения zh-Hans для упрощенного китайского и zh-Hant для традиционного китайского. Этот параметр можно использовать, запрашивая не стандартные видео каналы. | ||||||||
| racy | Параметр racy позволяет включать в результаты, помимо обычного содержания, содержание с ограниченным доступом. Возможные значения – include и exclude. По умолчанию, содержание с ограниченным доступом исключено. В каналах видео, содержащие содержание с ограниченным доступом, будут содержать дополнительный элемент <yt:racy>. | ||||||||
| restriction | Параметр restriction определяет адрес IP, который следует использовать для отбора видео, которые можно воспроизводить только в определенных странах. По умолчанию, API отбрасывает видео, которые нельзя проигрывать в стране, из которой отправляются запросы. Это ограничение основано на адресе IP вашего клиентского приложения. Для запроса видео, которые можно воспроизводить на конкретном компьютере, включите в запрос параметр ограничения и установите его значение на адрес IP этого компьютера, например, restriction=255.255.255.255.
Для запроса видео, которые можно воспроизводить в определенной стране, включите в запрос параметр ограничения и установите его значение на двухбуквенный код этой страны по ISO 3166, например, restriction=DE.
|
||||||||
| time | Параметр time доступный только для стандартных каналов top_rated, top_favorites, most_viewed, most_discussed, most_linked и most_responded ограничивает поиск видео, добавленными за определенное время. Возможные значения – today (1 день), this_week (7 дней), this_month (1 месяц) и all_time. Значение по умолчанию – all_time. |
Видео YouTube могут делиться на категории следующими способами:
Каждое видео может быть связано с одной определенной категорией YouTube, например, комедия, музыка, новости или спорт. Категория видео определяется тегом <media:category> и тегом <category>, для которого значение атрибута scheme – http://gdata.youtube.com/schemas/2007/categories.cat.
Каждое видео связано с произвольным числом ключевых слов, которые еще называют тегами. Теги видео определяются тегом <media:keywords> в запросах и ответах API. Теги ключевых слов также определяются тегами <category>, для которых атрибут scheme имеет значение http://gdata.youtube.com/schemas/2007/keywords.cat.
Каждое видео, кроме того, может быть связано с произвольным числом тегов разработчика. Можно искать видео с помощью тегов разработчика. Теги разработчика, однако, не отображаются на веб-сайте YouTube и их не следует отображать в вашем приложении. Теги разработчика для видео определяются в тегах <media:category> и <category>, для которых атрибут scheme имеет значение http://gdata.youtube.com/schemas/2007/developertags.cat.
Более подробно о присвоении тегов разработчика можно узнать в руководстве разработчика.
Для получения видео, относящихся к определенной категории или отмеченных определенными ключевыми словами или тегами разработчика, используйте следующий URL:
http://gdata.youtube.com/feeds/api/videos/-/category_or_tag
Дефис в URL – стандартное обозначение API данных Google, означающее, что оставшаяся часть URL состоит из одного или нескольких тегов. Инструкции ниже сообщают более подробные сведения о запросе видео, связанных с определенными категориями или тегами:
Если запрос содержит категорию и одно или несколько ключевых слов, или если запрос не содержит категории, но содержит несколько ключевых слов, разделите отдельные категории и ключевые слова косой чертой. Например, для запроса видео, связанных с ключевыми словами "bass" и "fishing", используется такой URL:
http://gdata.youtube.com/feeds/api/videos/-/bass/fishing
В запросе можно применять логические операторы NOT (-) и OR (|), для того, чтобы исключить видео или найти видео, связанные с одним из нескольких ключевых слов или категорий. Например, если вы хотите отобразить видео, связанные со словами "bass" (бас, окунь) и "music" (музыка), лучше всего искать видео, связанные со словом "bass", но не связанные со словами "fish" или "fishing" (рыба или рыбалка), как в примере далее. (Поиск видео в категории "Music" и ключевым словом "bass" может исключить видео, обучающих игре на басовых инструментах.)
http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing
В следующем примере – как искать видео, связанные с бейсболом, находящиеся в категориях "Sports" (спорт) или "Howto" (обучение). Названия категорий разделены значением "%7C", означающее символ | в кодировке URL, указывающий на то, что видео должны быть в одной из двух категорий:
http://gdata.youtube.com/feeds/api/videos/-/Sports%7CHowto/baseball
Названия категорий должны быть с прописной буквы, ключевые слова – со строчной. например, такой запрос определяет видео, связанные с ключевым словом "comedy", но не находящиеся в категории "Comedy":
http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy
Если вы создаете поиски по категориям или ключевым словам автоматически, на основании информации в ответе API, задайте схему как часть названия категории, чтобы четко отличать категории YouTube от тегов ключевых слов или тегов разработчика. Следующие URL показывают, как указать схему в названии категории:
http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fcategories.cat%7DNews http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fkeywords.cat%7Ddog http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fdevelopertags.cat%7Dexample.com
Всегда указывайте схему, см. выше, если вы запрашиваете видео, связанные с определенным тегом разработчика.
API данных YouTube использует теги из нескольких схем XML. Следующая таблица определяет различные схемы, используемые API, префикс пространства имен, связанный с каждой из схем и URL пространства имен для всех схем.
| Схема | Префикс пространства имен | URL схемы |
|---|---|---|
| Формат синдикации Atom | [нет] – это пространство имен по умолчанию | http://www.w3.org/2005/Atom |
| Схема Open Search | openSearch | http://a9.com/-/spec/opensearchrss/1.0/ |
| Media RSS | media | http://search.yahoo.com/mrss/ |
| Схема XML YouTube | yt | http://gdata.youtube.com/schemas/2007 |
| Схема данных Google | gd | http://schemas.google.com/g/2005 |
| GeoRSS | georss | http://www.georss.org/georss |
| Язык географической разметки (Geography Markup Language) | gml | http://www.opengis.net/gml |
| Протокол публикации Atom | app | http://www.w3.org/2007/app |
В следующих таблицах определены теги XML, появляющиеся в запросах и ответах API данных YouTube, для каждой из этих схем. Каждая таблица содержит определение одного тега. Теги перечислены в алфавитном порядке для каждой схемы.
Рядом с некоторыми дочерними тегами в определениях могут быть определенные символы. Эти символы и их значения таковы:
Тег <author> содержит информацию о пользователе YouTube, владеющем видеосодержанием, подпиской, списком избранных видео, знакомым или другим элементом.
<author>
Тег <category> указывает категорию, к которой относится видео.
Если тег <category> является подтегом <feed> или <entry>, он может определять тип элемента, описанного в каждой из записей в канале. Значение атрибута scheme – http://schemas.google.com/g/2005#kind, а значение атрибута term указывает, описывают ли записи в канале видео, ссылки плейлистов, подписки, знакомых или другие типы элементов.
Когда тег <category> является подтегом <entry> и запись описывает видео, тег может также указывать, с каким ключевым словом или категорией связано это видео. В этом случае атрибут scheme означает, относится ли значение атрибута term к ключевому слову или же к категории.
В запросе для добавления подписки, тег <category> означает, подписывается ли пользователь на канал, список избранного другим пользователем или же на ключевое слово:
Если пользователь подписывается на канал, значение атрибута term тега <category> должно быть channel.
Если пользователь подписывается на список избранного другого пользователя, значение атрибута <category> тега term должно быть favorites.
Если пользователь подписывается на ключевое слово, значение атрибута term тега <category> должно быть query.
В запросе добавления или удаления знакомого, тег
Если знакомый – член семьи, значение атрибута term тега <category> должно быть Family.
Если знакомый – друг, значение атрибута term тега <category> должно быть Friends.
| Название | Формат | Описание |
|---|---|---|
| scheme | Сложный | Атрибут scheme указывает URL, определяющий схему категоризации, связанную с меткой.
|
| term | Сложный | Атрибут term определяет тип элемента, содержащегося в записи канала, или категории или ключевого слова, связанных с видео.
|
| label | Сложный | Атрибут label указывает переведенное в элемент название категории YouTube, к которой относится видео. Атрибут включается только в теги <category>, относящиеся к категории (но не к ключевому слову или типу элемента). |
<category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='channel'/>
Тег <content> содержит текст комментария или описания видео или плейлиста. Если тег <content> оказывается в записи видео или плейлиста, он может содержать то же описание, что и тег <media:description>.
Тег <content> необходим в запросах добавления комментария.
<content type="text">Video comments are cool.</content>
Тег <entry> включает информацию о видео, плейлисте, подписке, знакомом или другом элементе. Тег <entry> – корневой во всех запросах добавления (POST) или обновления (PUT) API данных YouTube.
<entry>
В записи видео или плейлиста: id, published, updated, category*, title?, content?, link*, author?, media:group?, yt:description? (этот тег используется только в записи плейлиста), yt:position? (этот тег используется только в записи плейлиста), yt:statistics?, gd:comments?, gd:rating?, location?, yt:recorded?, georss:where?, app:control?
В канале комментариев: id, published, updated, category*, title?, content?, link*, author?
В канале плейлистов: id, published, updated, category*, title?, content?, link*, author?, yt:description?, gd:feedLink
В канале подписок: id, published, updated, category*, title?, content?, link*, author?, yt:username?, yt:queryString?, gd:feedLink
В записи профиля: id, published, updated, category*, title?, content?, link*, author?, yt:age?, yt:books?, yt:company?, firstName?, yt:gender?, yt:hobbies?, lastName?, yt:location?, yt:movies?, yt:music?, yt:occupation?, yt:school?, yt:username?, yt:statistics?, media:thumbnail?, gd:feedLink*
Добавление избранных видео: id
Добавление и обновление плейлистов: title, yt:description, yt:private
Добавление и обновление записей плейлистов: title, yt:description, yt:position
Добавление подписок: category, yt:username, yt:queryString
Добавление и обновление знакомых: category, yt:username
Добавление комментариев: content
Добавление видеоответов: id
Добавление оценок: gd:rating
Добавление жалоб: yt:description
Тег <feed> – корневой для некоторых каналов API данных YouTube, включая каналы видео, подписки, плейлиста, избранных видео и знакомых. Канал содержит набор элементов <entry>, каждый из которых включает сведения об одном видео, плейлисте, подписке или другом элементе.
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'>
id, updated, category*, title, logo?, link*, author?, generator, openSearch:itemsPerPage?, openSearch:startIndex?, openSearch:totalResults?, entry+
Тег <generator> определяет программное обеспечение, создавшее канал. Это информация может использоваться для отладки.
| Название | Формат | Описание |
|---|---|---|
| version | Сложный | Атрибут version указывает версию программы, создавшей канал. |
| uri | Сложный | Атрибут uri указывает URI, относящийся к программе создания канала. |
<generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator>
Тег <id> указывает URI, постоянно и однозначно определяющий канал или запись видео.
<id>http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/5c56f45db338111c</id>
Тег <link> содержит ссылку IRI (интернационализированный идентификатор ресурса), относящуюся к каналу или записи в канале.
| Название | Формат | Описание |
|---|---|---|
| rel | Сложный | Атрибут rel определяет, как URI, указанный в атрибуте href, относится к текущему набору результатов:
|
| type | Сложный | Атрибут type указывает тип мультимедиа ресурса в связанном URL. Ссылки в ответах API данных YouTube обычно указывают на страницу HTML или другой ответ API (канал Atom). Поэтому обычно атрибут type имеет значения text/html и application/atom+xml. |
| href | Сложный | Атрибут href указывает URI, определяющий ресурс, указанный в теге <link>. |
<link rel='http://gdata.youtube.com/schemas/2007#video.related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/AlPqL7IUT6M/related'/>
Тег <logo> указывает на изображение, представляющее канал. Логотип канала API данных YouTube – логотип YouTube.
<logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
Тег <name> указывает имя пользователя YouTube автора.
<name>andyland74</name>
Тег <published> указывает время создания этой записи в канале.
<published>2007-10-15T15:39:34.000-07:00</published>
Тег <title> дает удобочитаемое название канала или записи в канале. Этот тег нужен для добавления плейлистов и может применяться дополнительно для добавления или обновления записей в плейлистах.
В запросе добавления или обновления плейлиста, тег <title> указывает название плейлиста.
В запросе добавления или обновления записи в плейлисте, тег <title> указывает пользовательское название, которое может отображаться в плейлисте вместо исходного названия видео. Если пользователь не вводит собственного названия, YouTube отображает в плейлисте исходное название видео.
<title type='text'>andyland74's Subscriptions</title>
Тег <updated> указывает время последнего обновления канала или записи в канале.
<updated>2007-10-15T15:39:34.000-07:00</updated>
Тег <uri> содержит URL, относящийся к author.
<uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
Тег <openSearch:itemsPerPage> указывает, сколько записей в ответе API.
<openSearch:itemsPerPage>25</openSearch:itemsPerPage>
Тег <openSearch:startIndex> определяет номер (начинается с единицы) первого элемента, возвращаемого в канале.
<openSearch:startIndex>1</openSearch:startIndex>
Тег <openSearch:totalResults> определяет количество элементов в наборе результатов в канале. Заметьте, что это значение приблизительное и может не отражать точного значения. Это значение не следует использовать для создания ссылок перелистывания страниц. Определять, показывать ли ссылки для перехода между страницами, следует с помощью тегов <link rel="next"> и <link rel="prev">:
<openSearch:totalResults>36</openSearch:totalResults>
Тег <yt:age> указывает возраст пользователя, который рассчитывается на основании даты рождения, приведенной в профиле пользователя YouTube. Тег <yt:age> встречается в канале профиля пользователя.
<yt:age>33</yt:age>
Тег <yt:books> определяет любимые книги пользователя, указанные в профиле пользователя YouTube.
<yt:books>Catch-22</yt:books>
Тег <yt:company> определяет компанию, в которой работает пользователь, указанную в профиле пользователя YouTube.
<yt:company>Google</yt:company>
Тег <yt:description> содержит описание, которое пользователь ввел для плейлиста, собственное описание видео, которое пользователь ввел в плейлисте, или текст жалобы.
<yt:description>My new playlist description</yt:description>
Тег <yt:duration> дает длину видео в секундах.
| Название | Формат | Описание |
|---|---|---|
| seconds | Сложный | Атрибут seconds дает длину видео в секундах. |
<yt:duration seconds='344'/>
Тег <yt:firstName> указывает имя этого пользователя.
<yt:firstName>John</yt:firstName>
Тег <yt:gender> определяет пол пользователя, согласно профилю пользователя YouTube.
<yt:gender>m</yt:gender>
Тег <yt:hobbies> определяет хобби пользователя, указанные в профиле пользователя YouTube.
<yt:hobbies>Testing YouTube APIs</yt:hobbies>
Тег <yt:hometown> определяет город пользователя, указанный в профиле пользователя YouTube.
<yt:hometown>Albany, GA</yt:hometown>
Тег <yt:lastName> указывает фамилию пользователя.
<yt:lastName>Smith</yt:lastName>
В записи видео, тег <yt:location> содержит текст описания места, где было снято видео. В записи профиля пользователя, тег <yt:location> определяет место нахождения пользователя, введенное в профиле пользователя YouTube.
<yt:location>US</yt:location>
Тег <yt:movies> определяет любимые фильмы пользователя, указанные в профиле пользователя YouTube.
<yt:movies>Aqua Teen Hungerforce</yt:movies>
Тег <yt:music> определяет любимую музыку пользователя, указанную в профиле пользователя YouTube.
<yt:music>Elliott Smith, the Kooks</yt:music>
Тег <yt:noembed> указывает, что видео нельзя встраивать на другие веб-сайты. Этот тег может включаться в запросы добавления или обновления метаданных видео. По умолчанию видео, кроме видео только для избранных, можно встраивать на другие сайты. Если запрос не включает тега <yt:noembed> или тега <yt:private>, видео можно будет встраивать на другие веб-сайты.
<yt:noembed/>
Тег <yt:occupation> определяет занятие пользователя, указанное в профиле пользователя YouTube.
<yt:occupation>Technical writer</yt:occupation>
Тег <yt:position> указывает порядок, в котором видео отображаются в плейлисте.
<yt:position>4</yt:position>
Тег <yt:private> означает, что видео – только для избранных, то есть оно не будет общественно-доступным на веб-сайте YouTube. Видео для избранных могут просматривать только люди, отобранные владельцем видео. Этот тег может включаться в запросы добавления или обновления метаданных видео. Этот тег не должен указывать значение. Само присутствие тега означает, что видео – для избранных. Отсутствие тега означает, что видео будет доступно всем пользователям YouTube. По умолчанию, все видео доступны на YouTube для всех. Отсутствие тега означает, что видео будет доступно всем пользователям YouTube. (По умолчанию, видео доступны всем пользователям YouTube; для того, чтобы видео стало доступно только избранным, следует включить тег <yt:private> во все запросы добавления или обновления видео.)
<yt:private/>
Тег <yt:queryString> указывает ключевое слово (слова) или строку запроса, связанные с подпиской.
<yt:queryString>Dog skateboarding</yt:queryString>
Тег <yt:racy> указывает, содержит ли видео содержание с ограниченным доступом. Если вы запрашиваете канал видео, содержание такого характера будет включаться в него только при наличии в API запроса параметра racy.
<yt:racy/>
Тег <yt:recorded> указывает дату записи видео.
<yt:recorded>2003-08-03</yt:recorded>
Тег <yt:relationship> указывает семейное положение пользователя согласно информации, приведенной в профиле пользователя YouTube.
<yt:relationship>taken</yt:relationship>
Тег <yt:school> указывает школу, в которой учился пользователь, согласно информации, приведенной в профиле пользователя YouTube.
<yt:school>University of North Carolina</yt:school>
Тег <yt:state> содержит информацию о состоянии видео. Для тех видео, которые не добавились или были отклонены после добавления, атрибут reasonCode и значение тега помогут определить причину проблемы.
| Название | Формат | Описание |
|---|---|---|
| name | Сложный | Атрибут name указывает статус неопубликованного видео. Возможные значения – processing, rejected и failed. |
| reasonCode | Сложный | Атрибут reasonCode дает сведения о том, почему видео не добавилось или было отклонено после добавления. Тег <yt:state> не будет включать атрибут reasonCode, если значение атрибута name равно processing. Следующий список определяет возможные значения reasonCode для отклоненных или неудачных добавлений:
|
| helpUrl | Сложный | Параметр helpUrl содержит ссылку на страницу Справочного центра YouTube, которая может помочь разработчику или владельцу видео определить причину, по которой добавление было неуспешным или было отклонено. |
<yt:state name="rejected" reasonCode="tooLong" helpUrl="http://www.youtube.com/t/community_guidelines">Video is too long</yt:state>
Тег <yt:statistics> дает статистику о видео или пользователе. Тег <yt:statistics> не включается в запись видео, если значение атрибута viewCount – 0.
| Название | Формат | Описание |
|---|---|---|
| viewCount | Сложный | Если атрибут viewCount относится к видео, атрибут указывает число его просмотров. Если атрибут viewCount относится к профилю пользователя, атрибут указывает число его просмотров. |
| videoWatchCount | Сложный | Атрибут videoWatchCount указывает число видео, которые пользователь посмотрел на YouTube. Атрибут videoWatchCount используется только тогда, когда в записи профиля пользователя есть тег <yt:statistics>. |
| subscriberCount | Сложный | Атрибут subscriberCount указывает число пользователей YouTube, подписавшихся на канал определенного пользователя YouTube. Атрибут subscriberCount используется только тогда, когда в записи профиля пользователя есть тег <yt:statistics>. |
| lastWebAccess | Сложный | Атрибут lastWebAccess указывает, когда данный пользователь последний раз пользовался YouTube. |
| favoriteCount | Сложный | Атрибут favoriteCount указывает число пользователей YouTube, добавивших видео в свой список избранных. Атрибут favoriteCount используется только тогда, когда в записи видео пользователя есть тег <yt:statistics>. |
<yt:statistics viewCount='9' videoWatchCount='24' subscriberCount='1' lastWebAccess='2008-02-29T13:09:48.000-08:00'/>
Тег <yt:status> определяет состояние знакомого. Этот тег появляется только при получении знакомых аутентифицированного в настоящий момент пользователя. В следующем списке – возможные значения этого тега:
<yt:status>accepted</yt:status>
Тег <yt:username> указывает имя пользователя YouTube. В канале подписок или запросе добавления подписки, тег <yt:username> определяет владельца канала YouTube или список избранных, на который происходит подписка. В записи профиля, тег <yt:username> определяет пользователя, связанного с профилем. В записи знакомого пользователя, тег <yt:username> определяет знакомого вошедшего в систему пользователя.
<yt:username>andyland74</yt:username>
Тег <media:category> определяет жанр или тег разработчика, описывающий видео. Раздел Список категорий добавляемых видео определяет категории видео YouTube, которые можно связать с видео. Каждое видео можно отнести к одной из категорий в этом списке.
Кроме того, всякое видео можно связать с одной или несколькими собственными категориями (ключевыми словами), используя схему категорий http://gdata.youtube.com/schemas/2007/developertags.cat. Более подробные сведения о тегах разработчика можно найти в разделе Присоединение тегов разработчика протокола.
| Название | Формат | Описание |
|---|---|---|
| label | Сложный | Атрибут label указывает переведенное в элемент название категории YouTube, к которой относится видео. |
| scheme | Сложный | Атрибут scheme указывает URL, определяющий схему категоризации, связанную с меткой. |
<media:category label='Sports' scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Sports</media:category>
Тег <media:content> дает URL и другую информацию о видео.
| Название | Формат | Описание |
|---|---|---|
| url | Сложный | Атрибут url указывает URL объекта мультимедиа. |
| type | Сложный | Атрибут type указывает тип MIME объекта мультимедиа. |
| isDefault | Сложный | Атрибут isDefault означает, указывает ли соответствующий тег <media:content> источник мультимедиа группы мультимедиа по умолчанию. В ответе API данных YouTube, источник мультимедиа по умолчанию – URL встраиваемого проигрывателя видео (SWF). |
| expression | Сложный | Атрибут expression указывает, представляет ли объект видео фрагмент видео, полное видео или потоковое видео в реальном времени. Соответствующие (и единственные) возможные значения этого атрибута – sample, full и nonstop. |
| duration | Сложный | Атрибут duration дает длину видео в секундах. |
| yt:format | Сложный | Атрибут yt:format указывает формат объекта видео, описанного в элементе <media:content>. В следующем списке – возможные значения этого атрибута:
|
<media:content url='http://www.youtube.com/v/8aYQ_wjmriQ' type='application/x-shockwave-flash' medium='video' isDefault='true' expression='full' duration='166' yt:format='5'/>
Тег <media:description> содержит сводку или описание видео. Это поле обязательно в запросах добавления или обновления метаданных видео. Описание должно быть составлено из предложений, а не из ключевых слов, и может отображаться в результатах поиска. Описание ограничено 5000 символами и может содержать любые символы UTF-8, кроме < и >.
| Название | Формат | Описание |
|---|---|---|
| type | Сложный | Атрибут type указывает тип текста, приведенного в значении тега. Каналы содержимого YouTube используют формат обычного текста (type=plain). |
<media:description type="plain">Granny takes crocheting to the extreme during a rodeo and while surfing.</media:description>
Тег <media:group> включает метаданные о видео.
<media:group>
media:title, media:description, media:keywords, media:category, media:content, media:player, media:thumbnail, yt:duration?, yt:private?, yt:noembed?
Тег <media:keywords> содержит список слов или фраз, связанных с видео, разделенных запятыми. Для каждого видео в канале необходимо дать хотя бы одно ключевое слово. Это поле ограничено 120 символами и может содержать любые символы UTF-8, кроме < и <. Кроме того, ключевые слова не могут быть длиннее 25 символов.
| Название | Формат | Описание |
|---|---|---|
| scheme | Текст | Атрибут scheme указывает URL, определяющий схему категоризации, связанную с меткой.
|
<media:keywords>rodeo, surfing, crochet</media:keywords>
Тег <media:player> указывает URL, по которому полноразмерное видео доступно в проигрывателе, работающем в браузере. В ответе API данных YouTube, тег <media:player> указывает URL страницы веб-сайта YouTube, на которой воспроизводится видео.
| Название | Формат | Описание |
|---|---|---|
| url | Сложный | Атрибут url определяет URL, использующий проигрыватель видео для отображения видео в окне браузера. |
<media:player url='http://www.youtube.com/watch?v=8aYQ_wjmriQ'/>
Тег <media:thumbnail> указывает расположение изображения, которое можно использовать для представления видео в результатах поиска. Канал видео может ссылаться на несколько таких эскизов, которые могут иметь несколько вариантов размеров. Можно выбрать размер эскиза, наиболее подходящий для вашего пользовательского интерфейса.
| Название | Формат | Описание |
|---|---|---|
| url | Сложный | Атрибут url указывает URL эскиза. |
| height | Сложный | Атрибут height указывает высоту эскиза. |
| width | Сложный | Атрибут width указывает ширину эскиза. |
| time | Сложный | Атрибут time указывает время, в которое кадр эскиза появляется в видео. Значение атрибута выражается в Normal Play Time (нормальное время воспроизведения) (NTP) DSM-CC, как в RTSP. |
<media:thumbnail url='http://img.youtube.com/vi/8aYQ_wjmriQ/2.jpg' height='97' width='130' time='00:01:23'/>
Тег <media:title> определяет название видео. Это поле ограничено 60 символами и может содержать любые символы UTF-8, кроме < и >.
| Название | Формат | Описание |
|---|---|---|
| type | Сложный | Атрибут type указывает тип текста, приведенного в значении тега. Каналы содержимого YouTube используют формат обычного текста (type=plain). |
<media:title type="plain">Extreme crocheting in high surf, rodeo</media:title>
Тег <gd:comments> содержит ссылку на канал комментариев к видео.
<gd:comments>
Тег <gd:feedLink> указывает логически вложенный канал. Например, канал комментариев логически вложен в запись видео. Сходным образом, канал одного плейлиста логически вложен в запись плейлиста в канале плейлистов пользователя.
| Название | Формат | Описание |
|---|---|---|
| rel | Сложный | Атрибут rel определяет, как URI, указанный в атрибуте href, относится к текущему набору результатов:
|
| href | Сложный | Атрибут href указывает URI, определяющий ресурс, указанный в теге <link>. |
| gd:countHint | Сложный | gd:countHint указывает количество записей в похожем канале. Например, если тег <gd:feedLink> указывает ссылку на канал комментариев к видео, атрибут gd:countHint указвывает, сколько комментариев есть к этому видео. |
<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/8aYQ_wjmxiQ/comments' countHint='0'/>
Тег <gd:rating> указывает оценку, присваиваемую видео (в запросе добавления оценки) или текущую среднюю оценку видео на основе объединенных оценок пользователей YouTube.
| Название | Формат | Описание |
|---|---|---|
| min | Сложный | Атрибут min указывает минимальную оценку, которую можно присвоить видео. Это значение должно быть 1. |
| max | Сложный | Атрибут max указывает максимальную оценку, которую можно присвоить видео. Это значение должно быть 5. |
| numRaters | Сложный | Атрибут numRaters указывает, сколько пользователей оценило видео. Этот атрибут не используется в запросе добавления оценки. |
| average | Сложный | Атрибут average указывает среднюю оценку видео. Этот атрибут не используется в запросе добавления оценки. |
<gd:rating min='1' max='5' numRaters='7773' average='4.75'/>
Тег <georss:where> содержит сведения о географическом положении. Заметьте, что если с видео уже связано географическое положение, эту информацию необходимо включать в последующие запросы обновления сведений о видео; в противном случае, информация о положении будет удалена.
<georss:where>
Тег <gml:Point> содержит сведения об определенном географическом положении. Проекция точек по умолчанию – WGS84. Географическое положение съемки видео можно указать в запросах добавления или обновления метаданных видео. Заметьте, что если с видео уже связано географическое положение, эту информацию необходимо включать в последующие запросы обновления сведений о видео; в противном случае, информация о положении будет удалена.
<gml:Point>
Тег <gml:pos> указывает координаты географической точки. Проекция точек по умолчанию – WGS84. Заметьте, что если с видео уже связано географическое положение, эту информацию необходимо включать в последующие запросы обновления сведений о видео; в противном случае, информация о положении будет удалена.
<gml:pos>47.367 8.55</gml:pos>
Тег <app:control> означает, что видео не опубликовано. Этот тег возвращается только в канале добавленного аутентифицированного в настоящий момент пользователя.
<app:control>
Тег <app:draft> указывает, находится ли видео в состоянии черновика (не опубликовано). Этот тег включается только для неопубликованных видео, поэтому он всегда имеет значение yes.
<app:draft>yes</app:draft>
Тег <response> содержит возвращаемый YouTube ответ на запрос API добавления метаданных для нового видео с помощью добавления через браузер.
<response>
Тег <token> содержится в возвращаемом YouTube ответе на запрос API добавления метаданных для нового видео с помощью добавления через браузер. На странице должен быть идентификатор, позволяющий пользователю добавлять новое видео прямо на YouTube.
<token>AEwbFAQEvf3xox...</token>
Тег <url> содержится в возвращаемом YouTube ответе на запрос API добавления метаданных для нового видео с помощью добавления через браузер. Форма на вашей веб-странице, позволяющая пользователю добавлять видеофайл на YouTube будет подаваться на этот URL.
<url>http://uploads.gdata.youtube.com/action/FormUpload/AEF3087AUD</url>
Тег <code> поясняет причину неудачи запроса API. В следующих списках определены возможные значения тега <code> на основании значения соответствующего тега <domain>:
yt:validation:
<code>required</code>
Тег <domain> определяет ошибку, которая привела к неудаче запроса API. В следующем списке приведены возможные значения тега <domain>:
Ошибка yt:validation сообщает о проблема, связанной со значением элемента XML в запросе добавления или обновления записи. Функции API, которые вставляют или обновляют видео и другие данные, могут возвращать ошибки yt:validation. Ошибки проверки обычно сопровождаются HTTP-кодом ответа 400.
Ошибка yt:quota указывает на проблему, связанную с неправильным использованием API.
Ошибка yt:authentication указывает на проблему, связанную с неправильно аутентифицированным запросом, пытающимся выполнить функцию API, требующую аутентификации. Ошибки аутентификации могут определяться HTTP-кодами ответов 401 или 403.
<domain>yt:validation</domain>
Тег <error> содержит информацию об одной ошибке, которая привела к неудаче запроса API.
<error>
Тег <errors> содержит ответ API, описывающий ошибки, которые привели к неудаче соответствующего запроса API.
<errors>
Тег <location> дает информацию об элементах запроса, которые привели к ошибке.
Если значение тега <domain> – yt:validation, то тег <location> определяет положение ошибки как Xpath, указывающий на тег XML, вызвавший ошибку запроса. Расположение Xpath указывается относительно тега <entry> в запросе.
Если значение тега <domain> – yt:quota, а значение тега <code> – too_many_recent_calls, ответ API не будет включать тега <location>.
Если значение тега <domain> – yt:quota, а тега <code> – too_many_entries, то тег <location> указывает канал, вызвавший ошибку.
Если значение тега <domain> – yt:authentication, то тег <location>, если он есть, определит, что вызвало ошибку аутентификации.
| Название | Формат | Описание |
|---|---|---|
| type | Сложный | Атрибут type обеспечивает контекст для значения тега <location>. Атрибут type может иметь любое из следующих значений.
|
<location type='xpath'>media:group/media:title/text()</location>
Документ категорий YouTube, который можно загрузить со страницы http://gdata.youtube.com/schemas/2007/categories.cat, определяет категории, которые можно использовать для классификации видео. Документ категорий – это файл XML, определяющий категории и указывающий, можно ли добавлять к ним новые видео и можно ли найти эту категорию на YouTube.
Фрагмент ниже показывает записи категорий "Entertainment" и "Nonprofit & Activism" ("Кино и ТВ" и "Общественные акции") в документе категорий YouTube от 2 января 2008 года. Заметьте, что видео можно относить к обоим категориям, но только категория Entertainment доступна в тот момент для поиска на YouTube. Как показано в примере, присутствие тега <yt:browsable> означает, что соответствующая категория доступна для поиска на YouTube, а присутствие тега <yt:assignable> означает, что к этой категории можно добавлять новые видео. (К категориям, которые не обозначены тегом <yt:assignable> как открытые, нельзя добавлять новые видео.)
<atom:category term='Entertainment' label='Entertainment'> <yt:browsable/> <yt:assignable/> </atom:category> <atom:category term='Nonprofit' label='Nonprofit & Activism'> <yt:assignable/> </atom:category>
В запросе API добавления значение тега <media:category> должно быть установлено на значение атрибута <atom:category> тега term для соответствующей категории. Следующий пример показывает, как использовать тег <media:category> для присвоения новому видео категории Nonprofit & Activism, приведенной во фрагменте схемы выше.
<media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">Nonprofit</media:category>
Для создания запроса поиска HTTP, необходимо следовать некоторым правилам, чтобы Google мог правильно обработать ваш HTTP-запрос и выдал адекватный ответ.
Схема URL HTTP указывает, что запрос HTTP URL может содержать только определенные символы:
Google использует зарезервированные символы для декодирования URL и использует некоторые специальные символы для поисковых запросов. Поэтому следует перевести в URL все не буквенно-цифровые символы, которые есть в значениях параметров поиска.
Для переведения строки в URL, превратите последовательности пробелов в один "+" (символ плюс) и замените все остальные не буквенно-цифровые символы шестнадцатеричными значениями этих символов. Шестнадцатеричные коды специальных и зарезервированных символов, перечисленных выше, приведены в следующей таблице. Каждый их них должен быть переведен в URL в значениях параметров запросов.
| Символ | Шестнадцатеричный код |
|---|---|
| $ | %24 |
| - | %2D |
| _ | %5F |
| . | %2E |
| + | %2B |
| ! | %21 |
| * | %2A |
| " | %22 |
| ' | %27 |
| ( | %28 |
| ) | %29 |
| ; | %3B |
| / | %2F |
| ? | %3F |
| : | %3A |
| @ | %40 |
| = | %3D |
| & | %26 |
| | | %7C |
Examples
| Исходная строка | Строка, переведенная в URL |
|---|---|
| punch&judy | punch%26judy |
| O'Reilly | O%27Reilly |
Дополнительные сведения о переводе в URL можно найти в RFC 2396 и W3C.
