Данный раздел содержит общее описание бизнес-логики и протоколов взаимодействия (интерфейсов) компонент и подсистем продуктов Инетры (Peers.TV, Peers и Детский Пирс), назначение и общие правила применения конкретных интерфейсов и примеры применения. Для общего понимания целей интерфейсов рекомендуется регулярно перечитывать на ночь документы «Видение…» соответствующих продуктов, например, Видение продукта Peers.TV.
Документ предназначен для внутреннего потребления, для сотрудников компании Инетра, которые уже обладают минимальными знаниями о продуктах, сервисах и т.п..
Содержащиеся в этом документе общие правила применимы ко всем продуктам Инетры, существующим и будущим, которые используют иди будут использовать любые из интерфейсов пакета CN.API. Исключения (должны) будут упомянуты явно в настоящем документе и описаны подробно в документации по конкретному интерфейсу.
Все используемые в настоящем документе общие для всего проекта термины и определения описаны в документе Термины и определения. Термины, определяемые локально в настоящем разделе, могут только уточнять и дополнять смысл общих определений в контексте документа, но не должны противоречить им.
Единой начальной точкой получения информации о доступных Клиенту сервисах является Регистратура, которая заполняется следующими участниками:
Клиент получает информацию с помощью Registry API, который является частью Регистратуры. Типы сервисов описаны ниже.
Важно: Каждый сервис ассоциирован с каким-либо Контрагентом (поставщиком этого сервиса). Клиенту рекомендуется поддерживать в течение сеанса структуру данных со сведениями обо всех сервисах, в том числе и о поставщиках каждого сервиса. Клиент должен интерпретировать и использовать все доступные Сервисы, которые он технически может интерпретировать и способен использовать. Этим обеспечивается требуемая гибкость формирования доступных услуг силами только Регистратуры, без переписывания Клиента.
Тоже важно: В настоящем наборе интерфейсов сознательно разделяется логическая структура услуг (например, Телеканал, Передача, Выпуск передачи) от физического представления (URL-адрес вещания, URL-адрес записи передачи). Это разделение может выглядеть лишним уровнем абстракции, но оно позволяет единообразно и просто реализовать поддержку нескольких источников сигнала для одной услуги, нескольких вариантов качества кодирования одного и того же объекта, несколько вариантов доставки одной и той же услуги, гибко управлять доступом на стороне Регистратуры без постоянного допереписывания Клиента.
Нужно понимать, что компания Инетра выполняет несколько ролей, и не смешивать права и обязанности этих ролей, в том числе в работе с сервисами.
Отдельно должно доставлять сотрудникам нашей компании, что текущая роль компании и самих сотрудников в каждой конкретной ситуации может быть определена только из контекста. :)
В различных экранных формах Клиента предполагается использовать различные подмножества полного списка доступных клиенту сервисов.
Если клиент реализует ЭФ «ТВ моего оператора» (например), то для неё должны быть использованы только те телеканалы из общего списка доступных, которые предоставляются текущим оператором, в расписании телеканала в такой ЭФ могут быть использованы только ссылки на записи телепередач, ассоциированные с текущим оператором (если они есть), в списке «Топ популярных» могут быть использованы записи только с тех телеканалов, которые ассоциированы с текущим оператором.
В экранных формах, которые собирают все доступные услуги в удобном для Пользователя едином списке, производится логическое «ИЛИ» всех доступных услуг, т.е. телеканал появляется в списке телеканалов, если он доступен Пользователю хотя бы от одного Контрагента, телепередача отображается с доступной к просмотру записью, если запись этой передачи доступна Пользователю хотя бы от одного Контрагента и т.д..
При наличии нескольких альтернативных источников услуги (нескольких контрагентов-поставщиков) Клиент должен выбрать одного поставщика по определённому алгоритму. Рекомендуемый набор правил для построения такого алгоритма:
Очевидно, что некоторые правила на некоторых платформах могут быть сложнореализуемы, например, правило недостаточного качества, однако разработчикам рекомендуется изыскивать все возможные способы для реализации именно такой политики выбора источников.
На выдачу информации сервисами могут быть наложены дополнительные условия: запрещающие или разрешающие. Условия могут быть основаны на различных признаках (например, по гео–признаку, по контрагенту) и могут различаться в зависимости от типа сервиса. Примером таких условий являются ограничения по гео–признаку или предоставление дополнительной информации пользователям партнеров–провайдеров, а также авторизация доступа к платному контенту.
Для доступа к сервисам контрагента может потребоваться авторизация.
Контрагент может осуществлять аутентификацию пользователя и авторизацию доступа к сервисам на основе выданных аутентификационных данных — пары логин/пароль, аутентификационной сессии — или на основе IP адреса.
Аутентификация пользователя и авторизация по IP адресу происходит прозрачно для клиентского приложения.
В случае аутентификации по паре логин/пароль с использованием HTTP Basic Auth, клиент должен запросить пару логин/пароль у пользователя, полученную пару клиент должен сохранить и использовать при следующих запросах на аутентификацию по логину/паролю для любого из предоставленных контрагентом сервисов.
В случае наличия аутентификационного сервиса клиент должен получить аутентификационную сессию, сохранить ее и использовать при дальнейших обращениях к сервисам.
Некоторые сервисы могут предоставлять описательную информацию на нескольких языках.
По умолчанию сервис выдает информацию на основном действующем на текущей территории языке, так например, для Российской Федерации основной язык — русский. Если сервис не поддерживает основной действующий язык, то будет выбран язык по умолчанию, например, для стран СНГ таким языком будет русский язык, для стран Европы — английский язык. Территория определяется по IP адресу или другим гео–признакам.
Языки, на которых сервис выдает информацию, заполняются в HTTP заголовке Content-Language.
Язык содержимого можно указывать для любых медиатипов, а не только для текста. Например, если это видео, где люди говорят на английском, в котором сбоку расположено окошко с сурдопереводом на амслене, а внизу расположен перевод субтитрами на русском, то заголовок Content-Language должен иметь значение en, ase, ru. При этом, если это видео, где герои говорят на японском, и присутствует голосовой перевод на русском, то следует указать только русский язык, так как японцам, скорее всего, будет трудно расслышать родную речь.
Клиент может влиять на выдачу, передавая список предпочитаемых языков посредством HTTP заголовка Accept-Language. Пример задания заголовка:
Accept-Language: ru, en;q=0.9
Такая запись означает, что предпочитаемый язык — русский, но приемлемым языком будет английский.
Способ формирования языковых меток для заголовков Accept-Language и Content-Language указан также в RFC3282.
Описание языков информации в ответе относится только к телу ответа, но не к информации, на которую может ссылаться тело ответа. Т.е., нормальной является ситуация, когда англоязычный ответ со списком каналов в формате M3U с правильно указанным Content-Language: en будет содержать ссылки на русско- и украиноязычные телеканалы.
На момент написания данной документации (декабрь 2013) существуют следующие типы сервисов:
Сервис «Peers.TV», предоставляемый ООО «Инетра», является смесью сервисов IP–телевидение и Запись телепередач и на данный момент выделен в отдельную сущность. Устарел, для новых разработок использовать сервис peerstv не рекомендуется. Рекомендуется переписать существующие приложения с использованием сервисов iptv и media_locator.
С помощью Films API данного сервиса можно получить список фильмов по указанному фильтру, детальную информацию о фильме. Также ссылки на файлы фильма в файлообменной сети «Peers», однако этот метод получения ссылок устарел, рекомендуется переводить приложения на интерфейс media_locator.
На данный момент сервис фактически предоставляется единолично ООО «Инетра» на территории «Весь мир». Возможно зеркалирование сервиса у провайдеров–партнеров, например, ООО «Владлинк», предоставляющий данный сервис для своих абонентов.
Сервис iptv позволяет смотреть эфир различных телеканалов. Предоставляется множеством провайдеров, обычно только в границах собственной сети. В качестве API зачастую используются списки каналов, хранящиеся в файлах на серверах провайдера в форматах XSPF или M3U. Некоторые операторы генерируют для абонентов список, состоящий только из бесплатных и уже купленных каналов. Одним из таких примеров является ООО «Новотелеком».
Сервис может использовать различные способы доставки контента абоненту, на данный момент основным является multicast, дополнительным, продвигаемым компанией «Инетра» — HTTP Live Streaming, поддерживающийся на большем количестве устройств, в отличие от первого, но имеющий свои недостатки. Один оператор связи может предоставлять одну и ту же услугу несколькими способами доставки, в том числе и одновременно.
Исторически сложившимся исключением является контрагент Инетра (роль Инетра-вещатель), предоставляющий сервис «Peers.TV», частью которого также является вещание эфира телеканалов. Однако, тип сервиса peerstv является устаревшим и не рекомендуется к использованию в Клиентах, следует перевести Клиентов на использование сервиса типа iptv.
Сервис позволяет смотреть записи эфира различных телеканалов. Предоставляется через несколько API – peerstv и media-locator.
Планируется (с начала 2014 г.) предоставление услуги Записи телепередач ещё несколькими провайдерами. На данный момент (ноябрь 2013 г.) единственным контрагентом является ООО «Инетра», предоставляющая услугу в рамках сервиса «Peers.TV». Однако, тип сервиса peerstv является устаревшим и не рекомендуется к использованию в Клиентах, следует перевести Клиентов на использование сервисов типа tv_guide и media_locator.
Сервис позволяет прослушивать эфирное вещание различных радиоканалов. Предоставляется контрагентом «Инетра» всем пользователям. В качестве API используются списки каналов, хранящиеся в файлах в форматах XSPF или M3U.
Сервис может использовать различные способы доставки контента пользователям, на данный момент основным является TS–поток, передаваемый по транспорту HTTP (аудиокодек — MP3).
Сервис позволяет… обмениваться файлами. Предоставляется клиентами Peers и Pikachu, на данный момент осуществляется только по NMDC и ADC протоколам. В разработке находится еще один протокол, который будет поддерживаться только новым клиентом, Pikachu.
Услуга предоставляется несколькими операторами связи, основные из них это «Новотелеком» в Новосибирске и области, «Эртелеком» в различных регионах России, «E-Light» в Кемерово и области, а также «Владлинк» во Владивостоке.
Сервис позволяет получать информацию о канале, в том числе расписания телепередач, в зависимости от территории пользователя. Сервис не привязан ни к одному поставщику услуг телевидения, носит информационный характер. Предоставляется в виде TV Guide API, единственный поставщик — ООО «Инетра».
Данный сервис позволяет узнать:
cn-id) каналов;Данный сервис не позволяет и не может быть использован для получения:
За данной информацией надо обращаться к сервисам телевидения и записей телепередач соответствующих провайдеров.
Канал, вещаемый в разных регионах может иметь различную программу передач, а также содержать региональные рекламные вставки. Программу передач канала однозначно можно идентифицировать по идентификатору канала и территории, для которой предназначено вещание.
Территория программы передач может быть получена явно — в виде атрибута к источнику вещания, и косвенно — на основе предположений, что источник вещания является локальным, т.е. предназначен для текущей территории.
Данный сервис предназначен для осуществления навигации по произвольным наборам медиа-контента, заранее сформированным модератором.
Данный сервис может быть использован:
ВАЖНО: идентификатор сессии может быть использован только для доступа к службам одного контрагента, которому принадлежит аутентификационный сервис.
Данный сервис предоставляет гибкую структуру для хранения данных пользователя, таких как: избранные каналы, избранные передачи, история просмотров, настройки пользователя и т.д.
Сервис также предоставляет возможность оформить подписку на различные события посредством push–уведомлений. Для активации push–уведомлений клиент должен зарегистрировать установку приложения и используемое устройство в Сервисе хранения пользовательских данных.
Сервис позволяет поставщику услуг отслеживать события, происходящие у приложения. Это может быть как статистические данные о продолжительности времени работы, так и сбор сведений о качестве предоставления услуг.
На одной и той же территории для одного сервиса может существовать несколько сервисов трекинга. Так, плеер IP–телевидения может отправлять статистику использования приложения своему разработчику, а события, характеризующие качество предоставляемой услуги IP–телевидения — провайдеру.
На данный момент предоставляется только «Инетрой», по протоколу Tracking API.
При взаимодействии с сервисами клиент должен использовать только поддерживаемые версии протоколов, а в рамках версии — в соответствии с актуальной документацией. Подробная информация получении о версий сервисов доступна в Registry API.
При работе с сервисами рекомендуется придерживаться нескольких простых правил:
В данном разделе документации описываются лишь способы общения программного обеспечения и сервисов. При этом, у различных сервисов могут быть одинаковые механизмы передачи информации (например, связка HTTP + JSON), способы упаковки и структуры данных, но разные смыслы.
Обратимся за примером к TV API. У сообщения Channel имеется поле access, отвечающее за наличие доступа у абонента к данному каналу. Однако, не все сервисы, работающие по TV API, могут сообщить информацию о доступности канала. Допустим, у абонента А, который находится в Москве, доступны следующие сервисы:
Каждый провайдер, предоставляющий непосредственное вещание «Первого» канала может передать информацию о доступности или недоступности канала для конкретного абонента. Сервис «Телепрограмма», напротив, сделать этого не может, так как не имеет (и, в общем случае, никогда не сможет получить) доступа к автоматизированной системе расчета с абонентами ни одного из поставщиков услуг вещания «Первого» канала.
Поэтому для сервисов, предоставляемых одним API, отдельно оговаривается, какие параметры для них имеют или не имеют смысла.
Примечание: описанный в этом пункте пример относится к устаревшей модели применения API. В настоящий момент (декабрь 2013) рекомендуется получать общую информацию о каналах, безотносительно доступности через конкретных провайдеров, через TV Guide от Регистратуры, а получать сведения о доступности каналов от Провайдеров – через плейлисты формата m3u от самих Провайдеров.
На данный момент все API описаны способом Google Protocol Buffers. Как его понимать описано на отдельной странице.
Между сервисами могут существовать связи. Более того, они натурально существуют. Эти связи описаны в конкретной документации на интерфейсы или в примерах применения.
Рассмотрим последовательность использования интерфейсов в самом популярном сценарии – Пользователь запустил приложение-Клиент, посмотрел телевещание канала, и потом посмотрел запись телепередачи.
whereami.id локального оператора (Contractor), и перечень доступных сервисов с указанием провайдеров (Services).iptv, доступ по http, формат m3u), и получает полный список доступных вещаемых телеканалов от всех провайдеров. Плейлисты могут содержать дополнительную информацию о каналах, такую, как id телеканала, признак наличия записей для канала, признак (не)доступности канала, если он неоплачен, например.tvguide/idbytitle) за идентификаторами каналов, которые не имеют идентификаторов в плейлистах.tvguide/channels) за метаинформацией о телеканалах (иконки, расписание и т.п.)recordable, и если этот провайдер предоставляет сервис media-locator, для канала в экранной форме отображается соответствующий знак (Архив) и для этого канала запрашивается перечень записей передач для отображаемой даты. Провайдер отвечает списком записей, и Клиент отображает в расписании наличие записей (опять таки объединяя их по «ИЛИ»).