loader

Оставьте свои контакты

Мы получили вашу заявку

Создайте свой первый проект ещё до нашего ответа.
Это бесплатно!

Создать проект
Для разработчиковREST APIОбъекты

Объекты контроля

Работа в платформе Rightech IoT Cloud организована вокруг объектов контроля. Они являются представлением объектов реального мира, над которыми осуществляется мониторинг и управление.

Типовое описание объекта контроля:

interface Object {
    _id      : String;  /* Внутренний идентификатор в системе */
    id       : String;  /* Идентификатор объекта, присваиваемый пользователем  */
    model    : String;  /* Идентификатор модели объекта контроля */
    status   : String;  /* Текстовый статус объекта */
    state    : Packet;  /* Последний пакет данных */
}

Помимо глобального идентификатора _id определён еще один идентификатор id, используемый для связи с внешними системами передачи данных. Пакет данных объекта не фиксируется, он определяется в зависимости от модели устройства. Минимальным набором параметров является идентификатор и время регистрации.

Типовое описание пакета данных:

interface MinPacket {
    _id     : String;    /* Идентификатор пакета */
    _ts     : Number;    /* Время сервера (микросекунды) */ 
    time    : Number;    /* Время регистрации пакета устройством или сервером (миллисекунды) */
    online  : Boolean;
}

Можно заметить, что в полях _ts и time могут быть одновременно указано время сервера. Это объясняется тем, что если объект не регистрирует текущее время самостоятельно и не отправляет данные о нем на платформу, то тогда в поле time будет указано время сервера по умолчанию.

После добавления в модель дополнительных параметров они дополнительно включаются в формат пакета данных от объекта.

Пример

interface Packet extends MinPacket {
    lat     : Number;  /* Широта */
    lon     : Number;  /* Долгота */    
    height  : Number,  /* Высота над уровнем моря в метрах */
    angle   : Number,  /* Угол поворота в градусах */
    speed   : Number;  /* Мгновенная cкорость в км/ч */

}

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

  1. Получение списка объектов;
  2. Получение информации об одном объекте;
  3. Создание объекта;
  4. Изменение объекта;
  5. Удаление объекта;
  6. Получение журнала данных объекта;
  7. Отправка команд;
  8. События WebSocket.

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

Для запроса списка объектов, созданных ранее и добавленных пользователю в доступ, необходимо отправить запрос GET /api/v1/objects. В ответе от веб-сервера будет приведен массив объектов в формате json.

Запрос

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

Ответ

HTTP/1.1 200 OK

[
    {
        "_id": "5d8a25c1d0025e0012fb84b3",
        "model": "5d8a1ef2d0025e0012fb76c6",
        "id": "mqtt-z86s58",
        "name": "Объект 01",
        "status": "ok",
        "active": true,
        "group": "5d8a18d4d0025e0012fb6a31",
        "models": {
            "id": "5d8a1ef2d0025e0012fb76c6"
        }
    },
    {
        "_id": "5d8a3612d0025e0012fba724",
        "model": "5d8a3319d0025e0012fba0fa",
        "id": "mqtt-lf2d0d",
        "name": "Объект 02",
        "status": "ok",
        "active": true,
        "group": "5d8a18d4d0025e0012fb6a31",
        "models": {
            "id": "5d8a3319d0025e0012fba0fa"
        }
    }
]

Получение информации об одном объекте

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

Запрос

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

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8a3612d0025e0012fba724",
    "model": "5d8a3319d0025e0012fba0fa",
    "id": "mqtt-elisalena99-lf2d0d",
    "name": "mqtt-elisalena99-lf2d0d",
    "status": "ok",
    "active": true,
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "success": true
}

Создание объекта

Для регистрации нового объекта контроля в системе необходимо отправить запрос POST /api/v1/objects с указанием требуемых полей. Обязательными полями являются id и name. В ответе будет указана сформированная конфигурация созданного объекта и результат выполенния запроса.

Запрос

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

{ 
  "id":"SOME_OBJECT_ID", 
  "name":"SOME_OBJECT_NAME",
}

