Использование API облачного сервиса OwenCloud (часть 1)

Облачный сервис OwenCloud используется для удаленного мониторинга и управления системами автоматизации.

Сервис предоставляет пользователю информацию о значениях технологических параметров приборов (в виде таблиц, графиков и мнемосхем), тревогах (с отправкой уведомлений по SMS, e-mail, в Telegram-bot, а также push-уведомлений для мобильных устройств), позволяет формировать отчеты и изменять значения управляющих параметров (уставок, настроек регуляторов и т. д.).

Еще он позволяет осуществлять интеграцию с другими приложениями – с помощью API. В данной статье мы попробуем простыми словами объяснить, что такое API, как его использовать (и рассмотрим это на примере), и для каких задач он может потребоваться.

Что такое API?

API – это аббревиатура от Application Programming Interface (программный интерфейс приложения). API представляет собой набор правил для взаимодействия компьютерных приложений, который позволяет использовать функции одного приложения внутри другого.

Проще пояснить это на примере: представьте, что вы решили посмотреть в интернете текущую погоду. Вы можете зайти на какой-нибудь сайт (например, https://openweathermap.org/) и получить там эту информацию – увидеть текущие и прогнозируемые значения температуры, влажности, скорости и направления ветра и т. д.

Теперь предположим, что вы разрабатываете приложение, которому необходима та же информация – например, для организации погодозависимого регулирования в системе отопления.

Возникает вопрос – как передать эту информацию вашему приложению? Именно для решения таких задач предназначен API. У упомянутого выше сайта он тоже есть и доступен по ссылке.

API представляет собой описание действий, которые можно совершить с объектом (объектом может быть web-сервис, приложение на ПК, операционная система и т. д.). Эти действия называются методами. Например, для получения информации о текущей погоде используется метод weather. Его описание выглядит следующим образом:

Эта строка представляет собой описание HTTP-запроса, который нужно отправить сервису для получения информации о текущей погоде. Рассмотрим ее отдельные составляющие:

• https://api.openweathermap.org – это протокол (https) и адрес web-ресурса, на который нужно отправить запрос;
• data – это категория запроса. Категория data содержит информацию о погоде. У сервиса есть и другие категории – например, maps, которая содержит информацию о синоптических картах;
• 2.5 – это версия API. Обычно в более новых версиях поддерживаются новые методы или расширяются существующие. Хорошо спроектированный API имеет обратную совместимость – то есть в новых версиях методы из старых версий работают без каких-либо изменений;
• weather – это название метода. После символа «=» перечислены аргументы запроса. Для данного web-сервиса они передаются прямо в строке запроса, но вообще варианты могут быть разными – например, аргументы могут передаваться в формате JSON. Аргументы представляют собой наборы пар «название»=«значение».
  Рассматриваемый нами метод имеет три обязательных аргумента – широту (lat), долготу (lon) и токен пользователя (API key). В примере вместо какого-то реального значения токена указан заполнитель {API key} – вместо него разработчик должен указать свой токен.
  С широтой и долготой всё ясно – так определяются координаты, для которых будет возвращена информация о погоде. Токен нужен для того, чтобы разграничить пользователей. Например, для пользователя с «бесплатным» тарифным планом, полученным при регистрации в сервисе, доступно только 1000 вызовов методов API в пределах дня.
  Для клиентов, использующих платные тарифы, ограничения существенно ниже. Токен в этой системе позволяет сервису определить тарифный план, используемый клиентом.

Ответ на запрос возвращается в формате JSON:

Большая часть параметров в ответе интуитивно понятна. Их полное описание приведено в документации по API.

На уровне приложения разработчику нужно будет разобрать этот ответ, выделить из него нужные данные (это довольно просто – для JSON написано множество библиотек практически для всех языков программирования) и использовать их в своем коде.

API OwenCloud

Теперь давайте вернемся к OwenCloud. Он тоже имеет API, который позволяет «программно» выполнять те же действия, который пользователь может совершить в web-интерфейсе сервиса:

• считать текущие и архивные значения параметров;
• записать значения параметров;
• получить информацию о произошедших событиях;
• считать информацию о добавленных в аккаунт пользователя приборах;
• добавить новый прибор;
• и т. д.

Описание 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 секунд.

Давайте разберемся, как его использовать на практике. Для этого загрузите и установите утилиту Advanced REST Client– она представляет собой графический клиент для тестирования API.

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

В реальности метеостанция представляет собой установленный в нашем офисе контроллер ПЛК110 [М02], к которому подключен датчик температуры ПВТ10 и датчик концентрации углекислого газа ПКГ100-CO2. Дискретный выход ПЛК управляет светосигнальной колонной MeyrtecMT45 – с ее помощью легко определить момент, когда пришло время проветрить помещение. :)

