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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Увімкнувши функцію запиту клієнта HTTP, ви можете використовувати наступні команди для надсилання запитів на сервер HTTP. <method> це або Опублікувати, Покласти, Патч , Отримати або Видалити.

  • xCommand HttpClient <Method> [AllowInsecureHTTPS: <True/False>] [Header: <Текст заголовка>] [ResponseSizeLimit: <Максимальний розмір відповіді>] [ResultBody: <Немає/PlainText/Base64>] [Тайм-аут: <Період тайм-ауту>] 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:

 функція hue_command(дані) { 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 Заголовок запису: "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 , якщо вам потрібна допомога з макросами та стороннім кодом.