Описание API для интеграции системы Энергоатлас с внешними системами

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

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

Для аутентификации пользователей в API применяются access tokens, передаваемые в заголовке согласно спецификации OAuth 2. На начальном этапе эксплуатации API для получения токена используется отдельный метод 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).

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

• login* — имя пользователя (e-mail), используемое для входа в систему
• password* — пароль

Запрос:

POST /api2/auth/open HTTP/1.1

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

Ответ:

{
  "token":"rTetshrbhjYnAzMQaxgNqjHDizvzvRyI"
}

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

• token — токен для авторизации

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

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

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

• Пустой массив

Запрос:

GET /api2/company HTTP/1.1

[]

Ответ:

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

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

• id — идентификатор компании
• name — краткое название компании

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

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

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

• id — идентификатор компании

Запрос:

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
  }]
}]

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

• id — идентификатор объекта;
• name — название;
• address — адрес;
• latitude — географическая широта объекта;
• longitude — географическая долгота объекта;
• canManage — возможность создавать параметры на устройствах данного объекта или записывать значения параметров (0 — нет, 1 — да);
• devices — список устройств, установленных на объекте:
  • id — идентификатор устройства;
  • name — название устройства;
  • title — модель устройства (тип);
  • time_offset — сдвиг времени устройства относительно времени на сервере, в минутах;
  • nodes_count — количество УУ на устройстве. Нумерация УУ ведётся с нуля, УУ с номером 0 соответствует общим параметрам устройства. Например для МКТС (у которого 4 УУ) система вернёт в этом поле число 5.

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

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

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

• id* — идентификатор объекта

Запрос:

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"
  }]
}

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

• id — идентификатор объекта;
• name — название;
• address — адрес;
• latitude — географическая широта объекта;
• longitude — географическая долгота объекта;
• devices — список устройств, установленных на объекте:
  • id — идентификатор устройства;
  • serial — серийный номер устройства;
  • name — название устройства;
  • type — модель устройства (тип);
  • time_offset — сдвиг времени устройства относительно времени на сервере, в минутах;
  • nodes_count — количество УУ на устройстве. Нумерация УУ ведётся с нуля, УУ с номером 0 соответствует общим параметрам устройства. Например для МКТС (у которого 4 УУ) система вернёт в этом поле число 5;
  • period — период опроса устройства;
  • dt_reg — дата регистрации устройства в системе;
  • first_update — дата получения первых данных;
  • last_update — дата получения последних данных.

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

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

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

• id* — идентификатор объекта

Запрос:

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) (Общая)"
}]

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

• id — идентификатор мнемосхемы;
• name — название мнемосхемы.

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

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

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

• id* — идентификатор мнемосхемы

Запрос:

GET /api2/scheme/print HTTP/1.1

{
  "id":123
}

Ответ:

png файл

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

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

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

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

• id* — идентификатор устройства

Запрос:

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”
}]

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

• id — идентификатор УУ из базы
• node_num — номер УУ в рамках устройства
• name — название УУ
• is_active — флаг активности УУ
• resource_type — тип ресурса, который измеряется на этом УУ
  •  unknown — Неизвестно
  •  cw — Холодная вода, Кубический метр
  •  hw — Горячая вода, Кубический метр
  •  electro — Электрическая энергия, Киловатт-час
  •  gas — Газ, Кубический метр
  •  heat — Тепловая энергия, Гигакалория
  •  sink — Сточные бытовые воды, Кубический метр

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

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

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

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

• device_id* — идентификатор устройства;
• node_num* — номер узла учета;
• name* — название;
• is_active* — флаг активности.

Запрос:

PUT /api2/node HTTP/1.1

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

Ответ:

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

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

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

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

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

• id* — идентификатор устройства;
• data_type — тип данных c/h/d/i (если не указан, будут выданы все);
• node_num — номер УУ (если не указан, будут выданы параметры со всех УУ).

Запрос:

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
}]

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

• id — идентификатор параметра;
• node_num — номер УУ в рамках устройства;
• code — строковый код параметра. Гарантируется, что на одном узле учета не будет двух параметров с одинаковыми code и data_type;
• data_type — тип данных (c/h/d/i — моментальный/почасовой/посуточный/интегральный);
• physicname — физическое название параметра (например Мхв, V1);
• descr — человекочитаемое описание параметра ("Температура в первом трубопроводе");
• measurement — единицы измерения параметра;
• val — текущее значение параметра (отображается в системе);
• last_dt — дата и время получения последнего значения параметра (во временной зоне МСК, с указанием таймзоны);
• visible — помечен ли параметр как "видимый" в интерфейсе (1 — да, 0 — нет);
• expired — устарело ли значение параметра (1 — да, 0 — нет);
• is_main_metering — является ли этот параметр основным измеряемым ресурсом (1 — да, 0 — нет);
• computation_mode — режим вычисления, число: 
  • 0 — NONE;
  • 1 — EXPRESSION;
  • 2 — INTEGRATE_CURRENT;
  • 3 — AVERAGE_CURRENT;
  • 4 — DIFFERENTIATE_CURRENT;
  • 5 — SLIDING_AVERAGE;
  • 6 — SUM_HOURLY;
  • 7 — AVERAGE_HOURLY;
  • 8 — SUM_IN_MONTH;
  • 9 — AVERAGE_IN_MONTH;
  • 10 — TRANSFER_CURRENT;
  • 11 — BITWISE_OR_HOURLY;
  • 12 — BITWISE_AND_HOURLY.

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

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

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

• ids* — массив идентификаторов параметров

Запрос:

GET /api2/values HTTP/1.1

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

Ответ:

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

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

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

