Управление логикой объектов

В платформе Rightech IoT Cloud есть возможность задать гибкую логику поведения объекта в системе. Логика задается в нотации конечных автоматов в графическом интерфейсе платформы.

К основным операциям, которые могут быть воспроизведены со сценариями автоматизации посредством использования API, относятся:

  1. Получение списка сценариев автоматизации.
  2. Получение информации об одном сценарии автоматизации.
  3. Создание нового сценария автоматизации.
  4. Редактирование сценария автоматизации.
  5. Удаление сценария автоматизации
  6. Создание нового контейнера логики.
  7. Удаление контейнера логики.
  8. Получение списка контейнеров логики объекта.
  9. Запуск сценария автоматизации в контейнере.
  10. Остановка выполнения логики в контейнере.
  11. Отправка события в контейнер.

Получение списка сценариев автоматизации

Список предопределённых сценариев автоматизации, доступных для пользователя, можно получить через запрос GET /api/v1/automatons. В ответе от веб-сервера будет приведен массив сценариев, приведенных в формате json.

Запрос

GET /api/v1/automatons HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

Ответ

HTTP/1.1 200 OK

[
    {
        "_id": "5d8a4f2fd0025e0012fbdbf2",
        "name": "Автомат 01",
        "models": [
            "5d8a3319d0025e0012fba0fa"
        ],
        "model": "5d8a3319d0025e0012fba0fa"
    },
    {
        "_id": "5d8a4f6cd0025e0012fbdc75",
        "name": "Автомат 02",
        "models": [
            "5d8a1ef2d0025e0012fb76c6"
        ],
        "model": "5d8a1ef2d0025e0012fb76c6"
    }
]

Получение информации об одном сценарии автоматизации

Для получения информации об одном сценарии необходимо указать его идентификационный номер, присвоенный ему системой. В ответе от сервера будет получена конфигурация данной сущности и результат выполнения запроса.

Запрос

GET /api/v1/automatons/:id HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8a4f6cd0025e0012fbdc75",
    "name": "Автомат 02",
    "models": [
        "5d8a1ef2d0025e0012fb76c6"
    ],
    "model": "5d8a1ef2d0025e0012fb76c6",
    "success": true
}

Создание нового сценария автоматизации

Для создания нового сценария автоматизации в теле запроса необходимо указать все поля и их значения, которые являются обязательными для любого сценария. В ответе от сервера будет получена сформированная конфигурация сценария автоматизации и результат выполнения запроса.

Запрос

POST /api/v1/automatons HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

BODY

Ответ

HTTP/1.1 200 OK

BODY

Редактирование сценария автоматизации

При помощи API платформы могут быть изменены и отредактированы некоторые поля сценариев, к примеру, такие как наименование, описание, модель и т. д. Для добавления новых состояний и построения переходов между ними лучше воспользоваться графическим интерфейсом платформы.

Запрос

PATCH /api/v1/automatons/:id HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

{
  "description": "new description"
}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8a4f6cd0025e0012fbdc75",
    "name": "Автомат 02",
    "models": [
        "5d8a1ef2d0025e0012fb76c6"
    ],
    "model": "5d8a1ef2d0025e0012fb76c6",
    "data": "{\"states\":{\"0\":{\"data\":{\"id\":\"0\",\"type\":\"init\",\"width\":20,\"height\":20},\"position\":{\"left\":80,\"top\":100}},\"1\":{\"data\":{\"id\":\"1\",\"type\":\"final\",\"width\":20,\"height\":20},\"position\":{\"left\":120,\"top\":440}},\"2\":{\"data\":{\"id\":\"2\",\"name\":\"Новое состояние\",\"description\":\"\",\"onenter\":[],\"onexit\":[],\"type\":\"state\",\"width\":280,\"height\":180},\"position\":{\"left\":400,\"top\":220}}},\"transitions\":{\"0\":{\"version\":3,\"data\":{\"id\":\"0\",\"name\":\"Инициализация логики\",\"description\":\"Событие возникающее при запуске интерпретации модели логики\",\"event\":\"init\",\"owner\":{\"id\":\"0\",\"point\":{\"location\":\"right\",\"id\":0}},\"target\":{\"id\":\"2\",\"point\":{\"location\":\"top\",\"id\":1}}},\"block\":{\"key\":\"cb-0\",\"data\":{\"connectionKey\":\"0\",\"type\":\"connectionBlock\"},\"layout\":{\"height\":6,\"width\":11,\"position\":{\"x\":16,\"y\":2}}},\"drawMode\":\"rou\",\"points\":[{\"x\":140,\"y\":100},{\"x\":420,\"y\":100},{\"x\":420,\"y\":200}]},\"1\":{\"version\":3,\"data\":{\"id\":\"1\",\"event\":null,\"owner\":{\"id\":\"2\",\"point\":{\"location\":\"left\",\"id\":1}},\"target\":{\"id\":\"1\",\"point\":{\"location\":\"top\",\"id\":0}}},\"block\":{\"key\":\"cb-1\",\"data\":{\"connectionKey\":\"1\",\"type\":\"connectionBlock\"},\"layout\":{\"height\":3,\"width\":8,\"position\":{\"x\":2,\"y\":11}}},\"drawMode\":\"rou\",\"points\":[{\"x\":380,\"y\":240},{\"x\":120,\"y\":240},{\"x\":120,\"y\":420}]}}}",
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569345388888,
    "_at": 1569513576483,
    "description": "new description",
    "success": true
}

