smira Jul 14 2009 at 08:33

Qik Push Engine API: приглашаем разработчиков

5 min

792

Qik — это сервис стриминга (вещания) и загрузки видео с мобильных телефонов. Загруженное видео можно посмотреть на сайте или на его специальной версии с мобильного телефона. Доступна интеграция с другими сервисами, такими как Twitter, Facebook и другие. Клиенты для практически всех современных моделей телефонов: iPhone, Windows Mobile, Symbian, Android, Blackberry и другие.

Qik Push Engine — это механизм, который позволяет получать мгновенные оповещения о новых/изменившихся Qik-видео. Например, можно посмотреть постоянно обновляющийся список live-видео, все видео из района Новопеределкино или все видео со словом “кошка”. На основе Qik Push Engine API можно построить интересные приложения, интегрированные с Qik, или добавить функциональность в уже существующие. Можно написать собственную систему нотификации, desktop-widget
или что-то еще.

Сегодня мы открываем API для работы c Qik Push Engine. Это первая ласточка в большом списке API, открывающих доступ к платформе стриминга Qik. Если вам интересно посмотреть Qik Push Engine в действии, заходите на одну из страниц примеров.

Основы работы с API

Qik Push Engine API доступно в виде набора удаленных процедур по протоколу JSON-RPC (over HTTP). В ближайшее время будет открыт REST-подобный интерфейс. Точкой входа для JSON-RPC является engine.qik.com/api/jsonrpc. Пока проект находится в закрытом бета-тестировании для доступа к API необходимо указать ключ разработчика, добавив параметр apikey: engine.qik.com/api/jsonrpc?apikey=xxxxxxx. Ключ разработчика можно получить, отправив письмо с запросом на api@qik.com.

Пример HTTP-сессии:

POST /api/jsonrpc
Host : engine.stage.qik.com
Content-Type:  application/json; charset=UTF-8
Content-Length: 46

{"method": "qik.session.create", "params": []}

Ответ:

Content-Type: text/json 

["a56c1603-1fbb-4140-8b35-8c36abbd8b27"]

Пример подписки на поток событий

Здесь и далее я буду использовать простую запись вызова команд, которая похожа на вызов обычных функций, опуская детали JSON-RPC взаимодействия. Итак, пусть мы хотим подписаться на список всех live-стримов, которые есть данный момент.

Первым делом создадим сессию:

qik.session.create() -> "a56c1603-1fbb-4140-8b35-8c36abbd8b27"

Подписываемся в рамках сессии на view всех публичных live-стримов, при этом указываем максимальное количество элементов во view (limit). Элементы view будут упорядочены в порядке убывания даты начала стрима (самые новые первыми):

qik.stream.subscribe<em>public</em>live("a56c1603-1fbb-4140-8b35-8c36abbd8b27", 10) -> 
 [ "174/('PublicLiveStreamView', 'Stream', [('stoptime', None)], 'alllive;limit=10')", [ ... ] ]

В ответ на запрос мы получаем массив из двух элементов: первым является ключ подписки (длинная строка, начинающаяся с “174/..”). Не ищите смысла в ключе подписки, его необходимо просто сохранить, он потребуется в дальнейшем.

Вторым элементом является начальное состояние view, то есть текущий список live-стримов в нашем случае. Мы получим не больше 10 элементов (так как указали limit 10 при вызове метода qik.stream.subscribe_public_live). Состояние view выглядит примерно следующим образом:

[
   {"url": "http://qik.com/video/2158468", 
    "live": true, 
    "user_id": 340699, 
    "small_thumbnail_url": "http://media.qik.com/media.thumbnails.128/c8ad8fe065ad4ad7ac8491874c043eac.jpg", 
    "title": "Untitled", "duration": 0,
    "created_at": "2009-07-11 15:56:03", 
    "views": 0, 
    "id": 2158468}, 

   {"url": "http://qik.com/video/2158466", 
    "live": true, 
    "user_id": 340119, 
    "small_thumbnail_url": "http://media.qik.com/media.thumbnails.128/984c33e1ead441038f315e1fff109fc5.jpg", 
     "title": "Testando!", 
     "duration": 0, "created_at": "2009-07-11 15:55:34", 
     "views": 0, 
     "id": 2158466}
]

Смысл большинства полей очевиден, приведу лишь некоторые комментарии:

все даты приведены в UTC;
поле duration хранит длительность видео в секундах.

Так как мы подписались на live-стримы, у всех видео live == true.

Теперь нам необходимо получать новые события для тех view, на которые мы подписались. Для этого используются HTTP long polling-запросы. Клиент отправляет запрос серверу, а сервер отправляет ответ, когда появляются события или когда истечет таймаут, если событий не появилось.

Для реализации long polling в цикле вызываем метод qik.session.get_events, указывая желаемый таймаут (не рекомендуется использовать таймаут более 90 секунд).

qik.session.get_events("a56c1603-1fbb-4140-8b35-8c36abbd8b27", 60) -> 
  [ {...} ,{...} ]

В ответ мы можем получить пустой массив событий, если истек таймаут, или некоторый набор событий следующего вида:

[
   {
     "action": "update", 
     "old": {"id": 104252, "title": "Untitled", "views": 0, ...}, 
     "obj": {"id": 104252, "title": "driving to key largo", "views": 5, ...}, 
     "key": "175/('PublicRecentStreamView', 'Stream', [], 'allrecent;limit=50')"
    },
]

В каждом событии обязательно передается следующая инормация:

key — ключ подписки, это то же самое значение, которое мы получили при подписке на view, ключ позволяет отличать события для разных view в рамках одной сессии;
action — действие (изменение), произошедшее с view:
- ping — ничего не произошло, просто view сообщает, что все хорошо
- update — элемент view изменился (как в примере выше), передается старое и новое состояние объекта в полях old и obj
- insert — во view добавился новый элемент, его состояние будет записано в поле obj
- delete — элемент исчез из view (может быть, видео было удалено, или просто перестало удовлетворять критериям view, или ушло за границу “limit”), последнее состояние объекта будет записано в поле obj.

— абстрактный класс, представляющий view на стороне клиента. Обслуживание обновлений, отображение в элементах HTML, обработка событий и т.п. Списки элементов хранятся прямо в DOM-контейнере в виде HTML-узлов.

Потомки QikEngine.View для реализации конкретных view: QikEngine.PublicUserStreamView, QikEngine.PublicRecentStreamsView и т.д.

updater.js

Очень простой интерфейс между данными, полученными из Qik Push Engine (например, информацией о стримах) и HTML-элементами. Адаптация данных, например, перевод дат из UTC в локальный формат, форматирование значений и т.п.

usercache.js

QikEngine.UserCache — механизм загрузки информации о пользователях (по их ID). Использует DeferredManager для ограничения количества параллельных запросов.

Что делать дальше?

смотрите описание API;
пишите письмо на api@qik.com, расскажите о своем проекте и получайте ключ для доступа к API.

Полный список примеров

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

Tags:

Hubs:

Website development