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

2 июля 2024

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

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

Наиболее простой способ работы с API в контроллерах ОВЕН с ОС Linux– это использование утилиты curl. Для знакомства с утилитой и отладки ее вызовов следует подключиться к терминалу контроллера. Для этого загрузите, установите и запустите утилиту Putty.

Выберите протокол SSH, введите IP-адрес вашего контроллера (в примере у нашего контроллера IP-адрес = 10.2.11.174; у вас он будет своим) и нажмите кнопку Open.

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

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

Теперь нужно понять, какие команды вводить.

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

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

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

В примере используютcя специальные символы – «\» (перенос строки запроса) и «\r\n» (переход на новую строку в теле запроса). В терминале такие символы будут восприняты некорректно – поэтому немного отредактируем пример, убрав их, а также заменим кавычки, обрамляющие тело запроса, с двойных на одиночные (это связано с особенностями реализации 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

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

Видеоурок по использованию утилиты приведен на нашем YouTube канале: https://youtu.be/xFvN0BryJFk

Пример использования библиотеки для работы с API OwenCloud: https://ftp.owen.ru/CoDeSys3/21_Examples/01_3.5.11.5/08_Sockets/Example_OwenCloudApi_3517v1.projectarchive

Видео по работе с примером: https://youtu.be/T6XfuDQIOk4

Для упрощения парсинга ответов можно использовать библиотеку OwenStringUtils, выложенную на сайте ОВЕН в разделе CODESYS V3/Библиотеки и компоненты: https://owen.ru/product/codesys_v3/libraries

Заключение

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

© Материал является объектом авторского права компании ОВЕН. Запрещается копирование, распространение или любое иное использование информации и объектов данного материала без предварительного согласия правообладателя.