• ids* — массив идентификаторов параметров, данные которых требуется получить;
• start_dt* — дата и время начала интересующего интервала;
• end_dt* — дата и время окончания интересующего интервала.

При указании 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         
  }] 
}]

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

• id — идентификатор параметра
• data — данные. Это массив объектов с такими полями:
  • dt — дата и время
  • val — значение
  • fault — код ошибки

Стоит также отметить, что при чтении архивов 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.

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

• ids* — массив идентификаторов параметров, данные которых требуется получить;
• 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 уже существует, его данные обновляются. Нулевой номер узла учета соответствует "Общим параметрам" системы.

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

• id* — идентификатор устройства;
• values* — список добавляемых/обновляемых параметров. Массив объектов со следующими полями:* 
  • code* — текстовый код (строка, не длиннее 20 символов, только ASCII). Рекомендуется использовать мнемонические коды, например V1, Mhw, T_work;
  • physicname* — физическое название параметра (например Мхв, V1);
  • data_type* — тип параметра (c/h/d/i);
  • descr* — человекочитаемое название параметра;
  • aggr_mode* — режим аггрегации (используется при построении отчетов). Возможные значения — sum и avg. Соответственно параметр в отчете будет либо суммироваться, либо усредняться по времени;
  • measurement* — единицы измерения параметра:
    • byte — байт;
    • int — целое;
    • float — с плавающей точкой;
    • deg — температура;
    • kgf/cm2 — давление;
    • t/h — массовый расход;
    • bool — логическое;
    • Gcal/h — тепловая мощность;
    • m3/h — объемный расход;
    • kWh — электрическая энергия;
    • kW — электрическая мощность;
    • t — масса;
    • Gcal — тепловая энергия;
    • m3 — объем;
    • none — отсутствует;
    • percent — процент;
    • h — время;
    • kPa — давление;
    • atm — давление;
    • MPa — давление;
    • mmhg — давление;
    • rouble — рубли;
    • ms — миллисекунды;
    • MWh — электрическая энергия;
    • MW — электрическая мощность;
    • GJ — тепловая энергия;
    • W — электрическая мощность;
    • bar — давление;
    • m3/min — объемный расход;
    • kg/h — массовый расход;
    • J/h — тепловая мощность;
    • m3/sec — объемный расход;
    • GJ/h — тепловая мощность;
    • grad — угол;
    • V — напряжение;
    • A — сила тока;
    • Hz — частота;
    • l — объем;
    • m — длина;
    • R/Gcal — тариф;
    • mm — длина;
    • short — короткое целое;
    • float2 — вещественное;
    • float3 — вещественное;
    • sec — секунды;
    • mA — миллиамперы;
    • kVArh — электрическая энергия;
    • kVAr — электрическая мощность;
    • n.m3 — объем нормальный;
    • m3/day — дебит скважины;
    • t/m3 — плотность;
    • km/h — скорость;
    • float.swap — с плавающей точкой (инвертированный порядок байт);
    • m/s — скорость;
    • m3M — объём;
    • Pa — давление;
    • day — время;
    • cm — длина;
    • rpm — обороты в минуту;
    • nm — крутящий момент;
    • J/kg — энтальпия;
    • kg/s — массовый расход;
    • J — энергия;
    • kg/m3 — плотность;
    • kg — масса;
    • m3/s — объёмный расход;
    • ppm — концентрация;
    • l/min — объёмный расход;
    • int.swap — целое (инвертированный порядок байт 3-2-1-0);
    • short.swap — короткое целое (инвертированный порядок байт);
    • int.rswap — целое (инвертированный порядок регистров 2-3-0-1);
    • deg/min — диапазон dT/dt;
    • float.rswap — с плавающей точкой (инвертированный порядок регистров 2-3-0-1):
  • mathexpstr — формула вычисления параметра (синтаксис соответствует редактору формул). Если параметр не вычисляемый, поле передавать не нужно;
  • comment — комментарий к параметру.

Запрос:

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
  }]
}

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

• status — массив результатов добавления параметров:
  • code — код;
  • node_num — номер узла учета;
  • data_type — тип данных;
  • result — результат добавления (HTTP-код, 200 — успех, остальные — неудача);
  • id — полученный параметром идентификатор (если успешно добавлен);
  • comment — комментарий об ошибке (если есть).

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

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

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

• dt* — момент времени, к которому относятся данные;
• data* — сами данные, это массив объектов со следующими полями:
  • value_id* — идентификатор параметра;
  • val* — значение;
  • fault — код ошибки.

Запрос:

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

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

• id* — идентификатор устройства.

Запрос:

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  
}]

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

• id — идентификатор аварийного события;
• node_num — номер узла учета, к которому относится авария;
• mathexpstr — строка-условие;
• latchable — защелкиваемая или нет (0/1);
• active — активна (0 — нет, 1 — да);
• latch_message — сообщение при защелкивании;
• unlatch_message — сообщение при отщелкивании;
• state — текущее состояние (0 — защелкнута, 1 — отщелкнута);
• log_type_id — журнал, в котором находится авария;
• oneshot — является ли аварией, деактивирующейся после срабатывания.

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

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

• id* — идентификатор устройства;
• start_dt* — время начала;
• end_dt* — время окончания.

Запрос:

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": "Разница температур в норме"
}]

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

• limit_id — идентификатор аварии;
• latch_dt — время срабатывания (защелкивания);
• latch_message — сообщение в момент срабатывания;
• unlatch_dt — время выключения (отщелкивания) или null, если авария незащелкиваема или ещё активна;
• unlatch_message — сообщение в момент выключения (аналогично null, если авария незащелкиваема или ещё активна).

  ---

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