Регистратура — точка входа для всех приложений Инетры, позволяющая определить:
Клиент может синхронизировать локальное время с серверным на основе информации о часовом поясе и времени генерации ответа, полученного из HTTP–заголовка Date
(см. RFC822).
Данный прием позволяет выполнить синхронизацию времени с некоторой ошибкой (ввиду сетевых задержек).
Корневой адрес API — http://api.peers.tv/registry/2/
. Формат ответа зависит от суффикса запроса:
.xml
— XML;.json
— JSON;Цифра 2
символизирует версию API и может меняться в дальнейшем.
API возвращает результат работы в HTTP–коде и имеет следующие стандартные коды ответов:
Код | Значение |
---|---|
200 |
Успешное обращение к методу |
400 |
В запросе отсутствует обязательные параметры |
501 |
Метод не реализован |
Каждый контрагент имеет список сервисов, которые предоставляются им на определенном множестве территорий. Виды сервисов, которые можно найти с помощью Регистратуры перечислены в таблице ниже. Сервис может иметь несколько способов доставки. К примеру, IP–телевидение может поставляться как с помощью multicast, так и с помощью других средств, вроде HTTP Live Streaming или RTSP.
Код | Идентификатор | Название | Провайдер | Возможные API | Описание |
---|---|---|---|---|---|
0 |
films |
Каталог фильмов CN.ru | Инетра и партнеры | Films API | С помощью API можно получить список фильмов, описания и ссылки для загрузки и просмотра из файлообменной сети Пирс. |
1 |
iptv |
IP–телевидение | Контрагент | IPTV | IP–телевидение, может распространяться различными транспортами. |
2 |
peerstv |
Peers.TV | Инетра и партнеры | PeersTV API | С помощью API можно получить список каналов, расписание для каждого из них, а также ссылки на эфир и записи телепередач для просмотра из файлообменной сети Пирс. |
3 |
peers |
Файлообменная сеть Пирс | Инетра и партнеры | NMDC, Registry API | С помощью API можно обнаружить доступные хабы и подключиться в качестве клиента. |
4 |
tv_guide |
Телепрограмма | Инетра | Media Guide API | С помощью данного сервиса можно получить информацию о канале по его идентификатору, а также расписание на прошлое и будущее время. Учитывается территория и, как следствие, ее часовой пояс. |
5 |
notification |
Уведомления | Инетра | Notifications API | С помощью API приложения рассылают пользователям уведомления о событиях. |
6 |
tracking |
Трекинг событий | Инетра | Tracking API | С помощью API приложения могут регистрировать происходящие события для последующей их обработки. |
7 |
auth |
Аутентификация пользователя и авторизация приложения | Инетра и партнеры | Auth API | |
8 |
user_data |
Данные пользователя | Инетра | User Data API | |
9 |
user_data_merge |
Слияние пользовательских данных | Инетра | User Data Merge API | устарело с версии 2.25.2 |
10 |
media_locator |
Нахождение источников вещания | Инетра и партнеры | Media Locator API | |
11 |
pinger |
HTTP pinger | Кто угодно | HTTP | С помощью данного API контрагент может определять активность приложений в своей сети. Приложение периодически отправляет запросы на адрес, указанный в location . |
12 |
radio |
Радио | Инетра и партнеры | Radio | Предоставляет список источников вещания каналов радио. |
13 |
catalogue |
Медиа Каталог | Инетра | Catalogue API | Предоставляет информацию о коллекциях медийных элементов. |
14 |
promo |
Промо | Инетра | Promo API | устарело с версии 2.28 |
15 |
bytefog |
ByteFog | Инетра | ByteFog API | Предоставляет узлам сети ByteFog поиск точек входа для получения потокового вещания. |
16 |
portchecker |
PortChecker | Кто угодно | PortChecker API | Предоставляет проверку возможности получения входящих соединений. |
17 |
internet |
Доступ к сети Интернет | Кто угодно | отсутствует | Описывает услугу «Доступ к сети Интернет» |
18 |
registry |
Регистратура | Инетра | Registry API | Предоставляет информацию о доступных сервисах |
19 |
money_miner |
Конфигуратор рекламы | Инетра | Money Miner API | Предоставляет информацию о рекламных сетей для баннерных мест |
20 |
launcher |
Вывод афиш в лаунчер на приставке | Инетра и ЭГ | Launcher API | Предоставляет список афиш для отображения в лаунчере на приставке |
21 |
appconfig |
Конфигуратор приложений | Инетра | Appconfig API | Предоставляет клиенту возможность получать информацию о конфигурационных параметрах. |
22 |
promo_block |
Промоблок | Инетра | PromoBlock API | Предоставляет данные для отображения промоблока (слайдера/карусели) |
23 |
promocode |
Промокоды | Инетра | [Promocode API] | Ввод и проверка промокодов |
24 |
feed |
Ленты | Инетра | [Feed API] | Выдача лент контента в приложениях |
25 |
purchases |
Покупки | Инетра | [Purchases API] | Получения данных о покупках в приложениях |
26 |
gismeteo |
Погода | Гисметео | Gismeteo API | Прогноз погоды от Гисметео |
Каждый сервис, выданный Регистратурой, может поддерживать одну или несколько версий протоколов взаимдействия.
Клиенты должны использовать только поддерживаемые версии сервисов, а в рамках версии — в соответствии с актуальной документацией. Поддержка версии сервиса подразумевает выбор клиентом правильной точки входа и поддержку формата данных для выбранной версии сервиса.
Для информационных сервисов допускается поддерживать только актуальную версию, для сервисов контрагентов–партнеров (IPTV, MediaLocator, Auth, Radio) рекомендуется поддерживать все существующие версии (на момент выпуска клиента).
В целях резервирования сервисов метод whereami
может выдать несколько альтернативных описаний для каждой версии сервиса, упорядоченные в рамках версии по топологической и/или географической близости;
При возникновении критических ошибок при работе с сервисом, клиент должен обратиться по адресу, сформированному на основе альтернативного описания используемой версии сервиса, а описание версии, на которой произошла ошибка, пометить как временно недоступное для обращений на непродолжительное время (не более 10 минут).
Под критическими ошибками стоит понимать:
Пример
Частичная выдача метода whereami
:
{
...
"services":
[
...
{
"type": "user_data",
"contractor":
{
"contractorId": 2
},
"name": "Данные пользователя",
"apiVersions":
[
{
"majorVersion": 1,
"location": "http://msk.api.peers.tv/userdata/1/"
},
{
"majorVersion": 1,
"location": "http://nsk.api.peers.tv/userdata/1/"
},
{
"majorVersion": 1,
"location": "http://vl.api.peers.tv/userdata/1/"
},
]
},
...
]
}
В данном случае для сервиса «Данные пользователя» выдано 3 описания версии с номером 1
. При выполнении запроса к сервису клиент должен выбрать первое описание версии, которое соответствует размещению сервиса в Московском датацентре. При возникновении критической ошибки клиент должен переключиться на следующее описание версии сервиса и повторить запрос.
Для резервирования корневого сервиса «Регистратура» предусмотрена выдача описания сервиса в методе whereami
. К данному сервису применимы описанные выше принципы резервирования сервисов.
При получении описания сервиса Регистратура, клиент должен переключиться с фиксированного на полученное описание сервиса и сохранить его для последующих обращений. Клиент должен использовать фиксированное описание сервиса Регистратура при возникновении нештатных ситуаций в работе метода whereami
при использовании выданного описания сервиса. К нештатным ситуациям относятся:
404
параметр | значение по умолчанию | значение |
---|---|---|
territory |
автоматически определенный | идентификатор территории |
contractor |
автоматически определенный | идентификатор оператора |
client |
автоматически определенный | идентификатор клиента |
Возвращает информацию о месторасположении клиента и доступных ему веб–службах контрагентов. Если заданы дополнительные параметры, абонент рассматривается, как будто он находится на указанной территории и/или провайдере.
Возможные идентификаторы клиента:
идентификатор клиента | расшифровка |
---|---|
cn.ru-android |
Приложение CN.ru (также известное как Peers) на платформе Android |
cn.ru-desktop |
Приложение CN.ru (также известное как Peers) на настольных системах |
cn.ru-web |
Сайт CN.ru |
peers.tv-android |
Приложение Peers.TV на платформе Android |
peers.tv-ios |
Приложение Peers.TV на платформе iOS |
peers.tv-stb-dune |
Приложение Peers.TV на приставке DUNE |
peers.tv-tv-lg |
Приложение Peers.TV на телевизоре LG |
peers.tv-tv-panasonic |
Приложение Peers.TV на телевизоре Panasonic |
peers.tv-tv-philips |
Приложение Peers.TV на телевизоре Philips |
peers.tv-tv-samsung |
Приложение Peers.TV на телевизоре Samsung |
peers.tv-tv-sony |
Приложение Peers.TV на телевизоре Sony |
peers.tv-web |
Сайт Peers.TV |
Формат ответа: сообщение WhereAmI
.
Замечания:
client
в дальнейшем будет защищен от подделки переводом Registry API на авторизованный доступ. Из токена доступа всегда можно получить идентификатор клиента. При этом он автоматически защищен от подделки.параметр | значение по умолчанию | значение |
---|---|---|
id |
отсутствует | список идентификаторов территорий, разделенных символом запятая (, ) |
territory |
0 , т.е. «весь мир» |
идентификатор территории, для которой запрашиваются дочерние |
contractor |
отсутствует | идентификатор контрагента, которому должны принадлежать запрашиваемые территории |
q |
отсутствует | строка, с которой начинается название территории |
parents |
0 |
количество родительских территорий, возвращаемых в запросе |
Ответ: сообщение TerritoryList
.
Замечания:
parents
параметр | значение по умолчанию | значение |
---|---|---|
area |
автоматически определенный | идентификатор ареала |
Формат ответа: сообщение AreaList
.
параметр | значение по умолчанию | значение |
---|---|---|
area |
отсутствует | идентификатор ареала |
Формат ответа: сообщение HubList
.
Если параметр area
не задан, возвращаются все хабы всех ареалов.
параметр | значение по умолчанию | значение |
---|---|---|
area |
отсутствует | идентификатор ареала |
Формат ответа: сообщение HubIsolationList
.
параметр | значение по умолчанию | значение |
---|---|---|
contractor |
отсутствует | идентификаторы контрагента |
territory |
отсутствует | идентификаторы территории |
Формат ответа: сообщение PrefixList
.
Замечания
Например, чтобы получить список префиксов контрагентов 1
и 2
, которые находятся на территории с идентификатором 6
, необходимо в данном запросе передать параметры contractor=1,2&territory=6
.
параметр | значение по умолчанию | значение |
---|---|---|
id |
отсутствует | список идентификаторов контрагентов, разделенных символом запятая (, ) |
area |
отсутствует | идентификатор ареала |
territory |
отсутствует | идентификатор территории |
q |
отсутствует | строка, содержащая часть названия или бренда контрагента |
services |
отсутствует | строковые идентификаторы сервисов, перечисленные через запятую |
Формат ответа: сообщение ContractorList
.
Замечания:
Формат запроса: сообщение KnownInfo
.
Запрос передается методом POST в формате, соответствующем суффиксу запроса.
Запрос используется для новых контрагентов, информации о которых нет в Регистратуре, а также для сбора данных от пользователей о неверных результатах определения контрагента и территорий. Данная информация сохраняется на сервере и используется в качестве справочной при создании нового контрагента на основе данных, введенных пользователем. Во время сохранения информации в базе данных также фиксируется IP адрес источника запроса, а также информация из RIPE на момент запроса.
Идентификатор устройства пользователя позволяет модератору Регистратуры отделять запросы одного и того же пользователя в случае преднамеренной отправки множества данных и/или информационного мусора.
message WhereAmI {
optional ContractorInfo contractor = 1;
repeated TerritoryInfo territories = 2;
repeated APIInfo apis = 3 [deprecated=true];
repeated Service services = 4;
optional string ipAddress = 5;
}
message APIVersion {
optional uint32 majorVersion = 1;
optional uint32 minorVersion = 2;
optional string location = 3;
optional string params = 4;
}
message APIInfo {
enum APIType {
FILMS = 0; // Films API
IPTV = 1; // телевидение провайдера
TV_RECORDS = 2; // контент Peers.TV
}
optional APIType apiType = 1;
optional string name = 2;
repeated APIVersion apiVersions = 3;
}
message Service {
enum Type {
option allow_alias = true;
FILMS = 0 [(CN.string_value) = "films"];
IPTV = 1 [(CN.string_value) = "iptv"];
PEERSTV = 2 [(CN.string_value) = "peerstv"];
PEERS = 3 [(CN.string_value) = "peers"];
TV_GUIDE = 4 [(CN.string_value) = "tv_guide"];
MEDIA_GUIDE = 4 [(CN.string_value) = "tv_guide"];
NOTIFICATION = 5 [(CN.string_value) = "notification"];
TRACKING = 6 [(CN.string_value) = "tracking"];
AUTH = 7 [(CN.string_value) = "auth"];
DATA = 8 [(CN.string_value) = "user_data"];
USERS_MERGE = 9 [(CN.string_value) = "user_data_merge"];
MEDIA_LOCATOR = 10 [(CN.string_value) = "media_locator"];
PINGER = 11 [(CN.string_value) = "pinger"];
RADIO = 12 [(CN.string_value) = "radio"];
CATALOGUE = 13 [(CN.string_value) = "catalogue"];
PROMO = 14 [(CN.string_value) = "promo"];
BYTEFOG = 15 [(CN.string_value) = "bytefog"];
PORTCHECKER = 16 [(CN.string_value) = "portchecker"];
// 17 reserved for "internet"
REGISTRY = 18 [(CN.string_value) = "registry"];
MONEY_MINER = 19 [(CN.string_value) = "money_miner"];
LAUNCHER = 20 [(CN.string_value) = "launcher"];
APPCONFIG = 21 [(CN.string_value) = "appconfig"];
PROMO_BLOCK = 22 [(CN.string_value) = "promo_block"];
}
optional Type type = 1;
optional ContractorInfo contractor = 2;
optional string name = 3;
repeated APIVersion apiVersions = 4;
optional uint32 pingInterval = 5;
optional uint32 id = 6;
}
Замечания:
APIType
задает тип API: фильмы, телевидение или записи телепередачAPIVersion.params
задает дополнительные обязательные параметры, для передачи в указанное APIWhereAmI.apis
— устарело с версии 2.6WhereAmI.services
— сервисы, доступные пользователю данного контрагента на данной территории:
Service.id
— идентификатор сервисаService.type
— код (для JSON и XML представлений — строковый идентификатор) сервисаService.contractor
— контрагент, предоставляющий услугуService.name
— название сервисаService.apiVersions
— доступные версии API сервиса, в целях обеспечения отказоусточивости для одной версии сервиса может быть выдано несколько описании версии.Service.pingInterval
- интервал времени между двумя запросами (заполняется только для сервиса PINGER
)WhereAmI.ipAddress
— строковое представление IP адреса клиента, IPv4 или IPv6message ContractorInfo {
message ContractorImage {
enum ProfileType {
SQUARE_SOLID = 1;
LAUNCHER = 2;
LAUNCHER_KIDS = 3;
PROGRESSBAR_POSITION = 4;
PROGRESSBAR_POSITION_KIDS = 5;
LAUNCHER_VERTICAL = 6;
LAUNCHER_VERTICAL_KIDS = 7;
}
optional uint32 width = 3;
optional uint32 height = 4;
optional string URL = 5;
optional ProfileType profile = 6;
}
enum PrivateOfficeIdiom {
WEB = 0;
TV = 1;
MOBILE = 2;
}
optional uint32 contractorId = 1;
optional string name = 2;
repeated ContractorImage images = 3;
optional string brandName = 4;
optional string privateOfficeURL = 5;
optional string callCenterNumber = 6;
repeated string partnerTags = 7;
repeated PrivateOfficeIdiom supportedOfficeIdioms = 8;
}
message ContractorList {
repeated ContractorInfo contractors = 1;
}
Описание атрибутов сообщения ContractorInfo
:
ContractorInfo.name
— юридическое именование контрагента (например, «ООО Вымпелком»)ContractorInfo.brandName
— имя бренда контрагента (например, «Билайн»)ContractorInfo.privateOfficeURL
— адрес личного кабинета пользователяContractorInfo.callCenterNumber
— номер телефона контакт–центраContractorInfo.partnerTags
— набор тегов, характеризующих условия партнерства. Возможные значения (список значений может расширяться):
payment
— приложение предлагает закрытый (платный) контент контрагента, независимо от наличия открытых источников от других контрагентов;no_ads
— приложение должно исключить рекламу на оплаченном контенте контрагента;ContractorInfo.supportedOfficeIdioms
— список идиом, для которых адаптирован личный кабинет:
WEB
— сайт, подразумевает ввод информации при помощи манипулятора мышь или клавиатуры;TV
— телевизор или телевизионная приставка, подразумевает ввод информации при помощи пульта дистанционного управления;MOBILE
— мобильный клиент, подразумевает ввод информации с использованием сенсорного экрана.Описание атрибутов сообщения ContractorImage
:
width
— ширина изображения в пикселях;height
— высота изображения в пикселях;URL
— адрес изображения;profile
— тип профиля изображения:
SQUARE_SOLID
— квадратный логотип со сплошной заливкой;LAUNCHER
— логотип для приставки;LAUNCHER_KIDS
— логотип для приставки в детском режиме;PROGRESSBAR_POSITION
- указатель прогрессбара для приставки;PROGRESSBAR_POSITION_KIDS
- указатель прогрессбара для приставки в детском режиме;LAUNCHER_VERTICAL
- вертикальный логотип для приставки;LAUNCHER_VERTICAL_KIDS
- вертикальный логотип для приставки в детском режиме.message TerritoryInfo {
optional uint32 territoryId = 1;
optional string name = 2;
optional uint32 parentId = 3;
optional bool isLeaf = 4;
optional TerritoryInfo parent = 5;
optional int32 timezone = 6;
repeated string content_languages = 7;
}
message TerritoryList {
repeated TerritoryInfo territories = 1;
}
Замечания:
TerritoryInfo.parent
— иерархия родительских территорийTerritoryInfo.timezone
— часовой пояс, выраженный в секундах относительно UTC, например, для Новосибирска принимает значение 25200
, а для Нью–Йорка — -18000
(по зимнему времени)TerritoryInfo.content_languages
— список кодов предпочитаемых языков содержимого, в порядке уменьшения предпочтительности, рекомендуемых для данной территории. Коды языков указываются согласно RFC3282.Замечание: для часового пояса не учитывается переход на зимнее/летнее время, а также в некоторых случаях значение может отсутствовать, например, когда для территории может быть определено более одного часового пояса (пример: Россия, СФО).
message AreaList {
repeated Area areas = 1;
}
message Area {
optional uint32 areaId = 1;
optional string name = 2;
optional uint32 cost = 3;
}
Замечания:
Area.areaId
— идентификатор ареалаArea.name
— имя ареалаArea.cost
— стоимость обмена информацией с ареалом (на 22.11.2012 указывается только для Новотелекома). Информация о стоимости является условной: за 0 принимаются те контрагенты, у которых с данным контрагентом установлен пиринг, в наличии высокая скорость обмена информацией. Клиент при скачивании данных в первую очередь соединяется с теми источниками, чья стоимость нижеmessage Hub {
optional string name = 1;
message IPAddress {
optional string hostname = 1;
optional uint32 port = 2;
}
repeated IPAddress addresses = 2;
optional IPAddress nodeAddress = 3;
optional AreaList areas = 4;
}
message HubList {
repeated Hub hubs = 1;
}
Замечания:
Hub.name
— внутреннее имя хаба, должно совпадать с его hostnameHub.addresses
— адреса хаба для DC++–клиентовHub.nodeAddress
— сетевой адрес ноды хаба для соединения в кластерmessage HubIsolationList {
message HubIsolation {
optional string fromHub = 1;
optional string toHub = 2;
enum TTHSearch {
NONE = 0;
WITHPRIO = 1;
FULL = 2;
}
optional TTHSearch tthSearch = 3;
optional bool textSearch = 4;
optional bool u2u = 5;
}
repeated HubIsolation hubIsolations = 1;
}
Замечания:
fromHub
к хабу с именем toHub
)tthSearch
, textSearch
и u2u
соответствуют таковым конфигурации ноды кластераmessage PrefixList {
message Prefix {
optional string CIDR = 1;
optional string NAT = 2;
optional bool peersAccess = 3;
optional ContractorInfo contractor = 4;
repeated TerritoryInfo territories = 5;
}
repeated Prefix prefixes = 1;
}
Замечания:
CIDR
и NAT
задаются в формате A.B.C.D/Y
или A.B.C.D
(в случае одиночного IP адреса)NAT
может присутствовать только для частных адресов, задает их трансляциюpeersAccess
отвечает за наличие доступа в Пирс абонентам указанного префиксаcontractor
— информация о контрагенте префикса. Гарантируется передача только идентификатора контрагентаterritories
— территории, за которыми закреплен префикс. Гарантируется передача только идентификатора территории. Если за префиксом не закреплена территория, возвращается список территорий контрагентаmessage KnownInfo {
optional uint32 contractorId = 1;
optional string contractorName = 2;
optional uint32 territoryId = 3;
optional string territoryName = 4;
optional uint32 parentTerritoryId = 5;
optional string iptvPlaylistAddress = 6;
optional string uid = 7;
}
Замечания:
contractorId
— идентификатор контрагента известный нам и выбранный пользователемcontractorName
— название контрагента (оператора связи)territoryId
— идентификатор территории известный нам и выбранный пользователемterritoryName
— название территорииparentTerritoryId
— идентификатор родительской территории (если задана, то должна присутствовать в Регистратуре)iptvPlaylistAddress
— адрес списка каналов оператора связиuid
— идентификатор устройства пользователя, с которого совершен запросknownInfo
.prefixes
добавлена информация о наличии доступа в Пирс.knownInfo
.whereAmI
добавлен IP адрес, видимый сервером.4
по 6
).territories
добавлен способ получения полной информации об определенном количестве родительских территорий.7
по 9
).id
в метод contractors
для получения информации о контрагентах по их идентификаторам.TerritoryInfo
добавлена информация о часовом поясе при помощи атрибута timezone
.id
в метод territories
для получения информации о территориях по идентификаторам.services
из метода territories
.callCenterNumber
в сообщение ContractorInfo
.whereami
.knownInfo
помечен как устаревший;contractors
.parentId
из сообщения TerritoryInfo
.Service
.services
метода territories
;services
метода contractors
.ContractorInfo
добавлен список идиом, поддерживаемых личным кабинетом контрагента.sizeType
, osType
из сообщения ContractorInfo
помечены устаревшими;ContractorInfo
добавлен новый атрибут profile
;sizeType
, osType
из сообщения ContractorInfo
удалено;partnerTags
только к контрагенту, к сети которого осуществлено подключение;no_ads
для атрибута partnerTags
из ContractorInfo
.PROGRESSBAR_POSITION
и PROGRESSBAR_POSITION_KIDS
в сообщениях ContractorImage
LAUNCHER_VERTICAL
и LAUNCHER_VERTICAL_KIDS
в сообщениях ContractorImage