Продолжается серия статей про API облачного сервиса OwenCloud.
Во второй статье расскажем, как отладить работу с API OwenCloud из терминала контроллера ПЛК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).
© Материал является объектом авторского права компании ОВЕН. Запрещается копирование, распространение или любое иное использование информации и объектов данного материала без предварительного согласия правообладателя.
