Используйте API OwenCloud для облачного сервиса. Узнайте, как это сделать в первой части.

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

Сервис предоставляет информацию о значениях параметров приборов, тревогах и позволяет формировать отчеты. Он также поддерживает интеграцию с другими приложениями через API. В данной статье мы объясним, что такое API, как его использовать и для каких задач он может быть полезен.

Что такое API?

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

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

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

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

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

https://api.openweathermap.org/data/2.5/weather?lat="44.34"&lon="10.99&appid={API key}
\

Эта строка представляет собой описание 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:

{
  "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 обеспечит подробную информацию о доступных данных и способах их использования.

API OwenCloud

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

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

API предоставляется бесплатно, но имеется ограничение на количество запросов с одного IP адреса в интервале 10 секунд. Если ограничение превышено, будет возвращен код состояния 429 (Too Many Requests).

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 OwenCloud необходимо получить токен (идентификатор пользователя) с помощью метода 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"
}

В первом блоке описывается запрос и его заголовки (headers), а во втором блоке указываются данные, передаваемые в запросе. Пример из документации использует конкретный аккаунт разработчика. Однако, мы будем работать с демо-аккаунтом, поэтому будем использовать следующие логин и пароль:

{
  "login":"demo@owen.ru",
  "password":"demo123"
}

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

POST https://api.owencloud.ru/v1/auth/open

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

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

Значение первого поля (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»). Это удобно, если вы уже знаете имена нужных вам приборов. Но если вы их не знаете (как мы сейчас) – просто оставьте тело запроса пустым – в этом случае в ответе вернется информация по всем приборам аккаунта.

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

Для добавления заголовка Authorization воспользуйтесь кнопкой “ADD”, выберите тип заголовка “Authorization” и в поле “Value” введите “Bearer”, а затем через пробел укажите токен, полученный ранее. В ответе на запрос найдите прибор с именем “Метеостанция 5 этаж” и запишите его идентификатор (60546), который будет использован в следующем запросе. Более подробное описание остальных параметров ответа можно найти в документации API.

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

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

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

отладки

Показанный в прошлом пункте способ определения параметров через 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: код ошибки, который будет отображаться, если в облаке возникла ошибка или проблема с получением значения параметра.
  • f: форматированное значение параметра, которое фактически отображается в облаке, включая единицы измерения или код ошибки.

Эти значения помогут вам понять и интерпретировать полученные данные параметров в ответе от API.

Для чтения истории параметров используются методы 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"}   ]
}

В данный момент параметры smstag и smscode не используются и предназначены для будущих обновлений облака, связанных с возможностью подтверждения команды записи по SMS. Параметры timeout и sync соответствуют настройкам “Повторять попытки записи в течение” и “Не записывать, если значение в приборе изменилось к моменту записи” в интерфейсе облачного сервиса.

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

{
  "timeout":60,
  "sync":true,
  "data":[
    {"id":15197930,"value":"123"}   ]
}

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

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

Заключение

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

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

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *