Работа с DVR через API
Flussonic предоставляет набор методов для работы с DVR через API. Это позволяет автоматизировать работу с DVR в рамках вашей инфраструктуры. Эта статья посвящена обзору методов API и примерам их использования для управления DVR и работы с ним.
Обзор API-методов для работы с DVR
Flussonic позволяет получать данные о записанном потоке, настраивать запись архива и т.д. Часть команд доступна только администратору, а другая часть доступна также и пользователям.
Администратор может изменять настройки архива или сохранить его в виде файла на диск. Пользователи могут запрашивать информацию о потоке, JPEG-скриншоты и т.п.
Ниже вы можете увидеть команды для работы с DVR через API для администраторов и пользователей.
Команды, доступные только администратору
- Настроить DVR для потока
- Защита участков DVR от удаления
- Фрагменты записей DVR
- Экспорт фрагмента записи архива в виде MP4-файла
- Информация об использовании DVR
Команды, доступные пользователям
- Получение JPEG-скриншотов из архива по времени UTC
- Генерация JPEG-скриншотов по запросу
- Получение видео-скриншотов
- Скачивание фрагмента записи архива в виде файла MP4 или MPEG-TS
Команды, доступные только администратору
Запросы, доступные только администратору, должны быть авторизованы. Администратору необходимо передать basic-токен или bearer-токен при отправке запроса. В примерах ниже мы будем использовать простую авторизацию с указанием имени пользователя и пароля для входа на сервер Flussonic, разделённых двоеточием, вида username:password
.
Настройка DVR для потока
Для настройки DVR для потока используйте запрос PUT /streamer/api/v3/streams/{name} и передайте необходимую конфигурацию в формате JSON:
curl -u username:password -X PUT "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME" \
> -H "Content-Type: application/json" \
> --data '{"dvr": {"root":"/storage","expiration":3600}}'
, где:
/storage
— директория, где будут храниться записи DVR,3600
— глубина архива, или период хранения записей, после которого они будут удалены из директории.
Чтобы изменить настройки DVR для потока, используйте такой же запрос:
curl -u username:password -X PUT "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME" \
> -H "Content-Type: application/json" \
> --data '{"dvr": {"root":"/storage","expiration":172800}}'
, где:
/storage
— директория, где будут храниться записи DVR,172800
— глубина архива, или период хранения записей, после которого они удаляются из директории.
Защита участков DVR от удаления
В Flussonic реализован механизм защиты определенных частей архива от автоматического удаления. Для защиты записей используются эпизоды — набор метаданных об участке архива. Информация об эпизодах хранится в Flussonic Central и запрашивается при очистке архива. Flussonic Media Server не удаляет участки архива с эпизодами до тех пор, пока:
- На диске не становится критически мало места в байтах или процентах.
- Глубина записи эпизода не превышает своего предела episodes_expiration.
Note
Если вы удалите поток с эпизодами или внешняя база данных с эпизодами станет недоступна, Flussonic продолжит хранить участки DVR с эпизодами до окончания периода episode_expiration, чтобы защитить данные от внезапного удаления.
Чтобы использовать приведенные ниже вызовы API, установите и настройте Flussonic Central.
Note
Вы можете использовать для работы с эпизодами собственный конфигурационный бэкенд вместо Flussonic Central, см. Управление эпизодами.
Чтобы создать или обновить эпизод, отправьте в Flussonic Central запрос PUT /streamer/api/v3/episodes/{episode_id}.
curl -u username:password --request PUT 'http://127.0.0.1:9019/streamer/api/v3/episodes/1' \
-H "Content-Type: application/json" \
--data '{"episode_id": 1,"media": "test-879c595839","opened_at": 1686808712,"updated_at": 1686808712,"closed_at": 1686823112}'
Когда надобность в хранении защищенного участка отпадет, удалите эпизод DELETE /streamer/api/v3/episodes/{episode_id}.
curl -u username:password --request DELETE 'http://127.0.0.1:9019/streamer/api/v3/episodes/1' \
Note
Обратите внимание, что логин и пароль, которые нужно использовать для авторизации API-запросов к Flussonic Central, отличаются от логина и пароля администратора Flussonic. Логин и пароль Central указаны в файле /etc/central/central.conf
. Токен авторизации — это строка username:password
, закодированная в base64.
Вы также можете просматривать список имеющихся эпизодов и информацию о конкретном эпизоде. Соответствующие запросы отражены в схеме API.
Подробнее об использовании API Flussonic Central читайте в статье Flussonic Central API.
Фрагменты записей DVR
Flussonic может вернуть список временных интервалов фрагментов записей и информацию о времени начала фрагмента и продолжительности фрагмента в каждом из них.
Чтобы получить список временных интервалов фрагментов записей DVR, используйте запрос GET /streamer/api/v3/streams/{name}/dvr/ranges, где {name}
— имя потока:
curl -u username:password http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/ranges
Note
Время в интервалах возвращается в формате Unix-времени.
Если вам необходимо удалить фрагмент архива с определенным интервалом вручную, используйте запрос DELETE /streamer/api/v3/streams/{name}/dvr/ranges, где {name}
— имя потока:
curl -u username:password -X DELETE http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/ranges \
> -H 'Content-Type: application/json' \
> --data '{"from":1675326686, "duration":7200}'
, где:
1675326686
— время начала фрагмента архива в формате Unix-времени,7200
— продолжительности фрагмента в секундах.
Экспорт фрагмента записи архива в виде MP4-файла
Администратор может экспортировать фрагменты архива в виде MP4-файлов и хранить их на диске сервера или в хранилище Amazon S3. Чтобы скачать фрагмент архива в виде MP4-файла, используйте запрос POST /streamer/api/v3/streams/{name}/dvr/export, где {name}
— имя потока.
Обязательные параметры:
{from}
— время начала фрагмента записи архива в формате Unix-времени,{duration}
— продолжительность фрагмента записи в секундах,{path}
— путь до MP4-файла на диске сервера или хранилище Amazon S3,
указываются в строке запроса.
Экспорт фрагмента записи архива в виде MP4-файла на диск сервера
Чтобы экспортировать фрагмент архива в виде MP4-файла и сохранить его на диске сервера, используйте команду ниже:
curl -u username:password -X POST "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export?from=1675159800&duration=4200&path=/home/example/file.mp4"
Здесь:
from=1675159800
— время начала фрагмента записи архива в формате Unix-времени,duration=4200
— продолжительность фрагмента записи в секундах,path=/home/example/file.mp4
— путь до MP4-файла на диске сервера.
Указанный фрагмент архива будет сохранен в виде MP4-файла file.mp4
в каталоге /home/example
.
Caution
Будьте осторожны при указании имени файла, чтобы не затереть существующие.
Экспорт фрагмента записи архива в виде MP4-файла в Amazon S3
Чтобы экспортировать фрагмент записи архива в виде MP4-файла и сохранить его в хранилище Amazon S3, используйте следующую команду:
Caution
При формировании ссылки для экспорта фрагмента архива в хранилище Amazon S3 вам необходимо URL-кодирование. URL-кодирование преобразовывает символы параметров в строке запроса таким образом, чтобы они корректно передавались через Интернет. Для этого используйте параметр --data-urlencode
в команде curl
как в примере ниже.
curl -u username:password -X POST --data-urlencode "from=1675159800" --data-urlencode "duration=4200" --data-urlencode "path=s3://AWS_ACCESS_ID:AWS_SECRET_KEY@s3.amazonaws.com/bucket/path/to/file.mp4" http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export
Здесь:
from=1675159800
— время начала фрагмента записи архива в формате Unix-времени,duration=4200
— продолжительность фрагмента записи в секундах,path=s3://AWS_ACCESS_ID:AWS_SECRET_KEY@s3.amazonaws.com/bucket/path/to/file.mp4
— путь до MP4-файла в хранилище Amazon S3 с данными вашей учётной записи: идентификатором ключа доступаAWS_ACCESS_ID
и секретным ключом доступаAWS_SECRET_KEY
.
Можно также сохранять и метаданные MP4-файла, добавив meta=true
в строку запроса:
curl -u username:password -X POST "http://FLUSSONIC-IP/streamer/api/v3/streams/STREAM_NAME/dvr/export?from=1675159800&duration=4200&path=/home/example/file.mp4&meta=true"
Метаданные будут записаны в атом udta.meta.ilst.data
.
Информация об использовании DVR
Знать информацию об использовании DVR может быть полезно.
В чём ценность этой информации? Для чего она нужна?
- определение дискового пространства, необходимого для записи и хранения потоков;
- построение распределений трафика по глубине архива для дальнейшей оптимизации нагрузки на разные серверы.
Ниже указаны метрики, которые вы можете отслеживать. Все они отображаются в файле JSON при вызове события web_request
:
Метрика | Описание |
---|---|
bytes_from_ram | Количество байт прочитанных из памяти и отданных пользователю |
bytes_from_dvr_cache | Количество байт прочитанных из кэша и отданных пользователю |
bytes_from_dvr_disk | Количество байт прочитанных с диска и отданных пользователю |
bytes_from_dvr_remote | Количество байт прочитанных с внешнего DVR-сервера и отданных пользователю |
dvr_utc_ms | Время начала запрашиваемого фрагмента архива (Unix-время, мс) |
Чтобы получить общее количество переданной информации в байтах, необходимо просуммировать значения вышеприведённых метрик (за исключением dvr_utc_ms
):
bytes_from_ram
+ bytes_from_cache
+ bytes_from_dvr_disk
+ bytes_from_dvr_remote
= общее количество переданных байт.
Для того, чтобы настроить получение значений метрик, необходимо добавить в конфигурационный файл (/etc/flussonic/flussonic.conf
) следующие строки:
event_sink example_web_request_logger {
url http://examplehost:5000/events;
only event=web_request;
}
где:
example_web_request_logger
— имя процесса,http://examplehost:5000/events
— путь до кастомного обработчика либо до файла журнала.
Теперь когда будет вызываться событие web_request
, вам будет отправляться файл JSON со значениями указанных метрик.
Note
Если вы попытаетесь получить значения метрик для потокового вещания, то получите следующие значения: dvr_utc_ms = null
, bytes_from_ram = size
, bytes_from_cache = 0
, bytes_from_dvr_disk = 0
, bytes_from_dvr_remote = 0
по той причине, что указанные метрики относятся исключительно к использованию DVR.
Команды, доступные пользователям
При вызове команд, доступных пользователям, необходима проверка прав доступа. Это необходимо, чтобы обеспечить безопасный доступ клиентов к данным. Для этого вы можете использовать авторизацию по токену. В примерах ниже мы не будем использовать авторизацию при запросах к API.
Получение JPEG-скриншотов из архива по времени UTC
Когда вы включили скриншоты для DVR или по URL, Flussonic начинает создавать и писать скриншоты на диск, а вы можете получать эти скриншоты по специальным URL. Эти URL содержат время того момента, в который был получен скриншот.
Flussonic может находить JPEG-скриншоты с указанием приблизительного момента времени. Например, вы можете узнать из датчика движения, что в районе определённого времени записаны необходимые вам события, или вы можете знать необходимое время, посмотрев его на таймлайне в плеере.
Если по указанному вами моменту времени скриншот не был найден, то Flussonic найдёт ближайший к указанному вами момент времени, когда был сделан скриншот. Flussonic исправляет время на точное, если вы указали неточное в своем запросе. Он вернёт часть URL, который может быть использован для получения необходимого скриншота.
Например, запросим скриншот от 31.01.2023 13:28:11. Именно в этот момент времени скриншот записан не был, но есть скриншот в момент времени, близкий к указанному. Flussonic возвращает Location
с указанием момента времени, в который был найден скриншот (в нашем примере это 31.01.2023 13:27:07). Это время которое мы можем использовать далее для доступа к JPEG- скриншотом.
Чтобы запросить JPEG-скриншот потока из DVR, используйте запрос GET /{name}/{from}.jpg, где:
{name}
— имя потока,{from}
— момент времени в формате Unix-времени, после которого Flussonic ищет записанный JPEG-скриншот или ближайший ключевой кадр для генерации JPEG-скриншота.
curl -v 'http://FLUSSONIC-IP/STREAM_NAME/1675171691.jpg'
...
< HTTP/1.1 302 Found
< Connection: keep-alive
< Date: Tue, 31 Jan 2023 13:28:11 GMT
...
< Location: /STREAM_NAME/1675171627.jpg
Генерация JPEG-скриншотов по запросу
Flussonic может создавать JPEG-скриншоты на лету. При этом экономятся ресурсы диска. Нагрузка на процессор будет ощутимая, поэтому защищайте сервер с помощью авторизации доступа. А лучше используйте видео-скриншоты, если нет необходимости именно в JPEG.
Чтобы получить JPEG-скриншот, используйте запрос GET /{name}/{from}-preview.jpg, где:
{name}
— имя потока,{from}
— момент времени в формате Unix-времени, после которого Flussonic ищет записанный JPEG-скриншот или ближайший ключевой кадр для генерации JPEG-скриншота.
curl -v 'http://192.168.2.3:80/STREAM_NAME/1675179644-preview.jpg'
...
< HTTP/1.1 200 OK
...
< Content-Length: 5738
< Content-Type: image/jpeg
< Last-Modified: Wed, 02-May-2018 07:00:40 GMT
< X-Thumbnail-Utc: 1525244440
...here goes jpeg...
Получение MP4 видео-скриншотов
Мы рекомендуем использовать видео-скриншоты вместо JPEG-скриншотов. Видео-скриншоты архива получают почти так же, как JPEG-скриншоты. Flussonic исправляет URL, если по запрошенному URL нет подходящего кадра для создания скриншота.
Чтобы получить MP4 видео-скриншот из записанного в архив DVR потока, используйте запрос GET /{name}/{from}-preview.mp4, где:
{name}
— имя потока,{from}
— момент времени в формате Unix-времени, после которого Flussonic ищет записанный MP4-скриншот или ближайший ключевой кадр для возвращения MP4-скриншота.
curl -v 'http://FLUSSONIC-IP/STREAM_NAME/1675252800-preview.mp4'
...
< HTTP/1.1 302 Found
< Location: /STREAM_NAME/1675252803-preview.mp4
Flussonic вернёт MP4-файл, состоящий из одного кадра.
Скачивание фрагмента записи архива в виде файла MP4 или MPEG-TS
Flussonic позволяет скачать фрагмент записи архива DVR в формате файла MP4 или MPEG-TS на свой компьютер.
Чтобы скачать фрагмент архива в виде MP4-файла, используйте запрос GET /{name}/archive-{from}-{duration}.mp4, где:
{name}
— имя потока,{from}
— время начала фрагмента записи в формате Unix-времени,{duration}
— продолжительность фрагмента записи в секундах.
Ниже показаны примеры URL для загрузки фрагмента архива потока длиной в один час в:
- MP4:
http://FLUSSONIC-IP/STREAM_NAME/archive-1525186456-3600.mp4
- MPEG-TS:
http://FLUSSONIC-IP/STREAM_NAME/archive-1525186456-3600.ts
Вставьте подобную ссылку в браузер и начнётся загрузка файла на компьютер.
Если вам необходимо скачать фрагмент архива с определёнными дорожками, укажите их в параметре filter.tracks
в строке запроса:
http://FLUSSONIC-IP/STREAMNAME/archive-1525186456-4200.mp4?filter.tracks=v1a1