Макросы позволяют в любое время отправлять данные на сервер HTTP(S). Можно выбрать данные для отправки и структурировать их необходимым образом. Это позволяет адаптировать данные под уже настроенную службу.

Меры обеспечения безопасности:

  • Функция клиентских запросов HTTP(S) по умолчанию отключена. Системному администратору следует явным образом включить эту функцию, выбрав для параметра КлиентHTTP > Режим значение Вкл. (xConfiguration HttpClient Mode: On).

  • Системный администратор может запретить использование протокола HTTP, выбрав для параметра HttpClient > AllowHTTP значение False (xConfiguration HttpClient AllowHTTP: False)

  • Системный администратор может задать список серверов HTTP(S), на которые устройству разрешается отправлять данные. (см. описание команд xCommand HttpClient Allow Hostname).

  • Количество одновременных запросов HTTP(S) ограничено.

Конфигурации, упоминаемые в данной статье, доступны как из веб-интерфейса устройства, так и из API. Команды доступны в API. Сведения о том, как получить доступ к веб-интерфейсу и использовать API, см. в статье "Расширенные настройки".

Список разрешенных серверов HTTP(S)

Системный администратор может использовать эти команды для настройки и актуализации списка, содержащего до десяти разрешенных серверов HTTP(S) (хостов):

  • xCommand HttpClient Allow Hostname Add Expression: <регулярное выражение для сопоставления имени хоста или IP-адреса сервера HTTP(S)>

  • xCommand HttpClient Allow Hostname Clear

  • xCommand HttpClient Allow Hostname List

  • xCommand HttpClient Allow Hostname Remove Id: <идентификатор записи в списке>

Если в списке имеются записи, запросы HTTP(S) можно отправлять только на серверы из этого списка. Если список пуст, запросы можно отправлять на любой сервер HTTP(S).

Проверка по списку разрешенных серверов выполняется как во время небезопасной передачи данных (по протоколу HTTP), так и при защищенной передаче данных (по протоколу HTTPS).

Использование HTTPS без проверки сертификата

При отправке запросов по протоколу HTTPS устройство по умолчанию проверяет сертификат сервера HTTPS. Если сертификат сервера HTTPS недействителен, отображается соответствующее сообщение об ошибке. В этом случае устройство не отправляет данные на сервер.

Рекомендуется использовать HTTPS с проверкой сертификата. Если проверка сертификата невозможна, системный администратор может задать для параметра КлиентHTTP > AllowInsecureHTTPS (РазрешитьНебезопасныйHTTPS) значение Вкл. (xConfiguration HttpClient AllowInsecureHTTPS: On). Это позволит использовать протокол HTTPS без проверки сертификата сервера.

Отправка запросов HTTP(S)

После включения функции клиентских запросов HTTP(S) можно отправлять запросы на HTTP(S)-сервер, используя следующие команды: <method> — это Post, Put, Patch, Get или Delete.

  • xCommand HttpClient <Method> [AllowInsecureHTTPS: <True/False>] [Header: <Header text>] [ResponseSizeLimit: <Maximum response size>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Timeout period>] Url: <URL to send the request to>

Добавлять поля заголовка необязательно, однако можно добавить до 20 полей.

Параметр AllowInsecureHTTPS (РазрешитьНебезопасныйHTTPS) применяется только в том случае, если системный администратор разрешил использование протокола HTTPS без проверки сертификата сервера. В этом случае данные можно отправлять на сервер без проверки сертификата сервера, если параметру присвоено значение True (Истина). Если пропустить этот параметр или задать для него значение False (Ложь), в случае если проверка сертификата не пройдена, данные не отправляются.

Параметр ResposenSizeLimit — максимальный размер полезной нагрузки (в байтах), принимаемый устройством в качестве ответа от сервера Если объем полезных данных ответа превышает это значение, команда возвращает ошибку состояния. В сообщении об ошибке говорится о превышении максимального размера файла. Однако это не учитывается на стороне сервера, т. к. сервер получил запрос и обработал его надлежащим образом.

С помощью параметра ResultBody можно выбрать способ форматирования тела HTTP-ответа, полученного с сервера в результате выполнения команды. Доступны три варианта:

  • Нет: не включать тело HTTP-ответа в результат выполнения команды.

  • Base64: перед включением в результат кодировать тело ответа кодом Base64.

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

Для задания времени ожидания используйте параметр Задержка (в секундах). Если запрос не будет выполнен за этот период, API возвратит ошибку.

После ввода команды следует сразу ввести полезную нагрузку (данные). Все, что вы вводите, включая разрывы строк, является частью полезной нагрузки. После ввода полезной нагрузки следует ввести разрыв строки ("\n") и отдельную строку, в которой содержится лишь точка, за которой следует разрыв строки (".\n"). После этого команда будет выполнена, а данные будут отправлены на сервер.

Примеры

В обоих этих примерах текст сообщения указан в формате JSON. Однако он может быть в любом формате в зависимости от ожидаемого формата службы, которая получает сообщения.

Пример 1: управление устройством IoT с помощью HTTP POST

Ниже приведена функция макроса, которая включает лампочку, подключенную к маршрутизатору Philips Hue Bridge:

function hue_command(data) {
  var url = 'http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state';
  var headers = 'Content-Type: application/json';
  var command = '{"on":true}';
  xapi.command('HttpClient Put', { 'Url': url, 'Header': headers }, command);
}

Это же можно выполнить и в интерфейсе командной строки с помощью API:

xcommand HttpClient Put Header: "Content-Type: application/json" URL: "http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state"
{"on":true}
.

Пример 2: отправка данных в средство контроля с помощью HTTP POST

xcommand HttpClient Post Header: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring"
{"Message":"A user reported an issue with this system","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"}
.

Дополнительные источники информации

Дополнительные сведения об использовании клиентских запросов HTTP см. в Руководстве по настройке. Выбирайте последнюю версию.

Служба поддержки Cisco (TAC) не оказывает помощь в отладке стороннего кода, включая макросы. Если вам требуется помощь с макросами и сторонним кодом, обратитесь к сообществу разработчиков для совместной работы от Cisco. Кроме того, на этом сайте имеется множество ресурсов для разработчиков и интеграторов.