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

Версия 01:08, 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>

Пример ответа по запросу /api/xml/channel_list

Функция /get_url

Описание функции: получение ссылки вещания на заданный канал.

Вызов: /get_url?cid=<ИД канала>&gmt=<дата время позиции архива>&protect_code=<пароль для закрытых каналов>

Архив. Сервисом организована запись некоторых телеканалов сроком до 14 дней для последую- щего вещания по требованию. Каналы имеющие архивную запись помечены флагом have_archive в списке каналов. Доступ к записанным данным возможен через указание параметра gmt для функции get_url, где указано время в формате unixtime. Архив доступен по истечении 30 минут после прямого эфира. Рекомендовано на стороне клиента ограничить доступ к несуществующему в архиве промежутку времени во избежание недоразумений. При попытки воспроизвести еще не записанный фрагмент будет воспроизведен ближайший доступный в архиве фрагмент.

Параметр URL специально сгенерирован для проигрывания через VLC с соответствующими опти- мизированными параметрами. URL генерируется только один раз. Для повторного просмотра ка- нала необходимо получить заново сгенерированный URL. При попытке трансляции канала не- сколькими сгенерированными URL одновременно, будет транслироваться только URL, получен- ный последним. Таким образом, возможна трансляция только одного потока для одной сессии.

Фильтрация каналов

В некоторых случаях возникает необходимость фильтра каналов. По разным причинам абоненты не всегда желают видеть в списках некоторые каналы. Был разработан механизм скрытия кана- лов. Для абонента это выглядит как закрытая по паролю область со списком каналов, где можно включить/выключить каналы.

Функция /rule

Описание функции: работа с правилами.

/rule?cmd=<hide_channel|show_channel|get_list|reset_channels>&cid=<id_канала>&protect_code=< protect_code>

Ответ команды cmd=<hide_channel show_channel reset_channels>

Ответ при cmd= show_channel

Есть возможность получить весь список каналов с флагом скрытый <hide>1</hide> путем парамет- ра show=all и protect_code=<пароль> функции /channel_list

Набор функций для работы с EPG

Телевизионная программа передач (EPG) требует особого подхода к реализации и понимания происходящих процессов. Генерация EPG на стороне сервера достаточно трудоемкий процесс и сопряжен с опасностью перегрузки системы при неправильной реализации. Каждый разработчик желает чтобы его приложение максимально быстро отвечало требованиям пользователя, но эти требования не всегда оправданы. Мы рекомендуем разработчикам использовать механизм ке- ширования данных EPG на сколько это возможно. Время жизни cache в этом случае целесообразно будет устанавливать в 3 часа. Это оптимальное значение. Особого смысла загружать ВЕСЬ EPG нет, поскольку данные не всегда будут востребованы. Идеальным вариантом был бы механизм фоновой подгрузки EPG основанный на событии окончания телепрограммы. Другими словами, при окончении телепередачи следует загружать данные о следующей телепередачи (или о не- скольких). Для реализации этого меанизма была разработана функция /epg_current. Просьба обратить внимание на тот факт, что многие пользователи привыкли к так называемому сёрфингу каналов – простое перелистывание с канала на канал не особо вчитываясь в содержимое EPG. Или же путем «пробежки» по каналам выбирать нужный им канал. В этом случае не стоит немедленно подгружать EPG по событию перехода на канал, а выдержать паузу 0.6 секунды (значение было выявлено эмпирически).

Функция epg

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

Вызов:

/epg?cid=<идентификатор канала>&day=<дата формата DDMMYY>

Функция epg3

Описание функции: получение программы телепередач доступных каналов со времени, указанного в dtime на следующие period часов.

Вызов:

/epg3?dtime=<Дата и время старта EPG>&period=<на сколько часов вперед>

Необходима для организации функционала "сетки вещания", как на http://tvschedule.zap2it.com/tvlistings/ . Программа генерируется с учетом timeshift переменной, выставленной пользователем в настройках.

Функция epg_next

Описание функции: возвращает EPG на текущее время и на 3 последующих телепередачи канала с заданным ID.

Вызов:

/epg_next?cid=<id канала>

Функция epg_current

Описание функции: для вывода данных об текущем EPG нескольких каналов. Реализована для ди- намичной подрузки данных EPG. Содержит время начала и конца передачи. При установленном epg=3 Возвращает данные о трех следующих передачах начиная с текущей.

Вызов: /epg_current?cids=<id1,id3,id3>&epg=3

ВНИМАНИЕ! Идентификаторы каналов должны быть переданы через запятую.

Пример вызова: /epg_current?cids=2,5,7

При установленномпараметреepg=3