Данный документ создан для унификации способов получения информации о местах расположения контента из медийных каталогов, таких, как каталог фильмов или расписание выпусков телепередач канала.
Логика взаимодействия клиентского ПО, серверов Регистратуры и серверов Оператора-вещателя подразумевает согласованность идентификаторов выпусков телепрограмм, фильмов, серий сериалов и т.д. (далее в тексте – идентификаторы элементов медийного каталога). В настоящем документе не описывается механизм согласования идентификаторов.
В этом документе используются термины и определения, описанные в документах «О программных интерфейсах сервисов Инетры» и «Термины и определения».
API подразумевает доступ только аутентифицированного пользователя (возможно, анонимного), пользующегося авторизованным приложением. Таким образом здесь закладывается возможность внедрения системы оплаты для получения контента.
В следствие чего данное API должно быть доступно только по HTTPS. Формат запроса:
https://<path_to_api>/<api_version>/<method>.<format>?[params]
Где:
path_to_api
— путь до API, полученный в Регистратуреapi_version
— мажорная версия API (должна быть равна 1
)method
— метод, который производится над элементомformat
— формат упаковки данных:
json
— JSONprotobuf
— Google Protocol BuffersЗначения всех параметров перед передачей серверу необходимо кодировать для предотвращения неоднозначной интерпретации так, как это рекомендуется в RFC3986.
Коды ответов сервера должны соответствовать стандартным кодам HTTP-ответов для соответствующих ситуаций. Если по запросу не найдено никакой информации, сервер должен вернуть нормальный (код 200) пустой ответ.
Для аутентификации пользователя клиент должен передать полученный ранее токен доступа, выданный службой контрагента, реализующей Auth API, по схеме аутентификации в соответствии с типом токена.
Для авторизации по типу токена «Bearer» рекомендуется использовать HTTP заголовок Authorization
, пример:
Authorization: Bearer 18dasd81230dah12032
Если в рамках контрагента не объявлена служба, реализующая Auth API, то клиент должен обратиться к API без указания токена доступа. Если будет возвращен ответ с кодом 401
, то клиент должен рассматривать службу Media Locator как временно недоступную.
При получении информации о местах расположения контента из медийных каталогов в сообщении Rip
могут быть переданы условия доступа:
status
): разрешительный, запретительный, требующий оплаты и т.д.allowed_till
, pending_till
): ознакомительный период, длительность подписки, длительность применения прав доступа к оборудованию.Ниже описана интерпретация совместного использования атрибутов условного доступа в виде сочетаний характера и параметров доступа:
ACCESS_DENIED
— доступ запрещен:
allowed_till
— доступен режим пробного ознакомления в течении указанного времени (указывается в секундах).ACCESS_ALLOWED
— доступ разрешен:
allowed_till
— доступ разрешен до указанного времени — срок действия подписки, время указывается в формате Unix time.ACCESS_PURCHASED
— доступ разрешен (оплачен):
allowed_till
— доступ разрешен до указанного времени — срок действия подписки, время указывается в формате Unix time.ACCESS_PENDING
— доступ разрешен, но вещание по ряду причин пока недоступно (осуществляется применение прав доступа к оборудованию, ожидание подтверждения оплаты и т.д.):
pending_till
— доступ будет возможен после указанного времени, время указывается в формате Unix time.В рассмотренных случаях для атрибута allowed_till
HTTP ответ с кодом 401
в процессе воспроизведения записи должен быть интерпретировать как окончание подписки.
В остальных, неуказанных выше, случаях атрибуты pending_till
, allowed_till
должны быть проигнорированы клиентом.
Интерпретации указанного сервером времени производится с учетом текущего времени сервера, переданного им в ответе в HTTP заголовке Date
.
При обращении к сервису MediaLocator клиент может сообщить дополнительную информацию, которая позволит сформировать ответ, содержащий информацию о местах расположения только поддерживаемого клиентом контента.
Клиент может передать список поддерживаемых функций при помощи HTTP заголовка Client-Capabilities
. Возможные значения:
adult_content
— контент для взрослых;paid_content
— платный контент (закрытые записи);bytefog
— установлен плагин Bytefog, поддерживающий воспроизведение записей.HTTP заголовок Client-Capabilities
задается грамматикой в форме ABNF (см. RFC2616):
Client-Capabilities = "Client-Capabilities" ":" 1#feature
feature = token
Замечание:
token
определено в RFC2616 как последовательность символов, кроме управляющих символов и разделителей.Пример задания заголовка
Client-Capabilities: paid_content,adult_content
Если для элемента медийного каталога можно установить связь с телеканалом, то рекомендуется при обращении к MediaLocator API учитывать признак наличия архива у источников канала контрагента. Если у контрагента нет источников вещания канала с признаком наличия архива, то вероятно, что для элемента каталога для того же канала не будут присутствовать записи.
Клиент не должен запрашивать информацию о местоположении контента для элементов медийного каталога, которые являются еще не вышедшими в эфир выпусками телепередач.
параметр | тип | смысл |
---|---|---|
token |
строка |
токен доступа, может быть выдан службой аутентификации контрагента. (устарело с версии 1.3.2) |
Параметр token
не указывается, если контрагент не имеет службы аутентификации, реализующего Auth API.
Для каждого метода API предусмотрены стандартные коды ответов (RFC2616). Ниже описана интерпретация некоторых кодов:
200
— запрос успешно обработан400
— некорректно составлен запрос401
— требуется аутентификация:
403
— доступ запрещен:
Если аутентификация возможна, то для кодов 401
, 403
должен быть передан HTTP заголовок WWW-Authenticate
с указанием ожидаемой схемы аутентификации и дополнительнной информации (если применимо). Например, для схемы «Bearer» может быть указан дополнительный атрибут error
со значением:
invalid_token
— передан некорректный, просроченный или отозванный токен доступа (код 401
);insufficient_scope
— запрос требует более высоких привилегий, чем те, которыми обладает токен доступа (код 403
).sources
— Получение ссылок на источники вещания элементов каталогаПараметр | Значение по умолчанию | Описание |
---|---|---|
id |
отсутствует | Список логических идентификаторов элементов каталога (через запятую) |
Важно не путать элемент медийного каталога, например, выпуск телепередачи (telecast), и экземпляр записи выпуска телепередачи или фильма (rip). В параметре id
передается список идентификаторов элементов каталога.
Формат ответа: сообщение SourcesReply
.
Замечания:
SourceReply
с запрошенным catalogue_item_id
означает отсутствие информации об элементе каталога с указанным идентификаторомSourceReply
поля rips
или отсутствие элементов в нем означает присутствие элемента каталога с указанным идентификатором, но отсутствие рипов для негоПример получения ссылки на источник нишевого контента:
{ «replies»: [ { «catalogue_item_id»: 405623041, «niche»: [ { «video_id»: «1952cca28b042a3dc747f2b039beb61928d080cd», «video_url»: «https://storage.yandexcloud.net/inetra-test/fulm2/fulm/playlist.m3u8» } ] } ] }
timeshift
— получение ссылки на источник вещания со смещением от эфирногоПараметр | по умолчанию | описание |
---|---|---|
stream_id |
отсутствует | идентификатор источника вещания (из IPTV) |
offset |
отсутствует | смещение в секундах от эфира (положительное целое) |
start_over |
отсутствует | признак перехода на начало эфирной передачи (логическое) |
Позволяет получить ссылку на источник вещания со смещением от эфира. В целях оптимизации нагрузки сервер может переопределить запрошенное смещение, в этом случае в ответе будет указано фактическое смещение, отличное от запрошенного.
Замечания:
stream_id
— обязательный параметр;offset
и start_over
не могут использоваться совместно, но хотя бы один должен указан при обращении к методу;Рекомендуется использовать параметр start_over
для реализации функции «Начать с начала».
Формат ответа: TimeshiftReply
.
Запрос
GET /medialocator/1/timeshift.json?stream_id=232&start_over=true HTTP/1.1
Host: api.peers.tv
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Ответ
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"uri":"http://hls.peers.tv/timeshift/5kanal/16/playlist.m3u8?offset=130&token=2YotnFZFEjr1zCsicMWpAA",
"offset": 130
}
message SourceReply {
optional int64 catalogue_item_id = 1;
repeated Rip rips = 2;
repeated Rip trailers = 3;
repeated VOD vod = 4;
}
message SourcesReply {
repeated SourceReply replies = 1;
}
message VOD {
optional VODType type = 1;
optional string video_id = 2;
optional string video_url = 3;
optional DModel distribution_model = 4;
optional string auth_url = 5;
optional string stream_url = 6;
enum VODType {
RUTUBE= 1;
TVIGLE = 2;
IVI = 3;
MEGOGO = 4;
}
enum DModel {
FREE= 0;
AVOD = 1;
SVOD = 2;
TVOD = 3;
}
}
Замечания:
rips
— содержит описания рипов для элемента каталогаtrailers
— содержит описания трейлеров для элемента каталогаlocations
— источники вещания контента VodVOD
— информация от VOD контенте, такая как
video_id
— уникальный идентификатор фильмаtype
— поставщик VOD контентаvideo_url
- ссылка для воспроизведения в плеере (необязательна)distribution_model
- модель распространения контента. FREE - бесплатно, AVOD - после просмотра рекламы, SVOD - по подписке, TVOD - покупка конкретной единицы контентаauth_url
- ссылка для получения токена клиентом для последующего запроса контента (для Megogo)stream_url
- ссылка для получения контента клиентом, в запросе используется токен из ответа на запрос auth_url (для Megogo)enum RipDefinition {
SD = 0;
HD = 1;
}
enum RipStatus {
ACCESS_ALLOWED = 200;
ACCESS_PENDING = 220;
ACCESS_PURCHASED = 221;
ACCESS_DENIED = 403;
}
enum StreamingType {
PROTOCOL_DEFAULT = 0;
HTTP_LIVE_STREAMING = 1;
}
message Rip {
optional int64 id = 1;
repeated RipPart parts = 2;
repeated string snapshots = 3;
optional RipDefinition definition = 4;
optional RipStatus status = 5 [default = ACCESS_ALLOWED];
optional StreamingType streaming_type = 6 [default = PROTOCOL_DEFAULT];
optional int64 allowed_till = 7;
optional int64 pending_till = 8;
optional bool ad_targeting = 9;
}
Замечания:
id
— идентификатор рипаparts
— информация о частях рипа, передается в том же порядке, в котором должны быть показаны при воспроизведенииsnapshots
— массив, содержащий ссылки (URL) на стоп–кадры рипаdefinition
— качество рипа (SD, HD)status
— статус доступности рипа (доступны сразу либо все части, либо ни одной)streaming_type
— тип вещания:
PROTOCOL_DEFAULT
— определено протоколом доставки (значение по умолчанию);HTTP_LIVE_STREAMING
— вещание по стандарту Http Live Streaming.allowed_till
— время планируемого отключения доступа к вещанию;pending_till
— время в формате Unix–time, до которого будет производится настройка прав доступа, после истечения данного времени запись будет доступна для воспроизведения.ad_targeting
- признак наличия in-stream рекламы, для которой доступны таргетингиИнтерпретация атрибутов status
, allowed_till
, pending_till
описана в разделе «Интерпретация прав доступа»
message RipPart {
optional ContainerInfo container_info = 1;
repeated Location locations = 2;
optional uint32 start_position = 3 [default=0, deprecated=true];
optional uint32 end_position = 4 [deprecated=true];
optional float playback_start_time = 5 [default=0];
optional float playback_end_time = 6;
}
Замечания:
container_info
— описание контейнераlocations
— описание источников вещания части рипа. Несколько источников может быть передано для осуществления балансировки нагрузкиplayback_start_time
— время в секундах, с которого необходимо начать воспроизведение части рипа. Если отсутствует, воспроизведение начинать с началаplayback_end_time
— время в секундах, на котором необходимо останавливать воспроизведение части рипа. Если отсутствует, воспроизведение производить до конца всех дорожекstart_position
— время в секундах, с которого необходимо начинать воспроизведение части рипа. Если отсутствует, воспроизведение начинать с началаend_position
— время в секундах, на котором необходимо останавливать воспроизведение части рипа. Если отсутствует, воспроизведение производить до конца всех дорожекДля получения точных меток начала и остановки воспроизведения рекомендуется использовать атрибуты playback_start_time
, playback_end_time
, значения атрибутов — неотрицательные.
message ContainerInfo {
optional string format = 1;
optional string format_profile = 2;
repeated TrackInfo tracks = 3;
}
Замечания:
format
— формат контейнера, из библиотеки MediaInfoformat_profile
— профиль формата контейнера, из библиотеки MediaInfotracks
— информация о дорожках контейнераenum TrackType {
VIDEO = 0;
AUDIO = 1;
SUBTITLE = 2;
}
message TrackInfo {
optional TrackType type = 1;
optional string codec = 2;
optional string format = 3;
optional string format_profile = 4;
optional string language = 5;
optional uint32 duration = 6;
optional uint32 bitrate = 7;
repeated Location locations = 8;
// for video
optional uint32 width = 9;
optional uint32 height = 10;
optional float fps = 11;
// for audio
optional int32 channel_count = 12;
}
Замечания:
type
— тип дорожки: видео, аудио или субтитрыcodec
— кодек, из библиотеки MediaInfoformat
— формат дорожки, из библиотеки MediaInfoformat_profile
— профиль формата дорожки, из библиотеки MediaInfolanguage
— код языка дорожки по стандарту ISO 639–1duration
— продолжительность дорожки, в секундахbitrate
— битрейт дорожкиlocations
— список альтернативных источников вещания дорожкиwidth
— ширина изображения, в пикселяхheight
— высота изображения, в пикселяхfps
— количество кадров в секундуchannel_count
— количество каналовmessage Location {
optional string uri = 1;
optional uint32 usage_weight = 2;
}
Замечания:
uri
— URI источника вещанияusage_weight
— вес источника вещания, используется клиентом для определения вероятности использования источника вещания. Вероятность использования указанного URI равна весу источника, деленного на сумму всех источников вещания
Например, имеются следующие источники вещания с весами 0, 1, 2, 3 и 4, то вероятность использования каждого из них будет 0, 0.1, 0.2, 0.3 и 0.4 соответственно.message TimeshiftReply {
optional string uri = 1;
optional uint32 offset = 2;
}
Замечания:
uri
— URI источника вещанияoffset
— фактическое смещение от эфирного вещанияstreaming_type
.token
теперь является обязательным, только при наличии соответствующего OAuth2–сервиса;PAYMENT_REQUIRED
из перечисления RipStatus
;ACCESS_PENDING
для перечисления RipStatus
;allowed_till
, pending_till
.token
перенесен в раздел «Общие параметры запросов».token
помечен как устаревший.streaming_type
.start_position
,end_position
помечены устаревшими, взамен добавлены атрибуты playback_start_time
,playback_end_time
для поддержки дробных значений.WWW-Authenticate
в случае ошибок запроса с кодами ответа 401
, 403
.ACCESS_PURCHASED
для оплаченных записей.bytefog
.timeshift
для получения ссылки на источник вещания со смещением от эфирного.ad_targeting
для рипа.VOD
, содержащее информацию о источниках VOD контента.SourcesReply
для VOD контента.