Перейти к содержанию

API для DVR и записи потоков

Описание

В этом разделе описаны методы API для создания, удаления и изменения настроек DVR и записи потоков.

Общие сведения

  • Обязательные заголовки: CDN-AUTH-TOKEN (авторизационный токен, см. Авторизация)
  • Content-Type успешного ответа: application/json
  • Под ID ресурса понимается ID RTMP/RTSP-publish ресурса
  • Используемые сокращения:
Сокращение Полное название
ИП Исходный плейлист

Общие ошибки

В ответ на любой из запросов может вернуться одна из следующих ошибок:

Код ответа Content-Type Тело ответа Описание
400 text/plain Invalid path Неверный путь
401 text/plain Invalid token Не передан заголовок с токеном
403 text/plain Invalid account Указан неверный аккаунт
404 text/plain Not found Неверный URL
405 text/plain Method is not allowed Отказано в доступе к действию
500 text/html - Внутренняя ошибка сервера

Пример запроса

curl 'https://api.cdnvideo.ru/app/dvr/v1/testaccount/record'

Пример неуспешного ответа

Invalid token

Получить настройки всех записей

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record

  • Тип запроса: GET
  • Доступные querystring-параметры:

    Название Допустимые значения Описание
    resource_id ID ресурса ID ресурса, к которому применены настройки
    all Присутствие/отсутствие в списке параметров Вернуть все инстансы записей, в т.ч. закончившиеся и уже начавшиеся
    extra_fields Список строк, разделённый запятыми Вернуть дополнительные поля
  • Доступные значения параметра extra_fields:

    Значение Описание
    status Статус записи (wait/progress/finish/error)
  • Возможные коды ответа:

    Код ответа Данные ответа Описание
    200 Список данных о настройках -
  • Формат данных о настройках:

    Ключ Описание
    id Идентификатор
    resource_id ID ресурса
    account_name Название аккаунта
    source_domain Домен ИП
    source_path Путь ИП
    stream_type Вид трансляции
    launch_type Способ запуска записи
    stop_timeout Timeout ожидания потока для записи (в секундах)
    storage_time Время хранения файла записи (в днях)
    dvr_enabled Включен ли DVR
    dvr_window Окно DVR (в секундах)
    smil Является ли исходных плейлист SMIL-ом
    qualities Объект с ссылками и названиями качеств ИП
    records Список данных о записях
    path Путь, по которому сохраняются файлы записи
  • Формат данных о записи:

    Ключ Описание
    start Дата и время начала записи
    stop Дата и время окончания записи
    init_path Путь, по которому сохранялся файл записи

    Формат даты и времени начала и окончания записи

    Значение даты и времени выдаётся в формате YYYY-MM-DDThh:mm:ssZ в UTC.
    Пример: 2021-12-30T12:30:05Z

Пример запроса

curl 'https://api.cdnvideo.ru/app/dvr/v1/testaccount/record' -H "CDN-AUTH-TOKEN: $TOKEN"

Пример успешного ответа

[
 {
    "id": "a9bdcf5f-4e9e-42b3-bfсd-35469d66a44f",
    "resource_id": "6434361230573122384_fxqe0wa6vvv",
    "account_name": "test_account",
    "source_domain": "https://prefix.a.trbcdn.net",
    "source_path": "/livemaster/70xs4gn2s0_zv2dm9kt929/playlist.m3u8",
    "stream_type": "short",
    "launch_type": "button",
    "stop_timeout": 1800,
    "storage_time": 3,
    "dvr_enabled": true,
    "dvr_window": 43200,
    "smil": false,
    "qualities": null,
    "records": [
      {
        "start": "2022-01-01T13:26:26Z",
        "stop": "2022-01-01T15:27:34Z",
        "init_path": "/records/20220101T121112.m3u8"
      },
      {
        "start": "2022-01-01T16:13:52Z",
        "stop": "2022-01-01T17:14:48Z",
        "init_path": "/records/20220101T121112.m3u8"
      }
    ],
    "path": "/records/20220101T121112.m3u8"
  }
]

