Использование API облачного сервиса OwenCloud (часть 2)
В первой части статьи мы изучили, что такое API, и ознакомились с основными методами API облачного сервиса OwenCloud, проверив их работоспособность с использованием утилиты Advanced Rest Client. Теперь давайте повторим эти шаги, но уже в контроллере с системой исполнения CODESYS V3.5 — ПЛК2xx или СПК1xx. В наших примерах мы продолжим работать с устройством «Метеостанция» из демонстрационного аккаунта облачного сервиса. Наша задача — считать данные его параметров в программе контроллера.
Подключение к терминалу Linux
Самый лёгкий способ взаимодействия с API в контроллерах ОВЕН под управлением ОС Linux — это применение утилиты curl. Чтобы изучить эту утилиту и проверить её функции, подключитесь к терминалу контроллера. Загрузите, установите и запустите программу Putty.
Выберите протокол SSH, введите IP-адрес вашего контроллера (в примере у нашего контроллера IP-адрес равен 10.2.11.174; ваш адрес будет отличаться) и нажмите кнопку Открыть.
Появится окно терминала с запросом логина. Введите 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.
В примере используются специальные символы «\» (перенос строки запроса) и «\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.
Заключение
Во второй части статьи мы изучили, как настроить работу с API OwenCloud через терминал контроллера ПЛК2xx / СПК, а также предоставили ссылки на материалы, демонстрирующие, как интегрироваться с API в рамках проекта CODESYS. Благодаря этому контроллер может считывать данные с устройств, подключённых к OwenCloud, и использовать облачный сервис в качестве шлюза — один контроллер может передавать данные другому. При этом ни одному из них не потребуется внешний («белый») IP-адрес, поскольку оба будут взаимодействовать с сервером OwenCloud, чей статичный URL — (api.owencloud.ru).
