Драйвер HTTP API

Обзор

Драйвер предназначен для получения данных с помощью вызовов стороннего HTTP API. Поддерживается получение текущих и исторических данных, а также отправка команд управления. Так как API могут существенно различаться, драйвер поддерживает работу как по стандартному алгоритму, так и по пользовательскому алгоритму, который описывается на языке JavaScript.

Скачать драйвер можно по ссылке.

Установка

Драйвер HTTP API устанавливается в соответствии с общей последовательностью установки драйверов.

Конфигурирование

Взаимодействие со сторонним сервисом, предоставляющим HTTP API, выполняется в рамках линии связи Коммуникатора. На линии связи может быть одно или несколько устройств, которые позволяют сгруппировать отправляемые HTTP-запросы и получаемые данные удобным образом. Для добавления линии связи и устройств рекомендуется использовать соответствующие мастеры приложения Администратор.

Основные параметры линии связи содержат: тип канала связи – Не задан. В параметрах устройства: драйвер – DrvHttpApi. На следующем рисунке показана форма конфигурации устройства, дающая представление о структуре настроек.

Опции HTTP-клиента и список параметров являются общими для линии связи. Это означает, что если их изменить на форме конфигурации одного устройства, то они изменятся на форме конфигурации остальных устройств, относящихся к той же линии связи.

Заголовки по умолчанию добавляются ко всем HTTP-запросам. Параметры к ним применяются только один раз при старте линии связи, если параметры включены.

Запросы и команды прописываются для каждого устройства индивидуально. Однако есть возможность использовать один и тот же файл конфигурации для нескольких однотипных устройств. Для этого необходимо перейти в раздел Опрос устройств параметров линии связи, выбрать устройство и в параметре Командная строка указать короткое имя файла конфигурации.

Алгоритм работы

Если скрипт сеанса или скрипты команд отключены, то драйвер работает на основе алгоритма по умолчанию, который описан ниже. Если скрипты включены, то драйвер работает по скриптам.

Драйвер последовательно отправляет HTTP-запросы. Если для запроса заданы теги устройства, то чтобы значения тегов считались, возвращаемый HTTP-ответ должен представлять из себя объект JSON вида { "tagCode": tagValue }. Если ответ на HTTP-запрос не получен или получен с ошибочным статусом, то сеанс опроса не прерывается – выполнение переходит к следующему запросу.

При отправке команды управления отправляется HTTP-запрос, указанный в настройках команды. Отправляемая команда может содержать аргументы в следующем формате:

arg1=value1\n
arg2=value2

Аргументы, заданные при отправке команды, являются параметрами для HTTP-запроса команды. Если имя аргумента команды и имя параметра из конфигурации устройства совпадают, то приоритет отдаётся аргументу команды.

При отправке запросов как алгоритмом по умолчанию, так и пользовательским скриптом, учитывается параметр количества попыток при ошибке, который задан в основных параметрах линии связи. Также применяется параметр Пауза, который задан для каждого устройства в разделе Опрос устройств.

Скрипты

Пользовательские скрипты пишутся на языке JavaScript. Скрипт сеанса, если он включен, описывает алгоритм сеанса опроса настраиваемого устройства. Подразумевается, что в ходе сеанса опроса скрипт вызовет HTTP-запросы по имени, обработает полученные данные и запишет результат в теги устройства.

Скрипт команды описывает отправку одной конкретной команды. Подразумевается, что скрипт команды вызовет HTTP-запрос команды и обработает полученный ответ.

Если пользователем или системой дана команда на остановку службы Коммуникатора, скрипт, выполняемый в текущий момент, не будет прерван, он выполнится полностью.

Скрипты драйвера HTTP API поддерживают следующие функции:

Функция	Описание
log(text)	Вывести строку в журнал линии связи.
writeTextFile(shortFileName, contents)	Записать текстовый файл в директорию журналов. shortFileName – короткое имя файла, contents – записываемое содержимое.
setTagValue(tag, value)	Установить текущее значение тега устройства. tag – индекс или код тега, value – числовое значение или NaN.
setTagHistory(tag, timestamp, value)	Установить историческое значение тега устройства. tag – индекс или код тега, timestamp – метка времени, строка или число секунд Unix, value – значение. Обращение к тегу по индексу работает быстрее.
indexOfTag(tagCode)	Получить индекс тега по его коду. Возвращает числовой индекс или -1, если тег не найден.
getDeviceNumber()	Получить номер (идентификатор) устройства, скрипт которого выполняется.
sendRequest(name)	Отправить запрос с заданным именем. Возвращает объект { isSuccess, status, content }
sendCommand()	Отправить запрос команды управления, которая сейчас выполняется. Возвращает объект, аналогичный предыдущему.
addHeader(name, value)	Добавить постоянный заголовок ко всем HTTP-запросам на линии связи.
setHeader(name, value)	Добавить новый HTTP-заголовок или перезаписать существующий заголовок, ранее добавленный скриптом.
removeHeader(name)	Удалить HTTP-заголовок, ранее добавленный скриптом.
clearHeaders()	Удалить все ранее добавленные HTTP-заголовки.
getParameter(name)	Получить значение параметра по имени. Сюда входят параметры и секреты из конфигурации драйвера, а также параметры, добавленные скриптом. Возвращает объект.
setParameter(name, value)	Установить значение параметра. Значение является объектом.