Использование API облачного сервиса OwenCloud (часть 1)
Облачный сервис OwenCloud предназначен для дистанционного контроля и управления автоматизированными системами.
Сервис предоставляет доступ к информации о показателях технологических параметров приборов (в виде таблиц, графиков и мнемосхем), сигналам тревоги (с возможностью отправки уведомлений через SMS, электронную почту, Telegram-бот и push-уведомления на мобильные устройства), а также позволяет создавать отчёты и корректировать значения управляющих параметров (установок, настроек регуляторов и т. д.).
Кроме того, сервис даёт возможность интегрироваться с другими приложениями через API. В этой статье мы объясним простыми словами, что такое API, как его использовать (на примере) и для каких целей он может быть полезен.
Что такое API?
API (Application Programming Interface) — это набор правил для взаимодействия компьютерных приложений, который позволяет использовать функции одного приложения внутри другого.
Например, если вы хотите узнать текущую погоду, вы можете зайти на сайт (например, https://openweathermap.org/), где есть информация о температуре, влажности, ветре и других погодных параметрах.
Теперь представим, что вы создаёте программу, которой требуется такая же информация, например, для управления отоплением в зависимости от погоды.
Как передать эти данные вашей программе? Именно для решения подобных задач предназначен API. Этот ресурс также доступен по ссылке.
API содержит описание операций, которые можно выполнить с объектом (объект может быть веб-сервисом, приложением на компьютере, операционной системой и так далее). Эти операции называются методами. Например, для получения информации о текущей погоде используется метод weather. Его описание выглядит следующим образом:
https://api.openweathermap.org/data/2.5/weather?lat="44.34"&lon="... key}
Эта строка описывает HTTP-запрос, который необходимо отправить сервису для получения текущих погодных условий. Рассмотрим его составные части:
- https://api.openweathermap.org — это протокол (HTTPS) и адрес веб-ресурса, на который отправляется запрос;
- data — это категория запроса. Категория data содержит информацию о погоде. У сервиса также есть другие категории, например maps, содержащая информацию о синоптических картах;
- 2.5 — это версия API. Обычно в новых версиях поддерживаются новые функции или расширяются существующие. Хороший API обладает обратной совместимостью, то есть новые версии поддерживают старые методы без изменений;
- weather — это название метода. После символа «=» указаны аргументы запроса. В данном случае они передаются непосредственно в строке запроса, но возможны и другие варианты, например передача аргументов в формате JSON. Аргументы представляют собой пары «название» = «значение»;
Рассматриваемый нами метод имеет три обязательных аргумента — широту (lat), долготу (lon) и токен пользователя (API key). В примере вместо реального значения токена используется заполнитель {API key}, который разработчик должен заменить своим токеном.
Широта и долгота определяют координаты, для которых будет предоставлена информация о погоде. Токен используется для разделения пользователей. Например, пользователь с бесплатным тарифным планом, полученным при регистрации в сервисе, может сделать только 1000 вызовов API в течение дня.
Для клиентов, использующих платные тарифы, ограничения меньше. Токен в этой системе позволяет сервису определить тарифный план клиента. сигнал аварии на входе – мигает.
Ответ на запрос возвращается в формате JSON:
{
"coord":{
"lon":10.99,
"lat":44.34
},
"weather":[
{
"id":501,
"main":"Rain",
"description":"moderate rain",
"icon":"10d"
} ],
"base":"stations",
"main":{
"temp":298.48,
"feels_like":298.74,
"temp_min":297.56,
"temp_max":300.05,
"pressure":1015,
"humidity":64,
"sea_level":1015,
"grnd_level":933
},
"visibility":10000,
"wind":{
"speed":0.62,
"deg":349,
"gust":1.18
},
"rain":{
"1h":3.16
},
"clouds":{
"all":100
},
"dt":1661870592,
"sys":{
"type":2,
"id":2075663,
"country":"IT",
"sunrise":1661834187,
"sunset":1661882248
},
"timezone":7200,
"id":3163858,
"name":"Zocca",
"cod":200
}
Большинство параметров в ответе понятны интуитивно. Их подробное описание можно найти в документации по API.
На уровне приложения разработчик должен проанализировать этот ответ, извлечь необходимые данные (это легко, так как для работы с JSON существует множество библиотек почти для всех языков программирования) и использовать их в своём коде.
API OwenCloud
Давайте снова обратимся к OwenCloud. У него тоже есть API, позволяющий «программно» выполнять те же действия, которые пользователь может выполнить в веб-интерфейсе сервиса.
- прочитать текущие и исторические значения параметров;
- записать значения параметров;
- получить информацию о произошедших событиях;
- прочитать информацию о приборах, добавленных в аккаунт пользователя;
- добавить новый прибор;
- и т. д.
Описание API OwenCloud приведено по ссылке: https://api.owencloud.ru/
API предоставляется бесплатно, однако есть ограничение на количество запросов, обрабатываемых за 10-секундный интервал с одного IP-адреса. Время начинает отсчитываться с первого запроса в новой последовательности запросов. Если лимит превышен, возвращается код состояния 429 (Too Many Requests).
Ниже приведены ограничения:
- /v1/parameters/last-data – не более 10 запросов за 10 секунд;
- /v1/device/index – не более 10 запросов за 10 секунд;
- /v1/parameters/data – не более 10 запросов за 10 секунд;
- /v1/auth/open – не более 10 запросов за 10 секунд;
- все остальные запросы – не более 30 запросов за 10 секунд.
Давайте разберёмся, как использовать API на практике. Для этого скачайте и установите программу Advanced REST Client — это графический клиент для тестирования API.
В качестве примера мы будем работать с устройством Метеостанция, которое уже добавлено в демо-аккаунт облачного сервиса. Зайдите в сервис и в окне авторизации нажмите кнопку Демо-вход.
В реальной жизни метеостанция — это контроллер ПЛК110 [М02], размещённый в нашем офисе, к которому подключены датчик температуры ПВТ10 и датчик концентрации углекислого газа ПКГ100-CO2 промышленный датчик (преобразователь) концентрации углекислого газа в воздухе. ПЛК имеет дискретный выход, управляющий светосигнальной колонной MeyrtecMT45, которая помогает легко определить, когда нужно проветрить помещение.
Как получить токена
Прежде чем использовать какой-либо метод API, необходимо получить токен (идентификатор пользователя). Для этого применяется метод auth/open. Обратите внимание, что все методы API в OwenCloud используют POST-метод протокола HTTP(S). Пример запроса из документации выглядит так (наиболее важная часть выделена жирным шрифтом):
POST /v1/auth/open HTTP/1.1
Host: api.owencloud.ru
Accept: */*
Content-Length: 68
Content-Type: application/x-www-form-urlencoded
{
"login":"admin@owen.cloud",
"password":"password123"
}
В первом разделе представлен запрос и его заголовки, а во втором — данные, передаваемые в запросе. В примере из документации использовался конкретный аккаунт одного из разработчиков. Однако мы, как упоминалось ранее, будем работать с демонстрационным аккаунтом, поэтому используем следующие логин и пароль:
{
"login":"admin@owen.cloud",
"password":"password123"
}
Теперь соберём этот запрос в программе Advanced REST Client. Сначала выберем используемый HTTP-метод (как мы уже упоминали, для OwenCloud это всегда будет метод POST) и путь к методу API, который состоит из протокола (http:// или https:// — в примерах мы будем использовать второй вариант), имени сервера, на который отправляется запрос (указан в примере в поле host) и фрагмента /v1/auth/open (версия API/категория метода/название метода). Полный запрос будет выглядеть так:
POST https://api.owencloud.ru/v1/auth/open
Теперь, когда вы увидели пример из документации, вам должно быть понятно, как мы его создали. Тот же принцип будет применяться и ко всем остальным запросам.
Указанные в примере заголовки Accept, Content-Length и Content-Type можно не указывать — программа автоматически их создаст. Если хотите узнать, за что они отвечают, обратитесь к этой статье.
Теперь нажмите на кнопку Body и скопируйте в появившееся поле тело запроса.
{
"login":"demo@owen.ru",
"password":"demo123"
}
После этого нажмите кнопку отправки запроса, которая находится справа от строки с методом API.
В клиенте отобразится ответ облачного сервиса:
Нас интересует значение его первого поля (token). В нашем случае это WZRmH68SVJpBCpaiKEuCkw1RCHSZizGC. Ваш токен будет другим, так как при получении токена всегда создаётся уникальный токен. Этот токен используется в заголовке всех других запросов. Он позволяет идентифицировать пользователя облачного сервиса, благодаря чему при запросе списка устройств вы получите список устройств своего аккаунта, а не чужого. Если в течение 20 минут не было запросов с токеном к облачному сервису, он становится недействительным. Чтобы продолжить работу с API, необходимо получить новый токен.
Если вы допустите ошибку в данных запроса, вы получите ответ с кодом состояния (список кодов состояний HTTP приведён в этой статье). Например, предположим, что мы неправильно указали пароль пользователя в предыдущем запросе:
Теперь, когда мы знаем, как работать с документацией API, создавать запросы с помощью Advanced REST Client и получать токены, давайте изучим основные методы API OwenCloud.
Получение идентификатора прибора
Мы уже решили, что будем работать с метеостанцией из демонстрационного аккаунта. Было бы удобнее всего считать значения её параметров. Однако сначала нужно получить идентификатор этого устройства, а затем — идентификаторы нужных параметров.
Откроем пример вызова метода списка приборов в документации.
POST /v1/device/index HTTP/1.1
Accept: */*
Authorization: Bearer CYndQy1OwPtpal1OhrextgtIM7Bw5q3f
Content-Length: 13
Content-Type: application/x-www-form-urlencoded
{"filter":"100"}
Здесь нас интересуют две вещи:
- новый заголовок Authorization – в нем указывается токен, полученный нами в прошлом разделе;
- в теле запроса можно передать значение «фильтра». Фильтр представляет собой фрагмент имени (name) прибора/-ов, по которым мы хотим получить информацию (например, для фильтра "100" будет возвращена информация по всем приборам, в именах которых есть цифры «100»). Это удобно, если вы уже знаете имена нужных вам приборов. Но если вы их не знаете (как мы сейчас) – просто оставьте тело запроса пустым – в этом случае в ответе вернется информация по всем приборам аккаунта.
Создадим новый запрос.
Нажмите на кнопку ADD, выберите тип заголовка Authorization и в поле Value введите Bearer, а после него через пробел — токен, полученный ранее. В ответе на запрос найдите прибор с именем (поле name) имеет значение Метеостанция 5 этаж. Запишите его id (60546) — он понадобится в следующем запросе. Описание остальных параметров ответа приведено в документации API.
Получение идентификаторов параметров
Запрос информации о параметрах определённого устройства похоже на запрос информации обо всех устройствах — только вместо index нужно использовать идентификатор устройства, указанный в предыдущем разделе (для метеостанции это 60546).
В результате будет возвращён массив с данными о параметрах. Давайте создадим таблицу с кодами параметров (code) и их идентификаторов (id).
|
code |
id |
|
wHummidCloud |
1099136 |
|
wCo2Cloud |
1099138 |
|
wTempCloud< |
1099134 |
|
ValueSetting< |
15197930 |
Эти идентификаторы нужны для чтения и изменения значений параметров. Уникальность идентификаторов гарантируется на уровне облачной системы, то есть они не могут повторяться даже у разных устройств.
Остальные параметры ответа описаны в документации API.
Лайфхак для быстрого определения идентификаторов параметров на этапе отладки
Использование описанного в предыдущем пункте метода определения параметров через API является наиболее точным, так как идентификаторы могут изменяться, например, при корректировке конфигурации устройства в облаке.
В связи с этим рекомендуется избегать использования жёстко заданных значений идентификаторов в приложениях, работающих с API. Однако во время тестирования можно воспользоваться следующим методом: откройте страницу со списком параметров устройства в облачном сервисе и воспользуйтесь командой Просмотреть код в вашем браузере (например, в Google Chrome, щёлкните правой кнопкой мыши на странице и выберите соответствующую команду).
Затем наведите курсор на ячейку столбца Код параметра нужного вам параметра. Найдите этот код в окне просмотра (возможно, потребуется развернуть уровни вложенности, нажимая на стрелки) — прямо перед ним будет отображаться идентификатор этого параметра.
Чтение значений параметров
Имея идентификаторы параметров, можно организовать их чтение. Для этого используем метод parameters/last-data для получения текущих значений параметров.
Пример из документации:
POST /v1/parameters/last-data HTTP/1.1
Host: api.owencloud.ru
Accept: */*
Authorization: Bearer G78Fv1AfWN5JHirEVfAFnO1gAap3gKBR
Content-Length: 25
Content-Type: application/x-www-form-urlencoded
{"ids":[268191, 270292]}
В запросе указываются идентификаторы требуемых параметров. Мы используем идентификаторы параметров wHummidCloud (1099136), wCo2Cloud (1099138) и wTempCloud (1099134). Также необходимо заменить токен примера на ваш собственный токен.
{"ids":[1099136, 1099138, 1099134]}
В ответе для каждого параметра будет предоставлена следующая информация:
- d — временная метка получения значения в формате Unixtime. Чтобы преобразовать это значение в «понятный» формат, можно использовать онлайн-конвертер;
- v — «числовое» значение параметра;
- e — код ошибки (если в облаке вместо значения параметра отображается сообщение «Ошибка 255», то именно оно будет содержаться в параметре e);
- f — отформатированное значение, которое фактически отображается в облаке — то есть v с добавленными единицами измерения или кодом ошибки.
Для доступа к истории параметров применяются методы parameters/data, parameters/forward-data и parameters/backward-data. Их особенности и примеры использования представлены в документации API.
Запись значений параметров
Чтобы записать значение параметра, используйте метод parameters/write-data.
Пример из документации:
POST /v1/parameters/write-data HTTP/1.1
Host: api.owencloud.ru
Accept: */*
Authorization: Bearer CYndQy1OwPtpal1OhrextgtIM7Bw5q3f
Content-Type: application/x-www-form-urlencoded
{
"sms_tag":"3ca1eed2efaa183d0f32fb68099ead8f",
"sms_code":"69353",
"timeout":60,
"sync":true,
"data":[
{"id":237,"value":"2.9999"},
{"id":239,"value":"99"} ]
}
В настоящее время параметры sms_tag и sms_code не используются, так как предназначены для будущих обновлений облака, где может быть реализована функция подтверждения команды записи через SMS. Параметры timeout и sync отвечают за настройки Повторять попытки записи в течение и Не записывать, если значение в устройстве изменилось до момента записи в интерфейсе облачного сервиса.
Каждый записываемый параметр в массиве data содержит его идентификатор и значение. Метеостанция поддерживает запись только одного параметра — ValueSetting с идентификатором 15197930. Таким образом, тело нашего запроса будет выглядеть следующим образом (не забудьте заменить пример токена на ваш собственный):
{
"timeout":60,
"sync":true,
"data":[
{"id":15197930,"value":"123"} ]
}
В ответ на запрос возвращаются общий идентификатор запроса записи (writeGroupId) и идентификаторы запросов записи отдельных параметров (writeParamId).
Следует учесть, что логические значения должны быть записаны как false или true, а числа с плавающей точкой — с использованием точки в качестве разделителя целой и дробной частей. Если будет предпринята попытка записать некорректное значение или использовать идентификатор несуществующего параметра в данной учётной записи, в ответе будет содержаться информация об ошибке (дополнительную информацию можно найти в документации API).
Заключение
Мы изучили, что такое API, и на практике рассмотрели ключевые методы, применяемые при работе с API облачной платформы OwenCloud. Рассмотрим несколько примеров его использования:
- Официальные мобильные приложения OwenCloud для Android и iOS, а также плагин для интеграции с OwenCloud в Owen OPC Server основаны на использовании API;
- Компания ООО Быстрые Проекты разработала web-HMI, который использует их собственную систему визуализации для отображения данных, полученных от OwenCloud через API. Вот некоторые демонстрационные проекты: Мониторинг инженерных систем здания и Диспетчеризация теплового пункта.
Интеграция ваших приложений с OwenCloud через API позволит вам, например, мониторить системы и управлять ими.
