4.1. Общая информация

Важно

Если вы контролируете результат управления по API в web-интерфейсе Boro VoD, обновляйте страницу после исполнения команды.

4.1.1. Описание

API предназначен для управления решением Boro VoD и получения результатов анализа. Для настройки доступа по API необходимо выполнить несколько шагов:

  1. Войдите под учетной записью администратора сервера Boro VoD (роль суперадмина) и перейдите в настройки Settings

  2. На вкладке Панель администратора ➝ General убедитесь, что в поле Host name задано имя хоста. Без указания Host name не удастся применить настройки API;

  3. Перейдите на вкладку Панель администратора ➝ Control API, включите соответствующий чекбокс и сохраните настройки;

  4. Настройте доступ к API в Nginx-сервере, т.к. по умолчанию доступ закрыт.

    ../_images/ControlAPI_ru.png

  5. [опционально] Настройте аутентификацию пользователей.

4.1.2. Иерархия сущностей системы Boro VoD

../_images/ArchitectureAPI_ru.png

  • Сервер Boro VoD — платформа, позволяющая регистрировать учетные записи и создавать проекты для выполнения задач по контролю качества медиафайлов;

  • Аккаунт — зарегистрированная учетная запись пользователя в системе Boro VoD. Содержит настройки и список доступных проектов, зондов и шаблонов. Каждый аккаунт идентифицируется уникальным значением user_id, которое используется в запросах API;

  • Проект — логическая сущность в рамках учетной записи, объединяющая настройки, группу зондов, шаблонов проверки и выполняемых задач:

    • Каждый проект идентифицируется уникальным значением project_id, которое участвует в формировании запросов к API,

    • В рамках одной учетной записи пользователь может создать неограниченное количество проектов. Обычно достаточно одного проекта, однако для удобства допускается создание нескольких проектов с целью разграничения различных типов задач или локаций контроля качества,

    • Каждый проект уникален и может быть настроен независимо от других проектов,

    • Пользователи могут предоставлять доступ другим пользователям к своим проектам.

  • Зонды — программные компоненты системы, выполняющие задачи проверки медиафайлов в соответствии с заданным шаблоном. Каждый зонд привязан к конкретному проекту и работает согласно настройкам проекта. Для масштабирования решения пользователь может запускать неограниченное количество зондов в рамках проекта. Зонд идентифицируется с помощью идентификатора app_id;

  • Шаблон — JSON-структура, включающая набор тестов. Тест — это правило, по которому зонд проверяет медиафайл. Каждый тест включает уровень критичности, условие соответствия и пороговые значения, а также отвечает за анализ конкретного параметра или поиск ошибки. Шаблон характеризуется уникальным значением template_id;

  • Задача проверки — процесс анализа медиафайла, выполняемый зондом по заданному шаблону. Каждая задача имеет идентификатор task_id.

4.1.3. Описание формата сообщений

Формат сообщения основан на JSON RPC. Запросы отправляются на сервер Boro Vod с помощью HTTP POST на URL http://<SERVER_NAME>/ctrl_api/v1/json.

ЗАПРОС:

POST-сообщение с типом содержимого Content-Type: application/json.

{
  "user_id":(number),
  "methods":[
    {
      "method":(string),
      "id":(number),
      "params":{
        ...
        /DATA/
        ...
      }
    }
  ]
}

где:

  • user_id — целое число, идентификатор пользователя;

  • methods — массив объектов, список вызываемых методов с параметрами. Возможен вызов нескольких методов в одном запросе (в том числе одинаковых с использованием опционального поля id для идентификации ответа);

  • method — строка, имя вызываемого метода;

  • id (опциональное поле) — целое число, идентификатор запроса. Установленное значение возвращается в ответе на вызов метода. Поле предназначено для идентификации ответа при вызове нескольких одинаковых методов;

  • params — объект, параметры вызываемого метода (см. описание каждого метода).

ОТВЕТ:

Данные в формате JSON.

{
  "reply":[
    {
      "method":(string),
      "id":(number),
      "result":[
        ...
        /DATA/
        ...
      ]
    }
  ]
}

где:

  • method — строка, имя вызванного метода;

  • id (опциональное поле) — целое число, идентификатор запроса. Принятое в запросе значение возвращается в ответе. Поле предназначено для идентификации ответа при вызове нескольких одинаковых методов;

  • result — массив объектов, данные, возвращаемые методом (см. описание каждого метода).