С помощью макросов вы можете отправлять данные на HTTPs-сервер в любое время. Вы можете контролировать, какие данные отправляются и как они организованы, что упрощает адаптацию данных для использования с существующими службами.

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

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

  • Системный администратор может запретить использование 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-запросы только на эти серверы. Однако если список пуст, вы можете отправлять запросы на любой HTTPs-сервер.

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

HTTPS без проверки сертификата

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

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

Отправка HTTPS-запросов

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

  • xCommand HttpClient <Method> [AllowInsecureHTTPS: <True/False>] [Header: <Header text>] [ResponseSizeLimit: <Максимальный размер ответа>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Timeout period>] URL: <URL для отправки запроса>

Добавление полей заголовков не является обязательным, вы можете добавить до 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 = 'Тип контента: application/json'; команда var = '{"on":true}'; xapi.command('HttpClient Put', { 'Url': URL, 'Header': заголовки }, команда); }

Это же можно выполнить и в интерфейсе командной строки с помощью 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: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Сообщение":"Пользователь сообщил о проблеме с этой системой","systemName":"BoardRoom 4th Floor","softwareVersion": "ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} .

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

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

Служба поддержки Cisco (TAC) не оказывает помощь в отладке стороннего кода, включая макросы. Проверьте https://roomos.cisco.com , если вам нужна помощь с макросами и сторонним кодом.