Модели
Работа с моделями может осуществляться не только в графическом интерфейсе платформы, но и посредством использования API. Существует некоторый набор основных HTTP-запросов, использование которых может позволить внешним системам выполнять ключевые операции по взаимодействию с моделями, их параметрами и структурой. В числе этих операций:
- Получение списка моделей;
- Получение информации об одной модели;
- Создание новой модели;
- Редактирование модели;
- Удаление модели.
Получение списка моделей
Для того чтобы получить полный список моделей, доступных пользователю, необходимо отправить запрос GET /api/v1/models
. В ответе будет получен массив объектов, каждый из которых представляет из себя конфигурацию одной модели.
Запрос
GET /api/v1/models HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}
Ответ
HTTP/1.1 200 OK
[
{
"_id": "5d8a1ef2d0025e0012fb76c6",
"name": "Модель 01",
"base": "mqtt",
"props": {
"bots": true,
"hardwareEvents": false,
"helper": {
"nostate": "@ric-docs/docs/helpers/mqtt.md"
},
"prefix": "",
"order": 1,
"defaultNode": "temperature",
"protocol": "mqtt",
"idPattern": "mqtt-$tagname-$nanoid",
"auth": {
"title": "mqtt_auth",
"fields": {
"username": {
"title": "mqtt_username"
},
"password": {
"secret": true,
"title": "mqtt_password"
}
}
},
"x509": {
"enabled": true
}
},
"disabled": [],
"removed": []
}
]
Получение информации об одной модели
Для получения информации об одной сущности необходимо указать ее идентификационный номер, присвоенный ей системой. В ответе от сервера будет получена конфигурация модели и результат выполнения запроса.
Запрос
GET /api/v1/models/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}
Ответ
HTTP/1.1 200 OK
{
"_id": "5d8a1ef2d0025e0012fb76c6",
"name": "Модель 01",
"base": "mqtt",
"props": {
...
},
"x509": {
"enabled": true
}
},
"disabled": [],
"removed": [],
"success": true
}
Создание новой модели
При отправке данного запроса стоит учитывать, что модель будет создана именно на основе тех параметров, которые указаны в теле запроса. В примере, приведенном ниже, заданы только те поля, которые являются обязательными для модели.
Для того чтобы выстроить некоторую структуру модели и добавить в нее несколько параметров, необходимо прописать данную структуру в теле запроса или отправить новый запрос (см. следующий пункт). Стоит отметить, что при создании модели внешние программные модули добавляются автоматически. В этом можно убедиться, открыв вкладку «Код» в созданной модели и просмотрев ее структуру.
Запрос
POST /api/v1/models HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}
{
"base": "mqtt",
"name": "Model 02",
"description": "Model of microcontroller"
}
Ответ
HTTP/1.1 200 OK
{
"owner": "5d8a18d5d0025e0012fb6a34",
"group": "5d8a18d4d0025e0012fb6a31",
"time": 1569334251811,
"_id": "5d8a23ebd0025e0012fb8103",
"success": true
}
Редактирование модели
Для изменения сущностей используется метод PATCH. Применительно к моделям, он может быть использован следующим образом.
К примеру, с помощью запроса PATCH api/v1/models/:id
может быть выстроена структура модели с учетом добавления необходимых параметров и указания иерархических связей. Структура обязательно задается в поле data
в фигурны скобках. Она прописывается по аналогии со структурой модели, приведенной во вкладке «Код», в меню «Модели».
В ответе на запрос указывается вся та информация о модели и ее структуре, которая была задана в теле запроса.
Запрос
PATCH /api/v1/models/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}
{
"data": {
"id": "root",
"name": "MQTT",
"active": true,
"type": "subsystem",
"children": [
{
"id": "external-software-modules",
"active": true,
"copy": true,
"type": "subsystem",
"children": [],
"name": "Внешние программные модули"
},
{
"id": "params",
"name": "Params",
"active": true,
"type": "subsystem",
"children": [
{
"id": "temperature",
"name": "Temperature",
"active": true,
"type": "argument",
"source": "state",
"dataType": "number",
"unit": "temperature-celsius",
"reference": "base/state/temperature",
"factor": 1,
"linear": true
},
{
"id": "humidity",
"name": "Humidity",
"active": true,
"type": "argument",
"source": "state",
"dataType": "number",
"unit": "percent",
"reference": "base/state/humidity",
"factor": 1
}
]
}
]
},
"base": "mqtt"
}
Ответ
HTTP/1.1 200 OK
{
"_id": "5d8a3319d0025e0012fba0fa",
"base": "mqtt",
"name": "Model 05",
"description": "",
"owner": "5d8a18d5d0025e0012fb6a34",
"group": "5d8a18d4d0025e0012fb6a31",
"time": 1569338137927,
"_at": 1569338195770,
"data": {
"active": true,
"children": [
{
...
}
],
"id": "root",
"name": "MQTT",
"type": "subsystem"
},
"success": true
}
Удаление модели
Для удаления модели необходимо отправить запрос DELETE /api/v1/models/:id
с указанием ее идентификатора. В ответе отобразятся главные поля модели и результат выполнения запроса.
Запрос
DELETE /api/v1/models/:id HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}
Ответ
HTTP/1.1 200 OK
{
"_id": "5d8a23ebd0025e0012fb8103",
"owner": "5d8a18d5d0025e0012fb6a34",
"group": "5d8a18d4d0025e0012fb6a31",
"time": 1569334251811,
"success": true
}