Создать настройки записи

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record

  • Тип запроса: PUT
  • Content-Type тела запроса: application/json
  • Доступные параметры:

    Название Обязательный Значение по умолчанию Допустимые значения Описание
    resource_id Нет - ID ресурса ID ресурса, для которого создаются настройки записи
    stream_name Да - Строка Название потока
    stream_type Да - Вид трансляции Вид трансляции, для которой настраивается запись
    source Да - URL URL исходного плейлиста
    launch_type Да - Способ старта Способ старта записи
    schedule Нет - Список объектов расписания Список объектов запланированных записей
    path Нет /records/{now}.m3u8 Путь в хранилище Путь в хранилище для сохранения записи
    stop_timeout Нет 1800 Целое число (секунды) Длина timeout-а ожидания потока в секундах
    storage_time Нет 3 Целое число (дни) Количество дней хранения файла записи после её завершения
    dvr_enabled Нет false Boolean Флаг, определяющий наличие возможности DVR в плеере
    dvr_window Нет 43200 Целое число (секунды) Окно записи
    smil Нет false Boolean Флаг, определяющий, является ли ИП master-плейлистом
    qualities Нет - Объект Объект с ссылками и названиями качеств ИП
  • Возможные значения вида трансляции:

    Значение Описание
    short Краткосрочная трансляция (до 12 часов)
    long Постоянная трансляция
  • Возможные значения способов старта:

    Значение Описание
    stream_start Старт по публикации потока
    button Старт по нажатию кнопки (запросу)
    schedule* Старт в заранее определённое время

    Обратите внимание

    * - данный способ доступен только для записи краткосрочных трансляций

  • Возможные коды ответа:

    Код ответа Данные ответа Описание
    201 record_id Настройки успешно созданы
    409 - Настройки записи для ИП уже созданы и активны
    422 Данные об ошибках Ошибка в значениях параметров

Пример запроса

curl 'https://api.cdnvideo.ru/app/dvr/v1/testaccount/record' -X PUT --data '{"stream_name": "6t48oq7ts_i12f41tnkfs_smil", "stream_type":"short", "path":"/records/20220101T175729.m3u8", "smil":true, "qualities": {"https://prefix.a.trbcdn.net/livemaster/6t48oq7ts_i12f41tnkfs_tcode360p/playlist.m3u8": "360p", "https://prefix.a.trbcdn.net/livemaster/6t48oq7ts_i12f41tnkfs_tcode480p/playlist.m3u8": "480p", "https://prefix.a.trbcdn.net/livemaster/6t48oq7ts_i12f41tnkfs_tcode720p/playlist.m3u8": "720p"}, "launch_type": "button", "stop_timeout": 1800, "dvr_enabled": false, "schedule": [], "storage_time": 3, "resource_id": "9778349385416447311_hl4ceseblgw", "source": "https://prefix.a.trbcdn.net/livemaster/xlepd_live-5nls7s5gi2.smil/playlist.m3u8"}' -H "Content-Type: application/json" -H "CDN-AUTH-TOKEN: $TOKEN"

Пример успешного ответа

{
  "id": "b1795283-c88b-43ad-a28b-0659389e82df"
}

