Формирование запроса в RestAPI.

Tvigle Video Publisher RestAPI
Tvigle Video Publisher RestAPI
Документация для партнеров
Version 1.001
Оглавление
I.
Введение. .................................................................................................................................3
II.
Получение Сертификата..........................................................................................................4
III.
Формирование запроса в RestAPI. .....................................................................................5
IV.
Методы протокола. .............................................................................................................6
A.
version ...............................................................................................................................6
B.
catalog ...............................................................................................................................7
C.
videolist .............................................................................................................................8
D.
video ..................................................................................................................................9
V.
Список ошибок ...................................................................................................................10
A.
ERR_SINED .......................................................................................................................10
B.
ERR_DEPRECATED ...........................................................................................................10
C.
ERR_NO_DATA ................................................................................................................10
2
I.
Введение.
Данный набор функций предназначен для создания приложения вещания на платформах, не
поддерживающих технологию flash. Функции предоставляют доступ к структуре контента
партнера хранящегося в сиcтеме Video Publisher и прямым ссылкам на видео. Предполагается, что
основная работа будет производиться с клиентских устройств. Протокол позволяет получать
данные в двух форматах - xml и json. Используется текстовая кодировка UTF-8.
В целях сохранения стабильности работы системы и выполнения соглашения об авторских
правах, запрещается выкладывать результат работы функций в открытый доступ.
3
II.
Получение Сертификата.
Для начала работы с Tvigle Video Publisher Rest API необходимо получить Сертификат.
Сертификат представляет собой набор из двух 32х символьных значений Ключ и Секретный ключ.
Для их получения необходимо осуществить следующие действия:
a) Зарегистрироваться в системе Tvigle Video Publisher (http://vp.tvigle.ru/). Сообщить
Администрации сервиса email, указанный при регистрации, для получения необходимого
для приобретения Сертификата статуса.
b) Приступить к получению Сертификата, после подтверждения (на электронную почту) о
смене статуса. Это разовая операция - повторить ее нужно будет только в случае
компрометации Сертификата. Для получения Сертификата необходимо вызвать метод
GetRestAccess из Tvigle Video Publisher SOAP1.
a. Вызов GetRestAccess с пустым параметром возвращает ваш ключ.
b. Вызов GetRestAccess c ключом возвращает секретный ключ.
Пример кода (php):
$sUrl = 'http://pub.tvigle.ru/soap/index.php?wsdl';
$sLogin = '****';//Логин, который указан при регистрации
$sPassword = '*****';// Пароль, который указан при регистрации.
$soap = new SoapClient($sUrl, array('login' => $sLogin,'password' => $sPassword));
$key
echo
$sek
echo
= $soap->GetRestAccess();
"key: $key\n"; // Ваш ключ
= $soap->GetRestAccess($key);
"sekret: $sek\n"; // Ваш секретный ключ
c) Предполагается, что данные Rest API будут обновляться раз в сутки, поэтому доступ к API
предоставляется на следующий день после запроса сертификата.
d) В структуру данных Rest API попадают только данный отмеченные как опубликованные.
1
Подробнее о протоколе SOAP Tvigle Video Publisher можно узнать на сайте http://vp.tvigle.ru/api/.
4
III.
Формирование запроса в RestAPI.
Все запросы RestAPI имеют следующий вид:
http://rest.pub.tvigle.ru/{method:string}/{key:string}/{data}/{format:string}?sig={string}
a) Method - название вызываемого метода. Полный список приведен в п. (3);
b) Key - ключ приложения, полученного в п. (1);
c) Data - параметр метода, подробнее описан в п. (3);
d) Format - формат, в котором необходимо получить результат. RestApi поддерживает два
формата - xml и json;
e) Sig - идентификатор подписания запроса. Он рассчитывается по следующей формуле:
Md5(SekKey + Method + Data + Format)
i)
SekKey - секретный ключ;
ii)
md5 - необратимая функция (http://ru.wikipedia.org/wiki/MD5), если ее даже нет в
среде разработки, можно написать собственную реализацию;
iii)
+ - конкатенация;
iv)
Если метод не предполагает передачу каких-то дополнительных данных, то вместо
них передается «0».
Некоторые методы предполагают дополнительные параметры, они передаются как get
параметры запроса и не участвуют при расчете подписи (sig). Это могут быть параметры
page, order, txt.
5
IV.
Методы протокола.
A.
version
Описание
Возвращает данные о текущей системе в зависимости от параметра data:
а) если data = 1 - возвращает версию текущей версии протокола.
b) если data = 2 - возвращает время последнего обновления в формате ISO 8601.
В случае остальных значений data возвращается ошибка ERR_NO_DATA.
Возвращает
a) Если data = 1
XML
<?xml version="1.0" encoding="utf-8"?>
<root>
<value>1.000</value>
</root>
JSON
{"value":"1.000"}
b) Если data = 2
XML
<?xml version="1.0" encoding="utf-8"?>
<root>
<value>2012-05-27T15:06:33+04:00</value>
</root>
JSON
{"value":"2012-05-27T15:06:33+04:00"}
Где
value – запрашиваемое значение.
6
B.
catalog
Описание
Метод для получения данных о структуре видео. Структура рубрики – это двухуровневое
дерево:
а) Для получения первого уровня необходимо обратиться к методу с параметром data=0;
b) Для получения рубрик подуровня необходимо обращаться с идентификатором рубрики
первого уровня.
Возвращает
XML
<?xml version="1.0" encoding="utf-8"?>
<root>
<item id="4355" name="Лекции на Дожде" priorety="0" tp="0"
anons="" logo=""/>
<item id="4621" name="Ходячие мертвецы" priorety="0" tp="0"
anons="" logo=""/>
…
<item id="4604" name="Летнее Чтение" priorety="0" tp="0"
anons="" logo=""/>
</root>
JSON
[{"id": "4355","name":
"\u041b\u0435\u043a\u0446\u0438\u0438
\u043d\u0430\u0414\u043e\u0436\u0434\u0435",
"priorety": "0","tp": "0","anons": "","logo": null}
…………….,
{"id": "4604",
"name":
"\u041b\u0435\u0442\u043d\u0435\u0435
\u0427\u0442\u0435\u043d\u0438\u0435","priorety": "0","tp":
"0","anons": "","logo": null}]
Где
id – идентификатор рубрики;
name – название;
priority – приоритет в списке среди равных;
anons – краткое описание;
7
C.
videolist
Описание
Возвращает список видео, принадлежащих рубрике. В качестве параметра data передается
идентификатор (id) рубрики.
Список можно получить частями по пять элементов, указав параметр page. При этом
критерием конца списка будет очередной список с количеством элементов меньше пяти.
Возвращает
XML
<?xml version="1.0" encoding="utf-8"?>
<root>
<item id="1462306" name="На несанкционированном митинге в
Алма-Ате требуют выхода из евразийского и таможенного
союзов" catalog="3872" date="2012-01-28T16:25:23+04:00"
anons="" tags="" duration="56000" geo=""
bimg="http://photo.tvigle.ru/res/prt/c330f15b00e2d7499a04688ae5
657e5d/23/06/000001462306/pub.jpg" dr="56000" rs="1"
preview="http://photo.tvigle.ru/res/prt/c330f15b00e2d7499a04688a
e5657e5d/23/06/000001462306/pub.jpg"/>…………………………
………………………………….
</root>
JSON
[{"id":"1462306","name":"\u041d\u0430
\u043d\u0435\u0441\u0430\u043d\u043a\u0446\u
0438\u043e\u043d\u0438\u0440\u043e\u0432\u04
30\u043d\u043d\u043e\u043c
\u043c\u0438\u0442\u0438\u043d\u0433\u0435
\u0432 \u0410\u043b\u043c\u0430-\u0410
……………………………………………………….]
Где
id - идентификатор видео;
name - название видео;
catalog - идентификатор рубрики, которой принадлежит видео;
date - дата публикации видео в формате ISO 8601;
anons - описание видео;
duration - длительность видео в 1000 мили-секунд;
geo - список гео-зон, в которых есть право на показ видео;
tags – набор ключевых слов, описывающих видео;
bimg – стоп-кадр видео: 720x405 и 720x540 соответственно в формате jpg.
8
D.
video
Описание
Полные данные, необходимые для показа видео. В качестве параметра data передается
идентификатор видео.
Возвращает
XML
<?xml version="1.0" encoding="utf-8"?>
<root>
<id>1462306</id>
<name>На несанкционированном митинге в АлмаАте требуют выхода из евразийского и таможенного
союзов</name>
<txt/>
<geo/>
<preview>http://photo.tvigle.ru/res/prt/c330f15b00e2d74
99a04688ae5657e5d/23/06/000001462306/pub.jpg</preview>
<img>http://photo.tvigle.ru/res/prt/c330f15b00e2d7499a0
4688ae5657e5d/23/06/000001462306/pub.jpg</img>
<date>2012-01-28T16:25:23+04:00</date>
<age>0</age>
<rs>1</rs>
<duration>56000</duration>
<video>
<list url="...."/>
</video>
</root>
JSON
{"id":"1462306","name":"\u041d\u0430
\u043d\u0435\u0441\u0430\u043d\u043a\u0446\u
0438\u043e\u043d\u0438\u0440\u043e\u0432\u04
30\u043d\u043d\u043e\u043c
\u043c\u0438\u0442\u0438\u043d\u0433\u0435
\u0432 \u0410\u043b\u043c\u0430\u0410\u0442\u0435
\u0442\u0440\u0435\u0431\u0443\u044e\u0442
\u0432\u044b\u0445\u043e\u0434\u0430
\u0438\u0437
\u0435\u0432\u0440\u0430\u0437\u0438\u0439\u
0441\u043a\u043e\u0433\u043e \u0438
\u0442\u0430\u043c\u043e\u0436\u0435\u043d\u
043d\u043e\u0433\u043e
\u0441\u043e\u044e\u0437\u043e\u0432","txt":
"","geo":null,"preview":"http:\/\/photo.tvig
le.ru\/res\/prt\/c330f15b00e2d7499a04688ae56
57e5d\/23\/06\/000001462306\/pub.jpg","img":
"http:\/\/photo.tvigle.ru\/res\/prt\/c330f15
b00e2d7499a04688ae5657e5d\/23\/06\/000001462
306\/pub.jpg","date":"2012-0128T16:25:23+04:00","age":0,"rs":"1","duratio
n":"56000","video":[{"url":"......"}]}
Где
id - идентификатор видео;
geo - список гео зон, в которых есть право на показ видео. Если значение geo – пустое, то нет
ограничений;
img - стоп-кадр видео;
date - дата публикации видео в формате ISO 8601;
age - идентификатор типа содержания видео. Если равен 1, то видео содержит сцены, не
рекомендованные для просмотра детям до 16.
rs – идентификатор соотношения сторон видео:
a) 1 - для видео 16x9
b) 2 - для видео 4x3
duration - длительность видео в 1000 мили-секунд;
video - набор ссылок на файлы в формате mp4, из которых состоит видео, расположенных
последовательно;
Ссылки на видео формируются для ip с которого они запрошены и действительны в
течении часа.
9
V.
Список ошибок
A.
ERR_SINED
HTTP ERROR: 401 Unauthorized
Возвращается в случае неправильного формирования подписи.
B.
ERR_DEPRECATED
HTTP ERROR: 405 Method Not Allowed
Возвращается в случае запроса несуществующего метода.
C.
ERR_NO_DATA
HTTP ERROR: 404 Not Found
Возвращается в случае запроса несуществующих данных.
10