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

В первой части статьи мы разобрались, что такое API и рассмотрели основные методы API облачного сервиса OwenCloud, проверив их работу c помощью утилиты Advanced Rest Client. Теперь давайте повторим эти действия, но уже в контроллере с системой исполнения CODESYS V3.5 – ПЛК2xx или СПК1xx. В рассматриваемых примерах мы продолжим работать с устройством Метеостанция из демо-аккаунта облачного сервиса. Поставим себе задачу считать данные его параметров в программе контроллера.

Подключение к терминалу Linux

Для работы с API контроллеров ОВЕН на ОС Linux рекомендуется использовать утилиту curl. Для знакомства с этой утилитой и отладки ее вызовов, необходимо подключиться к терминалу контроллера. Для этого загрузите, установите и запустите утилиту Putty. Выберите протокол SSH, введите IP-адрес вашего контроллера (например, 10.2.11.174), и нажмите кнопку “Open”.

После открытия окна терминала, введите логин “root” и нажмите Enter. Затем введите пароль, который по умолчанию – “owen” (обратите внимание, что вводимые символы не будут отображаться), и нажмите Enter. Если вы изменили пароль в конфигураторе контроллера, введите свой собственный пароль.

После успешной аутентификации появится логотип ОВЕН и вы увидите приглашение для ввода команд.

Формирование примера запроса для curl в Advanced Rest Client

Curl – это утилита командной строки, которая позволяет отправлять запросы по различным протоколам обмена, таким как HTTP(S), FTP(S) и другим. В нашем случае нам необходимо отправлять HTTP-запросы. Хотя можно обратиться к документации для примеров, на начальном этапе будет проще использовать Advanced Rest Client. Давайте сформируем запрос в Advanced Rest Client для получения токена с помощью метода “auth/open”.

Теперь перейдем на вкладку CODE SNIPPETS. На этой вкладке сгенерированы примеры кода на различных языках программирования для нашего запроса – JavaScript, Python, C и Java. Вы можете использовать их в своих приложениях. Кроме того, на вкладке есть пример и для curl.

В данном примере используются специальные символы, такие как “n” (перенос строки запроса) и “rn” (переход на новую строку в теле запроса). Однако, при использовании в терминале такие символы могут быть некорректно интерпретированы. Поэтому для корректной работы в терминале, некоторые изменения в примере необходимы. В частности, можно удалить эти специальные символы и заменить двойные кавычки, обрамляющие тело запроса, на одинарные (в соответствии с особенностями curl для Linux):

curl "https://api.owencloud.ru/v1/auth/open" -X POST -d '{"login": "demo@owen.ru", "password": "demo123"}'

Выполним этот запрос в терминале контроллера.

В ответ получим токен:

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

Теперь выполним запрос на чтение параметров, используя полученный нами токен. Принцип формирования запроса описан в первой части статьи. Напомним, что нужно добавить заголовок типа Authorization, в котором ввести Bearer ваш_токен (например, Bearer 8WRhZatTVvdwEuL5oYkchlZ4B1pkqK95; у вас токен будет своим), а в теле запроса указать идентификаторы параметров.

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

curl "https://api.owencloud.ru/v1/parameters/last-data" -X POST -d '{"ids":[1099136, 1099138, 1099134]}' -H "Authorization: Bearer 8WRhZatTVvdwEuL5oYkchlZ4B1pkqK95"

Ответ на запрос будет выглядеть следующим образом:

Даже в процессе отладки работать с таким выводом неудобно. Чтобы сделать его более читабельным – воспользуемся утилитой jq.

Утилита jq

Утилита jq предназначена для парсинга формата JSON, который используется облачным сервисом для возвращения ответов на запросы через API. Чтобы обработать вывод команды curl с помощью jq, просто добавьте вертикальную черту после предыдущей команды и напишите jq. Вертикальная черта указывает на создание конвейера, где вывод утилиты curl будет передан на вход утилите jq для обработки.

curl "https://api.owencloud.ru/v1/parameters/last-data" -X POST -d '{"ids":[1099136, 1099138, 1099134]}' -H "Authorization: Bearer 8WRhZatTVvdwEuL5oYkchlZ4B1pkqK95" | jq

Вот что мы увидим в терминале:

С отформатированными подобным образом данными работать гораздо проще. Но заметим, что теперь в начале появилось несколько строк со статистикой выполнения запроса (total, received и т. д.). Чтобы убрать их – достаточно вызывать curl с ключом -s (silent; «тихий» вывод без отображения статистики).

curl -s "https://api.owencloud.ru/v1/parameters/last-data" -X POST -d '{"ids":[1099136, 1099138, 1099134]}' -H "Authorization: Bearer 8WRhZatTVvdwEuL5oYkchlZ4B1pkqK95" | jq

Предположим, что нас интересуют исключительно значения параметров, и мы хотим увидеть в выводе только их. Для этого нужно передать jq правильный фильтр. Чтобы сформировать его – потребуется ознакомиться с документацией на утилиту. Знакомство упростит сайт jqplay.org, который представляет собой «песочницу» для изучения jq. Откройте сайт и скопируйте в окно JSON вывод последней команды (без статистики), а в поле Filter экспериментируйте с фильтрами, ориентируясь на документацию. В результате можно, например, подобрать вот такой фильтр

.[range(0;3)].values[0].v

Объяснить его можно так: ответ на запрос возвращается в виде массива, в котором каждый элемент описывает один параметр. Мы работаем с элементами этого массива, начиная с нулевого и заканчивая вторым (первый аргумент функции range, определяющий индекс начального элемента обрабатываемого массива, является инклюзивным, а второй, определяющий конечный индекс массива – эксклюзивным, то есть не попадает в диапазон), обращаясь к записи values (она содержит значения параметра в различных форматах), в котором есть поле v («численное» значение без единиц измерения). Values представляет собой массив из одной записи, поэтому доступ к нему осуществляется по индексу 0 (справедливый вопрос – зачем возвращать информацию в виде массива из одного элемента, а не просто в виде записи? Дело в том, что это позволяет обеспечить согласованность с другими методами API – в частности, методами чтения истории значений параметров, в которых, соответственно, история значений возвращается в виде массива).

Внизу страницы отобразится готовый пример вызова утилиты с нужным фильтром:

Добавим его в наш предыдущий запрос:

curl -s "https://api.owencloud.ru/v1/parameters/last-data" -X POST -d '{"ids":[1099136, 1099138, 1099134]}' -H "Authorization: Bearer 8WRhZatTVvdwEuL5oYkchlZ4B1pkqK95" | jq '.[range(0;3)].values[0].v'

Теперь в выводе мы получим только интересующую нас информацию:

Осталось получить эту информацию в проекте CODESYS.

Вызов утилит Linux в проекте CODESYS

В проекте CODESYS для вызова утилит Linux используется библиотека CmpSysExec, которая автоматически устанавливается вместе с пакетом таргет-файлов ОВЕН. Она может использоваться только на контроллерах ОВЕН, так как является частью прошивки.

Заключение

Во второй части статьи мы рассмотрели, как отладить работу с API OwenCloud из терминала контроллера ПЛК2xx / СПК, а также привели ссылки на материалы, которые демонстрируют, как организовать работу с API из проекта CODESYS. Это позволяет контроллеру считывать значения из приборов, подключенных к OwenCloud и, например, использовать облачный сервис в качестве шлюза – то есть один контроллер может передать данные в другой. При этом ни одному из них не потребуется внешний («белый») IP-адрес, так как каждый из них будет работать с сервером OwenCloud, URL которого известен и статичен