Объекты контроля
Работа в платформе 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, относятся:
- Получение списка объектов;
- Получение информации об одном объекте;
- Создание объекта;
- Изменение объекта;
- Удаление объекта;
- Получение журнала данных объекта;
- Отправка команд;
- События 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"}
}