Получение токена

Прежде чем вызвать какой-либо метод API– нужно получить токен (идентификатор пользователя). Для этого используется метод auth/open. Важно отметить, что все методы API OwenCloud относятся к POST-методам протокола HTTP(S). Пример запроса из документации выглядит следующим образом (жирным выделена наиболее важная часть):

В первом блоке описан запрос и его заголовки (headers), во втором – передаваемые в запросе данные. В примере из документации использован конкретный аккаунт одного из разработчиков. Мы же, как уже упоминали выше, будем работать с демо-аккаунтом – так что используем вот такие логин и пароль:

Теперь «соберем» этот запрос в утилите Advanced REST Client. Для начала выберем используемый HTTP-метод (как мы уже говорили – для OwenCloud это всегда будет метод POST) и «путь» к методу API, который состоит из протокола (http:// или https:// – в примерах мы будем использовать второй из них), имени сервера, на который отправляется запрос (он указан в примере в поле host) и фрагмента /v1/auth/open (версия API/категория метода/имя метода). Полностью запрос будет выглядеть так:

Теперь посмотрите на пример из документации – и вы поймете принцип, по которому мы его сформировали. Этот же принцип будет использоваться и для всех остальных запросов.

Указанные в примере заголовки (Accept, Content-Length и Content-Type) можно не добавлять – утилита сформирует их автоматически. Если вас интересует, за что они отвечают – ознакомьтесь с этой статьей.

Теперь нажмите на кнопку Body и скопируйте в появившееся поле тело запроса:

После этого нажмите кнопку отправки запроса – она расположена справа от строки, в которой мы указывали метод API.

В клиенте отобразится ответ облачного сервиса:

Нас интересует значение его первого поля (token). В нашем конкретном случае это WZRmH68SVJpBCpaiKEuCkw1RCHSZizGC. У вас токен будет своим – потому что в ответ на запрос получения токена всегда возвращается уникальный токен. Токен используется в заголовке всех остальных запросов. Он позволяет идентифицировать пользователя облачного сервиса – именно за счет этого в ответ на запрос списка приборов вы получите список приборов вашего аккаунта, а не чьего-то еще. Если в течение 20 минут никаких запросов с токеном к облачному сервису не было – то он становится неактивным. Для продолжения работы с API потребуется получить новый токен.

Если вы ошибетесь в данных запроса, то получите ответ с кодом статуса (список кодов статусов HTTP приведен в этой статье). Предположим, мы некорректно указали пароль пользователя в предыдущем запросе:

Итак, мы разобрались, как использовать документацию на API, формировать запросы через утилиту Advanced REST Client и получать токен. Дальше рассмотрим наиболее часто используемые методы API OwenCloud.

Получение идентификатора прибора

Мы уже определились, что будем работать с метеостанцией из демо-аккаунта. Нагляднее всего было бы считать значения ее параметров. Но для этого сначала надо получить идентификатор этого прибора, а потом – идентификаторы нужных параметров.

Откроем в документации примера вызова метода «Вывод списка приборов».

Здесь нас интересуют две вещи:

• новый заголовок Authorization – в нем указывается токен, полученный нами в прошлом разделе;
• в теле запроса можно передать значение «фильтра». Фильтр представляет собой фрагмент имени (name) прибора/-ов, по которым мы хотим получить информацию (например, для фильтра "100" будет возвращена информация по всем приборам, в именах которых есть цифры «100»). Это удобно, если вы уже знаете имена нужных вам приборов. Но если вы их не знаете (как мы сейчас) – просто оставьте тело запроса пустым – в этом случае в ответе вернется информация по всем приборам аккаунта.

Создадим новый запрос.

Нажмите на кнопку ADD, выберите тип заголовка Authorization и в поле Value введите Bearer, а после него через пробел – токен, полученный в прошлом разделе. В ответе на запрос найдите прибор, у которого имя (поле name) имеет значение Метеостанция 5 этаж. Запишите его id (60546) – он потребуется в следующем запросе. Описание остальных параметров ответа приведено в документации API.

Получение идентификаторов параметров

Запрос информации о параметрах конкретного прибора аналогичен запросу информации о приборах – только вместо index надо указать идентификатор прибора, полученный в прошлом разделе (напомним, для метеостанции он равен 60546).

В ответе вернется массив с информацией о параметрах. Давайте составим таблицу кодов параметров (code) и их идентификаторов (id).

Эти идентификаторы понадобятся для чтения и записи значений параметров. Идентификаторы являются уникальными на уровне облачного сервиса – то есть они не могут совпадать даже для различных приборов.

Описание остальных параметров ответа приведено в документации API.

Лайфхак по быстрому определению идентификаторов параметров на этапе отладки

Показанный в прошлом пункте способ определения параметров через API является наиболее корректным – потому что, например, при изменении конфигурации прибора в облаке идентификаторы могут измениться.

Поэтому в приложении, использующем API, крайне желательно избежать «хардкода» при задании идентификаторов. Но во время тестирования можно сделать вот что – откройте страницу со списком параметров прибора в облачном сервисе и используйте в вашем браузере команду Посмотреть код (в Google Chrome, например, для этого нужно нажать правой кнопкой мыши на странице и выбрать одноименную команду).

После этого наведите курсор на ячейку столбца Код параметра интересующего вас параметра. Найдите этот код в окне просмотра (для этого может потребоваться пораскрывать уровни вложенности, нажимая на стрелочки) – прямо перед ним будет отображаться идентификатор этого параметра.

Чтение значений параметров

Зная идентификаторы параметров – можно организовать их чтение. Для этого воспользуемся методом parameters/last-data, чтобы считать текущие значения параметров.

Пример из документации:

В теле запроса передаются идентификаторы нужных параметров. Используем идентификаторы параметров wHummidCloud (1099136), wCo2Cloud (1099138) и wTempCloud (1099134). Также не забудем поменять токен примера на свой токен.

В ответе для каждого параметра мы получим следующую информацию:

• d – метка времени получения значения в формате Unixtime. В рамках тестов можно воспользоваться онлайн-конвертером, чтобы перевести это значение в «человеческий» формат;
• v – «числовое» значение параметра;
• e – код ошибки (например, если вместо значения параметра в облаке будет отображаться текст «Ошибка 255» – то именно его вы получите в параметре e);
• f – форматированное значение, которое фактически отображается в облаке – то есть v с добавленными единицами измерения или код ошибки.

Для чтения истории параметров используются методы parameters/data, parameters/forward-data и parameters/backward-data. Их отличия и примеры использования описаны в документации API.

Запись значений параметров

Для записи значения параметров используется метод parameters/write-data.

Пример из документации:

Параметры sms_tag и sms_code в данный момент не используются – они заложены для будущих обновлений облака, в которых может быть реализовано подтверждение команды записи по sms. Параметры timeout и sync соответствуют настройкам Повторять попытки записи в течение и Не записывать, если значение в приборе изменилось к моменту записи в интерфейсе облачного сервиса.

Для каждого записываемого параметра в массиве data указывается его идентификатор и значение. У метеостанции для записи доступен только один параметр – ValueSetting с идентификатором 15197930. Поэтому тело нашего запроса будет таким (и снова не забудьте поменять токен из примера на свой собственный):

В ответ на запрос будут возвращены общий идентификатор запроса записи (writeGroupId) и идентификаторы запросов записи отдельных параметров (writeParamId).

Обратите внимание – значение типа BOOL записываются в виде false/true, а значения с плавающей точкой – с разделителем «.» (точка) для целой и дробной части. В случае попытки записи некорректного значения или использования несуществующего в данном аккаунте идентификатора параметра – в ответе будет возвращена информация об ошибке (подробнее см. в документации API).

Заключение

Мы разобрались, что такое API, и на практике рассмотрели основные методы, используемые при работе с API облачного сервиса OwenCloud. Приведем несколько реальных случаев его применения:

• официальные мобильные приложения OwenCloud для Android и iOS, а также плагин для связи с OwenCloud в Owen OPC Server реализованы на базе использования API;
• компания ООО Быстрые Проекты реализовала web-hmi, построенный на их собственной системе визуализации, которая отображает данные, получаемые от OwenCloudпо API. Вот примеры демонстрационных проектов: Мониторинг инженерных систем здания, Диспетчеризация теплового пункта.

Используя API, вы можете интегрировать OwenCloudсо своими приложениями – например, системами мониторинга, диспетчеризации и т. д.

Во второй части статьи мы расскажем о том, как организовать работу с API OwenCloud из программы контроллера ПЛК2xx / СПК.