Ответ

HTTP/1.1 200 OK

{
    "id": "someID3458374",
    "name": "Object 03",
    "model": "5d8a3319d0025e0012fba0fa",
    "status": "ok",
    "active": true,
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "time": 1569340547109,
    "_id": "5d8a3c83d0025e0012fbb4ca",
    "success": true
}

Изменение объекта

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

Запрос

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

{ 
    "status": "в поломке"
}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8a3c83d0025e0012fbb4ca",
    "id": "someID3458374",
    "name": "Object 03",
    "model": "5d8a3319d0025e0012fba0fa",
    "status": "в поломке",
    "active": true,
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "time": 1569340547109,
    "_at": 1569340835269,
    "success": true
}

Удаление объекта

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

Запрос

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

Ответ

HTTP/1.1 200 OK

{
    "id": "someID3458374",
    "name": "Object 03",
    "model": "5d8a3319d0025e0012fba0fa",
    "status": "ok",
    "active": true,
    "owner": "5d8a18d5d0025e0012fb6a34",
    "group": "5d8a18d4d0025e0012fb6a31",
    "models": {
        "id": "5d8a3319d0025e0012fba0fa"
    },
    "time": 1569340547109,
    "_id": "5d8a3c83d0025e0012fbb4ca",
    "success": true
}

Получение журнала данных объекта

При получении журнала объекта реализуется загрузка пакетов данных из истории. При этом с помощью двух различных методов может быть получено как несколько пакетов, так и один.

С ресурсом /api/v1/objects/:id/packets можно работать как со списком пакетов данных, отправляемых объектом. При использовании данного метода рекомендуется использовать параметры begin и end, которые обозначают нижнюю и верхнюю границу интервала времени соответственно. Стоит не забывать о том, что временные границы могут быть заданы либо в формате Unix Timestamp (в миллисекундах), либо в формате ISO 8601 (YYYY-MM-DDThh:mm).

Запрос

GET api/v1/objects/5a718f4543af42110079e8a4/packets?begin=1569326400000&end=1569351600000 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

[
    {
        "_id": "5d8a0547bada12100036a26f",
        "_ts": 1569326407527500,
        "lx": 5,
        "ly": -58,
        "lz": 846,
        "humidity": 18.85,
        "temperature": 29.37,
        "Fahrenheit": 28.17,
        "online": true,
        "time": 1569326407527
    }
]

Для получения одного пакета данных необходимо послать запрос GET /api/v1/objects/:id/packets/:packetID с указанием идентификационного номера того пакета, данные которого требуется загрузить.

Запрос

GET /api/v1/objects/:id/packets/:packetID HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

Ответ

HTTP/1.1 200 OK

{
    "_id": "5d8a0547bada12100036a26f",
    "_ts": 1569329888806500,
    "lx": 8,
    "ly": -79,
    "lz": 785,
    "humidity": 19.36,
    "temperature": 29.27,
    "faringate": 28.17,
    "online": true,
    "time": 1569329888806
}

Отправка команд

Отправка команды из платформы на устройство осуществляется через запрос POST /objects/:id/commands/:command. В данном запросе вместо :id указывается идентификационный номер объекта, вместо :command — наименование команды, которую нужно отправить. В теле запроса вводятся параметры и их значения, необходимые для выполнения команды.

Запрос

POST /objects/:id/commands/:command HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

{
  "param1": "value1",
  "param2": "value2"
}

Ответ

HTTP/1.1 200 OK
Content-Length: ~

{
  "success": true
}

События WebSocket

Событие object-packet

Событие возникает при поступлении нового пакета от устройства. Формат пакета аналогичен ранее описанному.

Событие object-update

Событие возникает при обновлении одного из полей объекта контроля.

interface ObjectUpdateMessage {
  id     : String; /* Идентификатор объекта */
  before : Object; /* Набор полей до изменения */
  after  : Object; /* Набор полей после изменения */
}

Пример

{
  id: "55cefff8e803589a52ec11d0", 
  before: {name: "object name"}, 
  after: {name: "new object name"}
}