☰
mini logo

/rukovodstvo-polzovatelya/vzaimodejstvie-so-storonnimi-sistemami/opisanie-api-dlya-integratsii-sistemy-energoatlas-s-vneshnimi-sistemami.html (md)

Адрес API имеет следующий вид http(s)://<ip адрес или доменное имя>/api2.

Общие принципы работы

Для аутентификации пользователей в API применяются access tokensrukovodstvo-polzovatelya/тся отдельный метод API. Требуемое действие определяется через HTTP Verb (GET/POST/PUT/DELETE), семантика действия описывается в документации. Не описанные действия считаются невалидными. Результат выполнения каждого метода возвращается в HTTP Status Code, в случае ошибки также выдается текстовое описание случившейся ошибки. Все входные параметры метода можно передавать в теле запроса (в таком случае оно должно быть валидным JSON-объектом). Структура объекта описывается отдельно для каждого метода. В целях совместимости с большим количеством HTTP-клиентов допускается использование метода POST вместо метода GET при наличии параметров, передаваемых в теле запроса. Сервер будет одинаково отрабатывать варианты с GET и POST.

Версионирование

Версия API доступна по урлу /api2. В дальнейшем будет меняться этот элемент урла (api3, api4 итд). Впрочем, в ближайшем будущем введение новых версий не планируется.

Доступные методы API

Важно! Далее по тексту все параметры запросов отмеченные звездочкой (*) обязательны для заполнения!

Авторизация POST auth/open

В объекте запроса передаются имя пользователя и пароль. В ответе система выдает токен для доступа к API. Токен становится невалидным через 10 минут неактивности (отсутствия запросов с этим токеном). Для всех запросов кроме этого в заголовке требуется передавать полученный токен (согласно спецификации OAuth 2).

Параметры запроса:

Запрос:

POST /api2/auth/open HTTP/1.1

{
  "login":"Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в браузере должен быть включен Javascript.",
  "password":"password123"
}

Ответ:

{
  "token":"rTetshrbhjYnAzMQaxgNqjHDizvzvRyI"
}

Описание возвращаемых полей:

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

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

Параметры запроса:

Запрос:

GET /api2/company HTTP/1.1

[]

Ответ:

[{
  "id":14,
  "name":"My General Company"
},{
  "id":26,
  "name":"My Sub Company"
}]

Описание возвращаемых полей:

Получение списка объектов компании GET company/objects

Выдает список объектов в компании включая дочерние. Если идентификатор компании в запросе не передан, предполагается компания, к которой относится запрашивающий пользователь.

Параметры запроса:

Запрос:

GET /api2/company/objects HTTP/1.1

{
  "id": 26
}

Ответ:

[{
  "id": 218,
  "name": "название объекта",
  "address": "адрес",
  "latitude": "географическая широта объекта",
  "longitude": "географическая долгота объекта",
  "devices":[{
    "id": 34567,
    "name": "название прибора",
    "title": "модель прибора (тип)",
    "time_offset": 0,
    "nodes_count": 5
  },{
    "id": 73844,
    "name": "название прибора 2",
    "title": "модель прибора 2 (тип)",
    "time_offset": 0,
    "nodes_count": 3
  }]
}]

Описание возвращаемых полей:

Получение детальной информации по объекту GET object

Выдает информацию по объекту.

Параметры запроса:

Запрос:

GET /api2/object HTTP/1.1

{
  "id":218
}

Ответ:

{
  "id": 2467,
  "name": "название",
  "address": "адрес",
  "latitude": "географическая широта объекта",
  "longitude": "географическая долгота объекта",
  "devices": [{
    "id": 24518,
    "serial": "серийный номер прибора",
    "name": "название прибора",
    "type": "модель прибора (тип)",
    "time_offset": 0,
    "nodes_count": 5,
    "period": 3600,
    "dt_reg": "2016-03-23 10:23:34",
    "first_update": "2016-03-23 10:51:22",
    "last_update": "2018-02-11 22:43:53"
  }]
}

Описание возвращаемых полей:

Получение списка мнемосхем на объекте GET object/schemes

Выдает информацию по объекту.

Параметры запроса:

Запрос:

GET /api2/object/schemes HTTP/1.1

{
  "id":2467
}

Ответ:

[{
  "id": 123
  "name": "Закрытая система отопления (УУ1) (рекомендованная 1СИМ для УУ-1)"
},{
  "id": 124,
  "name": "Закрытая система отопления (УУ1) (рекомендованная ЕКС для УУ-1)" 
},{
  "id": 125,
 "name": "Закрытая система отопления (УУ1) (рекомендованная ЕКС для УУ-1)"
},{
  "id": 126,
 "name": "Закрытая система отопления, ГВС с циркуляцией (УУ1) (Общая)"
}]

Описание возвращаемых полей:

Получение png изображения мнемосхемы GET scheme/print

Выдает изображение мнемосхемы в формате png.

Параметры запроса:

Запрос:

GET /api2/scheme/print HTTP/1.1

{
  "id":123
}

Ответ:

png файл

Работа с узлами учёта

Получение списка узлов учета на устройстве GET device/nodes

Выдает список узлов учета на устройстве.

Параметры запроса:

Запрос:

GET /api2/device/nodes HTTP/1.1

{
  "id":218
}

Ответ:

[{
  "id": 12345,
  "node_num": 0,
 "name": "Общие параметры",
 "is_active": 1,
 "resource_type": “unknown”    
},{
 "id": 12346,
 "node_num": 1,
 "name": "ГВС",
 "is_active": 1,
 "resource_type": “hw”
},{
 "id": 12347,
 "node_num": 2,
 "name": "ХВС",
 "is_active": 1,
 "resource_type": “cw”
}]

Описание возвращаемых полей:

При этом если УУ измеряет определённый тип ресурса, то на нём будет параметр, соответствующий этому ресурсу и отображающий потребленное количество ресурса. Для тепловой энергии код этого параметра Q, для электроэнергии E (также могут быть коды E_t1, E_t2, E_t3, E_t4 для потребленной энергии по разным тарифам). Для остальных типов ресурсов используется код V.

Добавление или изменение узла учёта PUT node

Изменяет параметры узла учета или создает новый.

Параметры запроса:

Запрос:

PUT /api2/node HTTP/1.1

{
  "device_id": 12346,
  "node_num": 1,
  "name": "Новое наименование узла учета №1",
  “is_active”: 1
}

Ответ:

Отсутствует, кроме стандартного HTTP-кода результата

Работа с параметрами

Получение списка параметров на устройстве GET device/values

Выдает список параметров на устройстве.

Параметры запроса:

Запрос:

GET /api2/device/values HTTP/1.1

{
  "id": 7639,
  "data_type": "h",
  "node_num": 1
}

Ответ:

[{
  "id": 123456,
  "node_num": 1,
  "code": "t1",
  "data_type": "h",
  "physicname": "tпод",
  "descr": "Температура в подающем трубопроводе",
  "measurement": "deg"
  "val": "75.15",
  "last_dt": "2018-02-14 10:25:00",
  "visible": 1,
  "expired": 1,
  "is_main_metering": 1,
  "computation_mode": 0
},{
  "id": 123457,
  "node_num": 1,
  "code": "t2",
  "data_type": "h",
  "physicname": "tобр",
  "descr": "Температура в обратном трубопроводе",
  "measurement": "deg"
  "val": "53.6",
  "last_dt": "2018-02-14 10:25:00",
  "visible": 1,
  "expired": 1,
  "is_main_metering": 1,
  "computation_mode": 0
}]

Описание возвращаемых полей:

Получение данных параметров GET values

Выдает значений параметров.

Параметры запроса:

Запрос:

GET /api2/values HTTP/1.1

{
  "ids": [25643,54564,34645,45355]
}

Ответ:

Формат выходных параметров и прочие особенности идентичны методу GET device/values

Получение данных по параметру GET values/data

Параметры запроса:

При указании start_dt и end_dt настоятельно рекомендуется использовать формат даты и времени с указанием временной зоны. В противном случае сервер будет использовать таймзону сервера (обычно это московское время). В результат запроса будут включены обе границы заданного временного интервала.

Запрос:

GET /api2/values/data HTTP/1.1

{
  "ids": [25643,54564,34645,45355],
  "start_dt": "2018-01-01 00:00:00",
  "end_dt": "2018-02-01 00:00:00"
}

Ответ:

[{
  "id": 25643,
  "data": [{           
    "dt": "2018-01-01 00:00:00",      
    "val": "78.4",    
    "fault": 0  
  },{          
    "dt": "2018-01-01 00:01:00",      
    "val": "78.3",   
    "fault": 0      
  }]
},{ 
  "id": 54564,   
  "data": [{     
    "dt": "2018-01-01 00:00:00",         
    "val": "67.9",      
    "fault": 0  
  },{            
    "dt": "2018-01-01 00:01:00",      
    "val": "67.8",  
    "fault": 0         
  }] 
}]

Описание возвращаемых полей:

Стоит также отметить, что при чтении архивов timestamp данных в базе формируется без учета временной зоны, поэтому если нужен посуточный архив за 2015-01-01, нужно запрашивать значение с меткой времени 2015-01-01 00:00:00MSK. Такой эффект связан с тем, что некоторые устройства не выдают таймзону, в которой установлен устройство, только время на локальных часах, поэтому для унификации временная зона не учитывается. Впрочем, сами данные архива формируются по его локальным часам. Пользователям API следует учитывать, что запрос чрезмерного количества данных может привести к ошибкам вида "Bad Request" или "Internal Server Error". Рекомендуется запрашивать не более 10 месяцев данных (либо 1 параметр на интервале 10 месяцев, либо 10 параметров по месяцу). При запросе большого количества параметров рекомендуется ограничить интервал одним днём. Для параметров читаемых с устройства будут выданы значения за те моменты времени, в которые эти параметры были с устройства получены. Для рассчитываемых параметров будут выданы значения также за те моменты, в которые с устройства приходили очередные пакеты с данными.

Получение последних значений параметров на момент времени GET values/last-data

Метод выдает последние данные по указанным параметрам до момента end_dt.

Параметры запроса:

Запрос:

GET /api2/values/last-data HTTP/1.1

{
  "ids": [25643,54564,34645,45355],
  "end_dt": "2018-02-01 00:00:00"
}

Ответ:

Формат выходных параметров и прочие особенности идентичны методу GET values/data.

Добавление параметров PUT device/values

Добавляет новые параметры на заданном устройстве. Если параметр с заданным code, data_type и node_num уже существует, его данные обновляются. Нулевой номер узла учета соответствует "Общим параметрам" системы.

Параметры запроса: ○

Запрос:

PUT /api2/device/values HTTP/1.1

{
  "id": 12345,
  "values": [{
    "node_num": 1,
    "code": "t1",
    "physicname": "tпод",
    "data_type": "d",
    "descr": "Температура в подающем трубопроводе",
    "aggr_mode": "avg",
    "measurement": "deg"
  }]
}

Ответ:

{    
  "status": [{
    "code": "t1",
    "node_num": 1,
    "data_type": "d", 
    "result": 200,
    "id": 2392145
  }]
}

Описание возвращаемых полей:

Запись данных по параметрам PUT values/data

Этот метод загружает в систему данные по заданным параметрам.

Параметры запроса:

Запрос:

PUT /api2/values/data HTTP/1.1

{
  "dt": "2018-01-01 10:00:00",    
  "data": [{
    "value_id": 21354245,
    "val": 70.05,
    "fault": 0
  }]
}

Ответ:

Выходных параметров у метода нет (кроме стандартного HTTP-кода результата).

Работа с аварийными критериями

Получение списка аварийных критериев на устройстве GET device/limits

Параметры запроса:

Запрос:

GET /api2/device/limits HTTP/1.1

{
  "id": 12345
}

Ответ:

[{
  "id": 2345,
  "node_num": 1,  
  "mathexpstr": "t1-t2>50",   
  "latchable": 1,  
  "active": 1,    
  "latch_message": "Разница температур слишком большая",  
  "unlatch_message": "Разница температур в норме",    
  "state": 0,     
  "log_type_id": 3,   
  "oneshot": 0  
}]

Описание возвращаемых полей:

Получение истории срабатывания аварийных критериев на устройстве GET device/limit-log

Параметры запроса:

Запрос:

GET /api2/device/limit-log HTTP/1.1

{
  "id": 25643,
  "start_dt": "2018-01-01 00:00:00",
  "end_dt": "2018-02-01 00:00:00"
}

Ответ:

[{
  "limit_id": 653749,
  "latch_dt": "2018-01-18 12:30:00",
  "latch_message": "Разница температур слишком большая", 
  "unlatch_dt": "2018-01-18 18:05:00",
  "unlatch_message": "Разница температур в норме"
}]

Описание возвращаемых полей:

Пример на РНР по работе с API системы Энергоатлас api_example.zip