RU

Типы

Модель

Функции и принципы построения моделей описаны в разделе документации:
import type { Base, ModelNode } from "@rightech/api";
 
export interface Model extends Base {
  base: string; // идентификатор базовой модели: mqtt, lorawan, http ...
  data: ModelNode; // содержимое модели в виде древовидной структуры
}

Узлы модели

Все узлы модели, имеют следущий минимальный набор полей:
export type BaseNode = {
  type: string;
  id: string;
  name: string;
  description?: string;
  active: boolean; // видимость узла, может быть скрыт
  children?: ModelNode[]; // дочерние узлы
};
Поле type определяет тип узла:
export type ModelNode =
  | BaseNode
  | SystemNode
  | EventNode
  | ArgumentNode
  | ActionNode;

Подсистема

export type SystemNode = BaseNode & {
  type: "subsystem";
};

Аргумент

export type ArgumentDataType =
  | "number"
  | "boolean"
  | "string"
  | "object"
  | string;
 
export type ArgumentNode = BaseNode & {
  type: "argument";
  dataType: ArgumentDataType;
  unit?: string; // еденица измерения
};
Список доступных для использования едениц измерения можно получить через GET /api/v1/locale в поле units

Действие

export type ActionNode = BaseNode & {
  type: "action";
  service: string;
  command?: string;
  params?: Record<string, string>;
};
Чаще всего используется для описания команд к устройству в терминах базового протокола.
Например команда PUBLISH протокола MQTT будет иметь следующий вид:
{
  "id": "led-on",
  "name": "Turn-on LED",
  "active": true,
  "type": "action",
  "command": "publish",
  "params": {
    "topic": "base/relay/led1",
    "payload": "1"
  }
}

Событие

export type EventNode = BaseNode & {
  type: "event";
};

Методы

Базовые

Получить список моделей

GET/api/v1/models
По умолчанию список моделей отдаётся без их содержимого.
Для включения дочерних узлов модели в ответ необходимо использовать query-параметр ?with=data
[
  {
    "_id": "60d5db392b370f0011cb2987",
    "name": "model 1",
    "base": "mqtt"
  },
  {
    "_id": "6163dda4099a810011957be8",
    "name": "model 2",
    "base": "lorawan"
  }
]

Получить информацию об одной модели

GET/api/v1/models/:id
По умолчанию модель отдаётся вместе с полем data.
[
  {
    "_id": "60d5db392b370f0011cb2987",
    "name": "model 1",
    "base": "mqtt",
    "data": {
      "id": "root",
      "name": "[mqtt] model",
      "active": true,
      "type": "subsystem",
      "children": [...]
    }
  }
]

Создать новую модель

POST/api/v1/models
Обязательные поля:
  • base - идентификатор базовой модели;
  • name - имя новой модели.
{
  "base": "mqtt",
  "name": "test-model-01",
  "description": "Model of microcontroller"
}
В ответе будет передана созданная модель, в формате аналогичном запросу одной модели

Изменить модель

PATCH/api/v1/models/:id
{
  "name": "test-model-02",
  "description": "Model of sensor"
}
Для изменения отдельных узлов внутри модели необходимо использовать API узлов модели

Удалить модель

DELETE/api/v1/models/:id
В случае, если существуют объекты использующие эту модель, ответ будет содержать ошибку:
{
  "success": false,
  "message": "Unprocessable Entity",
  "tags": ["error_has_objects"]
}

Узлы моделей

💡
В запросах: - :id - идентификатор модели; - :node - идентификатор узла модели.

Создать новый узел

POST/api/v1/models/:id/nodes
Для того чтобы добавить новый узел в опреденное место модели нужно использовать query-параметр ?attachTo=:node с указанием идентификатора родительского узла, например ?attachTo=params или ?attachTo=cmds, иначе узел будет добавлен в корень.
Добавление нового узла происходит в конец списка дочерних элементов.
Для добавления узла в определённую позицию списка нужно использовать query-параметр ?atIndex=0 с указанием индекса нового элемента.
{
  "id": "floorTemperature",
  "type": "argument",
  "name": "Floor Temperature",
  "unit": "temperature-celsius",
  "dataType": "number"
}

Изменить узел

PATCH/api/v1/models/:id/nodes/:node
В теле запроса на изменение существующего узла укажите укажите поля, которые нужно обновить.
{
  "name": "Floor Temperature (in Fahrenheits)",
  "unit": "temperature-fahrenheit"
}

Удалить узел

DELETE/api/v1/models/:id/nodes/:node
⚠️
Удаление узла модели происходит безвозвратно