====== АННОТАЦИЯ ======
В данном документе приведено описание применения программы "Программный интерфейс взаимодействия системы отображения метеорологических данных измерительной информации", предназначенной для передачи системе отображения метеорологической информации из базы данных.
====== Общие сведения о системе ======
Программный интерфейс входит в состав системы отображения метеорологических данных МФ МГТУ им. Н.Э. Баумана.
Основные функции программного интерфейса состоят в получении, передачи и обработке метеорологической информации в формате JSON.
====== Условия применения ======
===== Требования к аппаратным средствам =====
В состав технических средств должен входить персональный компьютер (ПЭВМ), выполняющий роль сервера, включающий в себя:
* Процессор Pentium-2.0Hz, не менее
* Оперативную память объемом 1 ГБ, не менее
* Свободное место на диске объемом 1 ГБ, не менее. Данное требование обусловлено тем, что для корректной работы программного интерфейса необходимо установить ряд программных зависимостей
===== Программные зависимости =====
Для функционирования программного интерфейса необходимо инсталлировать резидентную систему управления базами данных класса NoSQL Redis версии 6.0.1.
Также необходимо установить программную платформу Node.js версии 12.16.3, а также ряд npm-пакетов и модулей:
* express - фреймворк для языка JavaScript
* redis - модуль, работающий с базой данных Redis
* fs - модуль, позволяющий работать с файловой системой сервера
* request - модуль, необходимый для осуществления отправки асинхронных запросов
* http-errors - модуль обработчика HTTP-ошибок
* path - модуль, помогающий определить путь файла в файловой системе
* cookie-parser - модуль обработчика cookie-файлов
* morgan - модуль, позволяющий осуществлять логирование и вести системный журнал, в случае неполадок и критических ошибок
* moment - модуль, предоставляющий функции для работы со временем
* graphql - модуль, предоставляющий возможность проектирования, используя архитектуру GraphQL
* express-graphql - модуль, связывающий фреймворк express и graphql
Все вышеперечисленные модули устанавливаются с помощью команды:
$ npm install "имя пакета"
Все вышеописанное программное обеспечение необходимо устанавливать на операционные системы семейства Linux и Windows. При использовании Windows единственным ограничением будет необходимое использование операционной системы Windows 7 или выше.
====== Описание решаемой задачи ======
Программный интерфейс работает в режиме 24/7 на сервере мониторинговой системы, ожидая запросы на получение данных. Вместе с программным интерфейсом постоянно работает Redis, который расположен на порте сервера 6379.
====== Входные и выходные данные ======
===== Входная информация =====
Входной информацией для программного интерфейса будет являться GET-запрос по протоколу HTTP к интерфейсу REST или GraphQL.
Список всех возможных запросов к программному интерфейсу REST:
^ **Запрос** ^ **Получаемые данные** ^
| calibr/last5min/:uname/:serial | Откалиброванные данные за последние 5 минут. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| calibr/day/:date/:uname/:serial | Откалиброванные данные за день. Обязательно нужно указать дату в формате "год-месяц-день". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| calibr/lastweek/:uname/:serial | Откалиброванные данные за последнюю неделю. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| calibr/log/:fdate/:sdate/:uname/:serial | Откалиброванные данные за любой временной интервал. Обязательно надо указать начальную и конечную даты в формате "год-месяц-день часы-минуты-секунды". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| calibr/last_measurement/:uname/:serial | Откалиброванные последние измерения (за последние 10 минут). Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| calibr/lastmin/:uname/:serial | Откалиброванные данные за последнюю минуту. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| not_calibr/last5min/:uname/:serial | Неоткалиброванные данные за последние 5 минут. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер). Пример: http://webrobo.mgul.ac.ru:3000/db_api_REST/not_calibr/last5min/Hydra-L/01 |
| not_calibr/lastweek/:uname/:serial | Неоткалиброванные данные за последнюю неделю. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер). Пример: http://webrobo.mgul.ac.ru:3000/db_api_REST/not_calibr/lastweek |
| not_calibr/log/:fdate/:sdate/:uname/:serial | Неоткалиброванные данные за любой временной интервал. Обязательно надо указать начальную и конечную даты в формате "год-месяц-день часы-минуты-секунды". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер). Пример: http://webrobo.mgul.ac.ru:3000/db_api_REST/not_calibr/log/2021-06-30%2013:44:50/2021-06-30%2013:47:57/ |
| not_calibr/last_measurement/:uname/:serial | Неоткалиброванные последние измерения (за последние 10 минут). Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер). Пример: http://webrobo.mgul.ac.ru:3000/db_api_REST/not_calibr/last_measurement |
| not_calibr/lastmin/:uname/:serial | Неоткалиброванные данные за последнюю минуту. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер). Пример: http://webrobo.mgul.ac.ru:3000/db_api_REST/not_calibr/lastmin |
| not_calibr/day/:date/:uname/:serial | Неоткалиброванные данные за день. Обязательно нужно указать дату в формате "год-месяц-день". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер). Пример: http://webrobo.mgul.ac.ru:3000/db_api_REST/not_calibr/day/2021-09-09 |
Для отправки запроса к программному интерфейсу REST необходимо обратиться к следующему URL:
http://название_домена:3000/db_api_REST/запрос
Список всех возможных запросов к программному интерфейсу GraphQL:
^ **Запрос** ^ **Получаемые данные** ^
| {calibr(time:"last5min",uname:" ", serial: " ")} | Откалиброванные данные за последние 5 минут. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {calibr(time:"lastweek",uname:" ", serial: " ")} | Откалиброванные данные за последнюю неделю. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {calibr(time:"log",fdate:" ",sdate: " ", uname:" ", serial: " ")} | Откалиброванные данные за любой временной интервал. Обязательно надо указать начальную и конечную даты в формате "год-месяц-день часы-минуты-секунды". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {calibr(time:"last_measurement",uname:" ", serial: " ")} | Откалиброванные последние измерения. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {calibr(time:"lastmin",uname:" ", serial: " ")} | Откалиброванные данные за последнюю минуту. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {calibr(time:"day",date:" ",uname:" ", serial: " ")} | Откалиброванные данные за день. Обязательно надо указать дату в формате "год-месяц-день". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {not_calibr(time:"day",date:" ",uname:" ", serial: " ")} | Неоткалиброванные данные за день. Обязательно надо указать дату в формате "год-месяц-день". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {not_calibr(time:"last5min",uname:" ", serial: " ")} | Неоткалиброванные данные за последние 5 минут. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {not_calibr(time:"lastweek",uname:" ", serial: " ")} | Неоткалиброванные данные за последнюю неделю. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {not_calibr(time:"log",fdate:" ",sdate: " ", uname:" ", serial: " ")} | Неоткалиброванные данные за любой временной интервал. Обязательно надо указать начальную и конечную даты в формате "год-месяц-день часы-минуты-секунды". Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {not_calibr(time:"last_measurement",uname:" ", serial: " ")} | Неоткалиброванные последние измерения. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) |
| {not_calibr(time:"lastmin",uname:" ", serial: " ")} | Неоткалиброванные данные за последнюю минуту. Для получения данных с конкретного прибора укажите uname и serial (название и серийный номер) | |
Для отправки запроса к программному интерфейсу GraphQL необходимо отправить GET-запрос по протоколу HTTP на следующий URL:
http://название_домена:4000/graphql?query=GraphQL-запрос
===== Выходная информация =====
Выходные данные представлены в виде JSON-записей, ключом каждой из
которых является их уникальный номер записи в базе данных, а значением – словарь, включающий в себя общую информацию и измерения.
Пример одной записи, которая подается на выход:
"1294425": {
"Date": "2020-05-14 11:15:38",
"uName": "Тест Студии",
"serial": "schHome",
"data": {
"system_Version": "2020-01-11",
"system_Upit": " 2.96",
"system_RSSI": "-61",
"system_MAC": "60:01:94:06:05:04",
"RTC_date": "2020-05-14",
"RTC_time": "11:15:32",
"BH1750_lux": "426.67",
"BH1750_blinkmin": "426",
"BH1750_blinkmax": "426",
"BH1750_blink": "0",
"TCS34725_red": "10091",
"TCS34725_green": "8868",
"TCS34725_blue": "9148",
"TCS34725_clear": "21810",
"TCS34725_redC": "6943",
"TCS34725_greenC": "5720",
"TCS34725_blueC": "6000",
"TCS34725_clearC": "18662",
"TCS34725_ir": "3148",
"TCS34725_colorTemp": "8804",
"TCS34725_colorTempCT": "4683.52",
"TCS34725_lux": "506.57",
"BMP280_temp": "14.49",
"BMP280_pressure": "744.43",
"BME280_temp": "13.87",
"BME280_humidity": "46.69",
"BME280_pressure": "743.2",
"DS18B20_temp": "13.69",
"AM2321_temp": "14",
"AM2321_humidity": "41.6"
}
}
Выше рассмотрена одна выходная запись, ключом которой является ее уникальный номер в базе – 1294425. Ее значение – словарь, в котором содержатся общие данные: время измерения, название прибора, его серийный номер. Также в значении записи находится словарь «data», в котором содержится вся метеорологическая и системная информация в формате «параметр – значение».