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

Заходи безпеки:

  • Функцію клієнтського запиту HTTPs вимкнено за замовчуванням. Системний адміністратор має явно ввімкнути функцію, встановивши HttpClient > Mode на Увімкнено ( режим xConfiguration HttpClient: увімкнено ).

  • Системний адміністратор може заборонити використання HTTP, встановивши HttpClient > AllowHTTP на False ( xConfiguration HttpClient AllowHTTP: False ).

  • Системний адміністратор може вказати список серверів HTTPs, на які пристрою дозволено надсилати дані. (Див. команди xCommand HttpClient Allow Hostname .)

  • Кількість одночасних запитів HTTPs обмежена.

Конфігурації, про які йдеться в цій статті, доступні як у веб-інтерфейсі пристрою, так і в API. Команди доступні через API. Прочитайте статтю Додаткові параметри , щоб дізнатися, як отримати доступ до веб-інтерфейсу та використовувати API.

Список дозволених HTTP-серверів

Системний адміністратор може використовувати ці команди для налаштування та підтримки списку до десяти дозволених HTTP-серверів (хостів):

  • xCommand HttpClient Allow Hostname Add Expression: <Регулярний вираз, який відповідає імені хосту або IP адресі сервера HTTPs>

  • xCommand HttpClient Дозволити очищення імені хоста

  • Список дозволених імен хостів xCommand HttpClient

  • xCommand HttpClient Allow Hostname Remove Id: <id запису в списку>

Якщо список містить записи серверів, ви можете надсилати запити HTTPs лише на ці сервери. Однак, якщо список порожній, ви можете надсилати запити на будь-який сервер HTTPs.

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

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

Під час надсилання запитів через HTTPS пристрій за замовчуванням перевіряє сертифікат HTTPS-сервера. Якщо сертифікат сервера HTTPS недійсний, ви отримаєте повідомлення про помилку. Пристрій не надсилає жодних даних на цей сервер.

Ми рекомендуємо використовувати HTTPS із перевіркою сертифіката. Якщо перевірка сертифіката неможлива, системний адміністратор може встановити HttpClient > AllowInsecureHTTPS на Увімкнено ( xConfiguration HttpClient AllowInsecureHTTPS: Увімкнено ). Це дозволяє використовувати HTTPS без перевірки сертифіката сервера.

Надсилання HTTPs-запитів

Після ввімкнення функції запиту клієнта HTTPs ви можете використовувати наступні команди для надсилання запитів на сервер HTTPs. <method> це або Post , Put , Patch , Get або Delete .

  • xCommand HttpClient <Метод> [AllowInsecureHTTPS: <True/False>] [Заголовок: <Текст заголовка>] [ResponseSizeLimit: <Максимальний розмір відповіді>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Timeout period>] Url: <URL для надсилання запиту>

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

Параметр AllowInsecureHTTPS діє, лише якщо системний адміністратор дозволив використання HTTPS без перевірки сертифіката сервера. Якщо так, ви можете надсилати дані на сервер без перевірки сертифіката сервера, якщо для параметра встановлено значення True . Якщо пропустити параметр або встановити для нього значення False , дані не надсилатимуться, якщо перевірка сертифіката не вдасться.

Параметр ResposenSizeLimit — це максимальний розмір корисного навантаження (у байтах), який пристрій приймає як відповідь від сервера. Якщо корисне навантаження відповіді перевищує цей максимальний розмір, команда повертає помилку стану. Повідомлення про помилку повідомляє, що максимальний розмір файлу перевищено. Однак це не впливає на сервер; сервер отримав і належним чином обробив запит.

Використовуйте параметр ResultBody , щоб вирішити, як форматувати тіло відповіді HTTP від ​​сервера в результаті команди. У вас є три варіанти:

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

  • Base64 : Base64 кодує тіло перед включенням його в результат.

  • PlainText : Включіть тіло в результат як звичайний текст. Якщо відповідь містить недруковані літери, команда повертає помилку стану з повідомленням про те, що виявлено недруковані дані.

Використовуйте параметр Timeout , щоб установити період очікування (у секундах). Якщо запит не виконано протягом цього періоду, API повертає помилку.

Введіть корисне навантаження (дані) безпосередньо після введення команди. Усе, що ви вводите, включаючи розриви рядків, є частиною корисного навантаження. Коли закінчите, закінчіть розривом рядка ("\n") і окремим рядком, який містить лише крапку, після якої йде розрив рядка (".\n"). Тепер команда виконана, і дані відправлені на сервер.

Приклади

В обох цих прикладах текст повідомлення є JSON. Це може бути будь-який формат, залежно від очікуваного формату служби, яка отримує повідомлення.

Приклад 1: керування пристроєм IoT за допомогою HTTP Post

Ось функція макросу, яка вмикає світло, підключене до Philips Hue Bridge:

 функція 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': заголовки }, команда); }

Ви можете зробити те саме в командному рядку за допомогою API:

 xcommand HttpClient Помістіть заголовок: "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" {"Message":"Користувач повідомив про проблему з цією системою","systemName":"BoardRoom 4th floor","softwareVersion": "ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} .

Додаткова інформація

Дізнайтеся більше про те, як використовувати HTTP-запити клієнта в Інструкція з налаштування . Виберіть останню версію.

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