Модели

Работа с моделями может осуществляться не только в графическом интерфейсе платформы, но и посредством использования API. Существует некоторый набор основных HTTP-запросов, использование которых может позволить внешним системам выполнять ключевые операции по взаимодействию с моделями, их параметрами и структурой. В числе этих операций:

1. Получение списка моделей;
2. Получение информации об одной модели;
3. Создание новой модели;
4. Редактирование модели;
5. Удаление модели.

Получение списка моделей

Для того чтобы получить полный список моделей, доступных пользователю, необходимо отправить запрос 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
}