Сервер WNAM QoW позволяет обеспечить взаимодействие с внешней информационной системой - например, системой мониторинга вашей организации, или универсальным дашбордом сервисов организации, по HTTP/REST протоколу.
Для этого внешняя информационная система должна отправлять специальным образом сформированные запросы на API-эндпоинт сервера QoW. Для авторизации доступа используется передача заголовка "X-API-Key" со значением, соответствующем значению параметра netams.remoteToken, определенного в конфигурационном файле /home/qow/application.properties сервера. При помощи API внешняя система может получить справочники различных объектов (сенсоров, групп, ...) сервера, состояние последнего измерения по заданному объекту, запустить внеочередное выполнение измерения по заданному объекту (например, проблемной точке доступа).
Формат обмена данных - JSON, кодировка UTF-8. Все эндпоинты вызываются по методу HTTP GET. Ответ сервера - в формате JSON.
Справочник допустимых эндпоинтов API:
| URL | Параметры | Возвращаемое значение | Описание |
|---|---|---|---|
| /api/objects/listGroups | нет | Массив краткой информации по всем группам в системе | |
| /api/objects/getGroup/{groupId} | идентификатор группы | Краткая информация по заданной группе | |
| /api/objects/listSensors | нет | Массив краткой информации по всем сенсорам в системе | |
| /api/objects/getSensor/{sensorId} | идентификатор сенсора | Краткая информация по заданному сенсору | |
| /api/objects/listAccessPoints | нет | Массив краткой информации по всем "своим" точкам доступа в системе | |
| /api/objects/getAccessPoint/{accessPointId} | идентификатор точки доступа | Краткая информация по заданной точке доступа | |
| /api/objects/listTasks | нет | Массив краткой информации по всем задачам в системе | |
| /api/objects/getTask/{taskId} | идентификатор задачи | Краткая информация по заданной задаче | |
| /api/objects/getNames/{groupId} | идентификатор группы или "default" для самой верхней (топ) группы | Массив объектов: типов и имен групп, точек доступа и сенсоров по их Id, для всех объектов заданной группы, и её подгрупп | Пример вывода: [ { |
| /api/healthSummary/getLatest | один из параметров должен быть указан: groupId, sensorId, accessPointId или bssid | Краткая информация по результатам измерения для заданного объекта, взятая из последнего измерения из БД сервера. | Запрос последних известных данных по измерениям для заданного объекта. Параметры объекта передаются в URL запросе в виде ключ=значение, например https://dev.wifisensor.pro/api/healthSummary/getLatest?sensorId=611a211ff1290747553498f4 Ответ сервера приходит синхронно и за короткое время (миллисекунды). |
| /api/healthSummary/requestHealth | один из параметров должен быть указан: groupId, sensorId, accessPointId, accessPointName, taskId, ssid или bssid (все - строки) обязательные параметры callbackUrl (строка) и timeout (число секунд) | Статус запуска задачи "вне очереди" на подходящем по параметрам запроса сенсоре (сенсорах) | Запрос выполнения измерения для заданного объекта. Параметры объекта передаются в URL запросе в виде ключ=значение. Ответ сервера приходит асинхронно после заданного таймаута, либо раньше, если измерения завершатся до него, путем отправки запроса на заданный Callback URL вашей системы. |
| /api/objects/getSsids/{groupId} | идентификатор группы | список заданных для этой группы SSID | Запрос перечня заданных для группы "собственных" сетей со всеми их настройками, без вложенных либо родительских групп |
| /api/objects/setSsidPassword | ssid=строка password=строка | количество измененных SSID | Запрос изменения PSK пароля для заданного SSID. Изменяется значение всех найденных SSID (по имени) во всех группах. Запрос отправляется по методу HTTP POST. |
| /api/metrics/getList | необязательные параметры: groupId, sensorId, accessPointId | массив объектов типа "метрика", содержащий имя (ключ), описание и пороговые значения | может быть отфильтрован по собираемым метрикам для заданной группы, сенсора или точки доступа |
| /api/metrics/getAggregated | один из параметров должен быть указан: groupId, sensorId, accessPointId необязательные параметры: interval (по умолчанию Day) допустимо Hour, SixHours, TwelveHours, Day, Week, TwoWeeks, Month key, ssid, или bssid | комплексный объект, содержащий общие счетчики метрик за весь период, и затем в виде массива счетчики по интервалам (отрезкам времени) внутри этого периода. | аналогичен данным, использующимся в отрисовке гистограммы по метрикам. применимы дополнительные фильтры по ключу метрики, SSID и BSSID |
| /api/metrics/getRaw | необязательные параметры: interval (по умолчанию Day) допустимо Hour, SixHours, TwelveHours, Day, Week, TwoWeeks, Month либо Period, в последнем случае также указать fromDate и toDate groupId, sensorId, accessPointId key, ssid, bssid | массив объектов типа MeasurementResult с примененными фильтрами, и за заданный диапазон времени | исходные результаты измерений (метрики) без агрегации по времени или типу. формат дат fromDate и toDate задаётся как "dd/MM/yyyy HH:mm" |
| /api/metrics/getSemiAggregated | обязательные параметры: groupId, key необязательный параметр: interval, принимает значения: FiveMinutes, TenMinutes, ThirtyMinutes, Hour, ThreeHours, SixHours, TwelveHours, Day, Week, TwoWeeks, Month, TwoMonths, ThreeMonths, FourMonths, SixMonths, Year по умолчанию interval=TenMinutes | массив объектов типа MetricSemiAggregatedResult для группы и ключа метрики key, за заданный интервал времени от "сейчас" назад: [ { | агрегированные по времени результаты измерений метрики, с разбивкой по BSSID |
При этом идентификатором является ключ в базе MongoDB, под которым хранятся сведения об объекте. Это длинная строка вида "611a213bf1290747553498f9".
Внимание! Выдаются сокращенные сведения об объекте: id, имя, местоположение, принадлежность к группе и несколько других базовых характеристик. Полная информация об объекте (как она хранится на сервере) в данном API не предоставляется.
Например:
Запрос информации о сенсоре
curl -X GET \
https://wifisensor-server/api/objects/getSensor/611a211ff1290747553498f4 \
-H 'X-API-Key: sxdgfgdfghdgjgfdhjlasdgf' \
-H 'cache-control: no-cache'
Ответ сервера
HTTP/1.1 200
Server: nginx/1.14.2
Date: Wed, 12 Jan 2022 12:20:59 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: JSESSIONID=706F8360029679006C5548E26C0E1A33; Path=/; HttpOnly
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Accept,Authorization,Cache-Control,Content-Type,DNT,If-Modified-Since,Keep-Alive,Origin,User-Agent,X-Requested-With,X-API-Key{
"id": "611a211ff1290747553498f4",
"mac": "94:83:C4:09:04:DC",
"location": "FNM_B_r220",
"name": "QoW-1",
"testingAccessPointIds": [
"614a0c47b6fb545d0e1ea1b0"
],
"groupId": "611a213bf1290747553498f9"
}
Получение вашей информационной системой информации о статусе "здоровья" заданных точек доступа, по точке доступа, группе точек доступа, и сенсору (отвечающему за некоторые точки доступа), а также по иным параметрам, может производиться в двух режимах:
Первый вариант применим, если результат желательно получить сразу. При этом в качестве ответа поступят данные, собранные ранее, т.е. за время не больше, чем штатный интервал между запусками задач на сенсоре. Результаты формируются настроенной на сенсоре задачей.
Второй вариант применим, если вы хотите выполнить измерение "сейчас", для заданного объекта или подмножества объектов (контролируемых "ваших" точек доступа). У вас есть возможность указать другой (чем в обычном расписании сенсора) идентификатор задачи - проверка будет проводиться с её использованием. На время проведения проверки задачей такого типа штатное выполнения других задач сенсором по расписанию приостанавливается.
В любом случае ваша система должна предварительно запросить идентификаторы точек доступа, сенсоров и т.п., для формирования запроса статуса здоровья.
Внимание! Возвращается сокращенная информация о здоровье: успешность и текстовый статус инструкций подключения к точке доступа, портальной авторизации, проверке качества связи, суммарная информация по метрикам. Полная информация о результате измерения (как она хранится на сервере) в данном API не предоставляется.
Для демонстрации возможностей API сервера WNAM QoW Server на Python/Flask создан прототип внешней информационной системы, имеющий Web UI, поддерживающий REST и доступный в исходных кодах по запросу. Далее приведены скриншоты его работы со стендовым сервером WNAM QoW.
По нажатию на кнопки получения списков отображаются запрошенные сведения, например идентификаторы, требуемые для последующих запросов статуса здоровья:
При нажатии на кнопку запроса последнего выполненного измерения для заданной точки доступа показывается информация по её "здоровью":
Если указать URL callback-метода (этот эндпоинт также входит в состав примера), можно попросить сервер выполнить задачу "вне очереди". При этом сразу возвращается информация о (не)успешности запуска такого задания:
В этот момент на сервере формируется задача на тестирование (и присваивается уникальный ключ такого внеочередного теста), и она отправляется сенсорам:
14:25:31.207 DEBUG [c.n.q.s.OutOfOrderMeasurementService:35] - addRequest awaiting from 1 sensors in 300 seconds, OOO task key is f90e1cdd-d3a9-4e49-9ef3-2575c5720e3f
В свою очередь, сенсоры по MQTT получают сообщение о необходимости внеочередного запуска задачи:
2022-01-12 14:25:31,258 [wnam_async_client.py:387] >> INFO: OOO RUN TASK! {'queue_schedules': {}, 'tasks_to_run': [], '_Scheduler__sensor': <__main__.Sensor object at 0x19e0b10>, ....
2022-01-12 14:25:31,266 [wnam_async_client.py:389] >> DEBUG: OOO RUNNER PROCESS PID 15557
2022-01-12 14:25:31,275 [wnam_task.py:148] >> DEBUG: Task Enabled
2022-01-12 14:25:31,277 [wnam_task.py:150] >> DEBUG: TASK 5f9c6800dfb03e75993a5d38
2022-01-12 14:25:31,293 [wnam_task.py:245] >> DEBUG: Out-of-order taks key is f90e1cdd-d3a9-4e49-9ef3-2575c5720e3f
Задача выполняется положенное время, результат отправляется на сервер.
При этом при нажатии на кнопку "показать последний полученный результат" отображается содержимое буфера callback-эндпоинта, поначалу пустое. Со временем на сервер поступят данные от тестирующего сенсора:
14:30:26.914 DEBUG [c.n.q.s.OutOfOrderMeasurementService:46] - sendMeasurement received from sensor QoW-1, left 0/1 sensors, 295/300 seconds
14:30:27.015 DEBUG [c.n.q.s.OutOfOrderMeasurementService:67] - submitCallback returned code 200 OK, msg='{"success": true, "length": 20}'
И после этого в окне с информацией об объекте появятся полученные данные:
Если по каким-то причинам (сбой одного сенсора, задача исполняется дольше, чем ожидается в параметре timeout) данных на сервере будет недостаточно, он все равно отправит на callback-эндпоинт то, что будет получено к данному моменту.