Категории

Использование API в FortMonitor

ПО FortMonitor имеет возможность получения данных и интеграции со сторонними системами посредством использования API.

Для каждого сервера список доступных методов можно получить по адресу /api/help/index#/ExternalApiV1
Набор методов может различаться в зависимости от версии сервера, поэтому рекомендуется использовать описание API именного на том сервере, с которым предполагается работа.

API не покрывает всех доступных функций системы, многие справочники и отчеты через API недоступны. Если необходимы какие-то методы и функции, которых в текущей версии API нет - можно обратиться к менеджеру продукта FortMonitor, описать необходимый функционал - возможно, будет принято решение о доработке методов API.

Общее описание

Система API документирована посредством использования инструмента построения документации Swagger.

Общий вид документации:

  1. Список доступных методов и их краткое описание
  2. Выбранный запрос - описание его ответа. Переключаясь между пунктами "Model" и "Example Value", можно посмотреть описание параметров ответа и пример структуры ответа.
  3. Описание входных параметров выбранного запроса
  4. Модель данных и пример структуры входящих данных. Переключаясь между пунктами "Model" и "Example Value", можно посмотреть подробное описание параметра и пример его структуры.
  5. Кнопка запроса выбранного метода - с ее помощью можно проверить работу метода.

Принцип использования API

Идеологически API работает следующим образом:

  1. Вызов метода connect
  2. Вызов других методов - с обязательным прикреплением Cookie к запросам.
  3. Вызов метода disconnect - опционально, в конце работы. Сессия будет закончена автоматически через указанный в настройках сервера период неактивности (по умолчанию 5 минут).

Любой метод (кроме connect) обязан быть вызван с передачей Cookie - иначе в ответ будет возвращаться ошибка "NoAuth".

Начиная с версии 3.18 появился второй вариант вызова запросов.
При вызове метода connect в http-заголовках будет возвращен заголовок SessionId.
Во всех последующих вызовах методов можно вместо использования Cookie в добавлять его в http-заголовки.

Основная рекомендация при периодическом запросе данных по API: 1 раз вызвать метод connect, и затем вызывать нужные методы циклически.
Не рекомендуется при каждом цикле каждый раз вызывать метод connect.

Также рекомендуется создавать отдельного пользователя и использовать его только для работы по API.

Устранение наиболее часто возникающих проблем

  1. Запросы возвращают в ответ "NoAuth".
      1. Основная причина проблемы при таком ответе - в запросах не прикреплены Cookie, которые были возвращены при вызове метода connect.
        Решение - проверить, что Cookie действительно прикрепляются ко всем запросам.
      2. Вторая возможная причина - истекшая сессия. Т.е. предыдущий запрос был вызван больше чем N минут назад (N - время неактивности сессии, по умолчанию 5 минут).
        Решение - проверить периодичность вызовов. Можно попробовать вставить циклический вызов метода Ping либо увеличить время неактивности сессий.
      3. Еще одна из причин - для работы в веб-интерфейсе и через API используется один и тот же логин, у которого не указана возможность одновременного входа в систему.
        Решение - использовать отдельный логин для работы через API.
  2. В ответах возвращаются времена в непонятном часовом поясе.
    Работа с часовыми поясами в API имеет особенность: в методе connect указывается часовой пояс. Но если в системе для пользователя вручную через настройки задан часовой пояс - то будет использован часовой пояс именно из настроек, а не из параметров метода.
    Решение - задать нужный часовой пояс в настройках пользователя.

Интеграция с 1С

Большое количество интеграций производится с системой учета 1С.
Для работы с ней в принципе все рекомендации точно такие же, как и для других систем.

Последнее время участились запросы с проблемой - после вызова метода connect все вызовы последующих методов выдают в ответ "NoAuth", хотя все рекомендации были выполнены - и Cookie прикреплялись, и пользователь использовался только для API.

Один из наших партнеров смог решить эту ситуацию:

Долгие ковыряния привели к следующему:

В куки через вызов api/intergration получаем примерно такую строку:

.ASPXAUTH=; expires=Mon, 11-Oct-1999 20:00:00 GMT; path=/; HttpOnly, SGUID=session_id=2cd0e294-00bb-4fad-b6ea-6b8d27152d1b&Culture=ru-ru&langfile=ext-lang-ru.js&msgfile=msg-lang-ru.js&login=; path=/


Беда в том, что перед "SGUID=session_id=" стоит запятая, а не точка с запятой. Меняем эту запятую на точку с запятой и дальше все работает.
Поэтому, для нас эта проблема закрыта.

Возможно, эта проблема связана с настройкой в IIS работы по HttpOnly.