Удаление сценария автоматизации

Для удаления сценария необходимо отправить HTTP-запрос DELETE /api/v1/objects/:id с указанием его идентификатора. В ответе будет получена конфигурация сценария автоматизации и результат выполнения запроса.

Запрос

DELETE /api/v1/automatons/:id HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8a52f6d0025e0012fbe47c",
    "name": "Scenario 03",
    "description": "Automation scenario for microcontroller",
    "target": "5d8a25c1d0025e0012fb84b3",
    "model": "5d8a1ef2d0025e0012fb76c6",
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "time": 1569346294975,
    "_at": 1569346568864,
    "data": {
        ... /* конфигурация автомата */
    },
    "success": true
}

Создание нового контейнера логики

После принятия решения о запуске сценария логики на отдельном объекте необходимо предварительно создать новый контейнер. Контейнер - это изолированное окружение, необходимое для интерпретации отдельного сценария.

Параметр Тип Описание
id ObjectId Идентификатор объекта, является обязательным
container_id string Идентификатор контейнера, является необязательным, будет сгенерирован при его отсутствии

Запрос

POST /api/v1/objects/:id/containers/:container_id HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "container" : "NEW_CONTAINER_ID"
    "success"   : true
}

Удаление контейнера логики

Для удаления ранее созданного контейнера необходимо отправить запрос:

Параметр Тип Описание
id ObjectId Идентификатор объекта, является обязательным
container_id string Идентификатор контейнера, является обязательным

Запрос

DELETE /api/v1/objects/:id/containers/:container_id HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
  "success": true
}

Получение списка контейнеров логики объекта

В любой момент времени существует возможность запросить список запущенных для объекта контейнеров с указанием статуса исполнения.

Запрос

GET /api/v1/objects/:id/containers HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
  "object_id": {
    "container-1": true,
    "container-2": false,
    "container-3": true,
  },
  "success": true
}

Запуск сценария автоматизации в контейнере

После выбора сценария автоматизации и создания контейнера под него становится возможным непосредственный запуск сценария. Стоит учитывать, что при формировании запроса в его теле необходимо указать идентификационный номер сценария, сгенерированный системой.

Параметр Тип Описание
id ObjectId Идентификатор объекта, является обязательным
container_id string Идентификатор контейнера, является обязательным
automaton ObjectId Идентификатор сценария автоматизации, является обязательным

Запрос

POST /api/v1/objects/:id/containers/:container_id/start HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

{
    "automaton": "58238a935baa56173b24f0e4",
}

Ответ

HTTP/1.1 200 OK

{
    "success": true
}

Остановка выполнения логики в контейнере

Остановка выполнения сценария осуществляется при помощи запроса POST /api/v1/objects/:id/containers/:container_id/stop. При этом контейнер, в котором была ранее запущена логика, остаётся.

Параметр Тип Описание
id ObjectId Идентификатор объекта, является обязательным
container_id string Идентификатор контейнера, обязателен

Запрос

POST /api/v1/objects/:id/containers/:container_id/stop HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "success": true
}

Отправка события в контейнер

Событие может быть отправлено в контейнер логики вручную посредством передачи в теле запроса идентификатора события, указанного в сценарии. Отправка события для всех контейнеров объекта осуществляется через запрос POST /api/v1/objects/:id/emit. При отправке события для конкретного контейнера добавляются префиксы containers/:container_id.

Параметр Тип Запрос
id ObjectId Идентификатор объекта, является обязательным
container_id string Идентификатор контейнера, является необязательным
event string Идентификатор события, является обязательным

Запрос

POST /api/v1/objects/:id/containers/:container_id/emit HTTP/1.1
Content-Type: application/json
Autorizatoin: Bearer {token}

{
    "event": "custom-user-event",
}

Ответ

HTTP/1.1 200 OK

{
    "success": true
}