API — различия между версиями

Версия 00:55, 10 февраля 2015

Термины

Контент – содержательная часть видео- или радиотрансляции в цифровом виде.

- Сервис – программно-аппаратный комплекс предоставления доступа к IPTV как к услуге.

- Клиент – приложение или устройство, получающее доступ к Сервису посредством учет- ной записи.

- Абонент – физический пользователь сервиса SUNDUK.TV

- Абонемент – учетная запись клиента. Логин и пароль цифровые – для удобства набора со стандартного пульта управления устройства (settopbox).

- Сервер вещания – streamserver – программно-аппаратный комплекс для организации трансляции потокового видео и радиосигнала.

- Ссылка вещания – URL, по адресу которого сервер вещания транслирует контент.

- Middleware – комплекс сервисов авторизации и управления абонементами, потоками ве- щания, персональными настройками.

- API – интерфейс Middleware для программного взаимодействия с клиентом.

Принцип работы

Провайдер транслирует видеопотоки телевизионных и радио каналов в сети Интернет. Видеокон- тент предоставляется посредством транспортного потока HTTP/TS с распределенных серверов провайдера. Контент закодирован видеокодеком H.264 и аудиокодеком AAC (подробные техни- ческие характеристики потока представлены в справочном разделе настоящего руководства). Сервис предоставляется на платной основе, в виду чего становится невозможным предоставлять доступ к вещанию обычными средствами. В отличие от ссылок типовых списков воспроизведения (playlists), ссылки вещания не могут быть постоянными, поэтому они динамически генерируются на время сессии работы клиента. Для генерации уникальной ссылки необходимо реализовать методы работы с сессией клиента. При первом обращении к системе необходимо авторизоваться и инициировать сессию. Ответ сервера включает в себя ключ сессии, который необходимо передавать при каждом обращении. Для удобства реализации сервер принимает ключ сессии как в виде параметра URL, так и в виде COOKIES.

Общий алгоритм приложения можно представить следующим образом:

1. авторизация /login и получение списка настроек клиента

2. получение списка каналов, групп каналов, текущего EPG на каждый канал. /channel_list

3. при выборе абонентом канала необходимо получить ссылку вещания для этого канала /get_url

4. проигрывание полученной ссылки воспроизведения

5. подгрузка следующего фрагмента EPG при окончании телепередачи /epg_current

6. загрузка EPG на весь день при просмотре программы телепередач за этот день и при вы- боре телепередачи из архива.

Использование API

Работа с API подразумевает работу с сетью и не накладывает на приложение клиента никаких ограничений по выбору средств реализации. Другими словами – программная часть клиента мо- жет быть реализована на любом языке программирования, который может использовать библио- теки работы с сетью и протокол HTTP. Поскольку типы ответов могут быть как в формате XML, так и в формате JSON, рекомендуется использовать готовые библиотеки для работы с этими форматами данных. Мы рекомендуем использовать формат JSON как наиболее удачный формат для работы с ассоциативными (хэш) массивами. Также рекомендуется использовать автономное хранилище для хранения промежуточных данных (ключ сессии, настройки клиента, всевозможные списки и т.п.) Все запросы к API отправляются по протоколу HTTP, формируются по специально сформирован- ному URL и имеют следующий вид:

httр://iptv.kartina.tv/api/<тип ответа>/<имя функции>?param1=value&param2=value...

<тип ответа> задает формат выходных данных. Данные могут быть типов: XML, JSON, JSONP

Все возвращаемые сообщения имеют вид ассоциативного массива.

Формат времени

Все данные, обозначающие дату и время, представлены в формате unixtime. Каждый ответ серве- ра имеет отпечаток времени сервера (для синхронизации) с тегом <servertime>

Cookie

Для идентификации и создания сессии используется стандартный механизм HTTP-сессий с под- держкой COOKIE. При первом входе необходимо выполнение login. При корректном входе возвращается парамет- ры состояния, данные по клиенту и COOKIE, которые необходимо передавать при последующих запросах. В COOKIE хранится идентификатор сессии. Если запрос не содержит COOKIE, то это вызо- вет ошибку. Для корректного завершения сессии необходимо вызвать метод logout. COOKIE уста- навливается стандартным HTTP ответом, поэтому если клиент использует браузер или фреймворк, то COOKIE будут передаваться автоматически, в противном случае клиент должен позаботиться об сохранении ключа сессии. Также возможна передача параметров &<имя сессии>=<ключ сессии> через url. <Имя сессии> при этом необходимо брать из ответа пакета функции /login. Подобный метод из соображений без- опасности является не желательным, ровно как и передача login методом GET. Рекомендуем ис- пользовать HTTPS (безопасное шифрованное соединение через SSL) для авторизации.

Функции API

Функция login

Описание функции: функция выполняет логин клиента.

Вызов: /login?login=<login>&pass=<password>&device=<apple|default:all>&settings=all

Пример ответа по запросу /login?login=1234567&pass=1234567&device=all&settings=all

Функция account

Описание функции: возвращает информацию об аккаунте, аналогично функции login. Вызов:

/account

Функция logout

Описание функции: выполняет отключение клиента от сервиса. Вызов без параметров

/logout

Функция channel_list

Описание функции: получение списка каналов.

Для вывода информации о скрытых каналах следует использовать /channel_list?show=all&protect_code=<пароль закрытых каналов> В этом случае будет показан спи- сок всех каналов с дополнительным тегом <hide>0</hide>, который указывает скрыт ли канал в обычном режиме.

В списке для каждого канала также имеется «таблица» возможных сочетаний bitrate и timeshift. Может сложиться ситуация, когда установленный системный bitrate в сочетании с timeshift не за- дан для некоторых каналов. В этом случае каналы не попадают в список /channel_list. Информа- ция доступна в теге <stream_params>