Получить настройки записи конкретного потока

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record/<record_id>

  • Тип запроса: GET
  • Доступные querystring-параметры:

    Название Допустимые значения Описание
    resource_id ID ресурса ID ресурса, к которому применены настройки
    all Присутствие/отсутствие в списке параметров Вернуть все инстансы записей, в т.ч. закончившиеся и уже начавшиеся
    extra_fields Список строк, разделённый запятыми Вернуть дополнительные поля
  • Доступные значения параметра extra_fields:

    Название Описание
    status Статус записи (wait/progress/finish/error)
  • Возможные коды ответа:

    Код ответа Данные ответа Описание
    200 Список данных о настройках -
  • Формат данных о настройках:

    Ключ Описание
    id Идентификатор
    resource_id ID ресурса
    account_name Название аккаунта
    source_domain Домен ИП
    source_path Путь ИП
    stream_type Вид трансляции
    launch_type Способ запуска записи
    stop_timeout Timeout ожидания потока для записи (в секундах)
    storage_time Время хранения файла записи (в днях)
    dvr_enabled Включен ли DVR
    dvr_window Окно DVR (в секундах)
    smil Является ли исходных плейлист SMIL-ом
    qualities Объект с ссылками и названиями качеств ИП
    records Список данных о записях
    path Путь, по которому сохраняются файлы записи
  • Формат данных о записи:

    Ключ Описание
    start Дата и время начала записи
    stop Дата и время окончания записи
    init_path Путь, по которому сохранялся файл записи

    Формат даты и времени начала и окончания записи

    Значение даты и времени выдаётся в формате YYYY-MM-DDThh:mm:ssZ в UTC.
    Пример: 2021-12-30T12:30:05Z

Пример запроса

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "CDN-AUTH-TOKEN: $TOKEN"

Пример успешного ответа

[
  {
    "id": "089ec628-1e96-482e-a43d-02537b6f8f8e",
    "resource_id": "2415236563435151586_izxvl4r88pc",
    "account_name": "testaccount",
    "source_domain": "https://prefix.a.trbcdn.net",
    "source_path": "/livemaster/dxsbm_live-sj74f3ih5co.smil/playlist.m3u8",
    "stream_type": "short",
    "launch_type": "schedule",
    "stop_timeout": 1800,
    "storage_time": 87,
    "dvr_enabled": false,
    "dvr_window": 43200,
    "smil": true,
    "qualities": {
      "https://prefix.a.trbcdn.net/livemaster/bkxw4xqxna_7vn4752dq4_tcode360p/playlist.m3u8": "360p",
      "https://prefix.a.trbcdn.net/livemaster/bkxw4xqxna_7vn4752dq4_tcode480p/playlist.m3u8": "480p",
      "https://prefix.a.trbcdn.net/livemaster/bkxw4xqxna_7vn4752dq4_tcode720p/playlist.m3u8": "720p"
    },
    "records": [],
    "path": null
  }
]

Действия с настройками записи

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record/<record_id>

  • Тип запроса: PATCH
  • Content-Type тела запроса: application/json
  • Доступные параметры:

    Название Обязательный Значение по умолчанию Допустимые значения Описание
    action Нет change Строка действия Название действия, которое необходимо осуществить над настройками
  • Возможные коды ответа:

    Код ответа Данные ответа Описание
    200 - Действие успешно совершено
    400 - Запись с указанным record_id не найдена
    422 Данные об ошибках Ошибка в значениях параметров

Изменение настроек записи

  • action: change
  • Доступные параметры:

    Название Обязательный Значение по умолчанию Допустимые значения Описание
    stream_type Нет - Вид трансляции Вид трансляции, для которой настраивается запись
    launch_type Нет - Способ старта Способ старта записи
    schedule Нет - Список объектов расписания Список объектов запланированных записей
    storage_time Нет - Целое число (дни) Количество дней хранения файла записи после её завершения
    dvr_enabled Нет - Boolean Флаг, определяющий наличие возможности DVR в плеере

Пример запроса

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"stream_type": "long", "dvr_enabled": true}' -H 'Content-Type: application/json'

Старт записи

  • action: start

Пример запроса

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "start"}' -H 'Content-Type: application/json'

Остановка записи

  • action: stop

Пример запроса

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "stop"}' -H 'Content-Type: application/json'

Деактивация настроек записи

  • action: deactivate

Пример запроса

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "deactivate"}' -H 'Content-Type: application/json'