Ця функція дає можливість надсилати довільні http(S) запити з дошки, кімнати або настільного пристрою на http(S) сервер. Крім того, пристрій отримує відповідь, яку сервер надсилає назад. Пристрій підтримує методи Публікації, Поставити, Патч, Отримати та Видалити.
Використовуючи макроси, ви можете надсилати дані на сервер HTTP(S), коли забажаєте. Ви можете вибрати, які дані надсилати, і структурувати їх так, як вам подобається. Зробивши це таким чином, ви зможете адаптувати дані до вже створеного сервісу.
Заходи безпеки:
Функція запиту клієнта HTTP(S) за замовчуванням вимкнена. Системний адміністратор повинен явно ввімкнути цю функцію, встановивши Увімкнуто (
xConfiguration HttpClient Mode: On).Системний адміністратор може запобігти використанню HTTP, встановивши to 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: <Regular expression that matches the host name or IP address of the HTTP(S) server>xCommand HttpClient Allow Hostname ClearxCommand HttpClient Allow Hostname ListxCommand HttpClient Allow Hostname Remove Id: <id of an entry in the list>
Якщо список не порожній, ви можете надсилати http(S) запити тільки на сервери в списку. Якщо список порожній, ви можете надіслати запити на будь-який HTTP(S) сервер.
Перевірка зі списком дозволених серверів виконується як при використанні незахищених (HTTP), так і при безпечній (HTTPS) передачі даних.
HTTPS без перевірки сертифіката
При відправці запитів по HTTPS пристрій за замовчуванням перевіряє сертифікат HTTPS-сервера. Якщо сертифікат сервера HTTPS не встановлено дійсним, з'явиться повідомлення про помилку. Пристрій не надсилає жодних даних на цей сервер.
Ми рекомендуємо використовувати 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 без перевірки сертифіката сервера. Якщо так, ви можете надіслати дані на сервер без перевірки сертифіката сервера, якщо для параметра встановлено значення
True
. Якщо ви залишите поза увагою параметр, або встановіть для нього значення
False
, дані не надсилаються, якщо перевірка сертифіката не вдається.
Нараду
ResposenSizeLimit
параметр - максимальний розмір корисного навантаження (байтів), який пристрій приймає в якості відповіді від сервера. Якщо корисне навантаження у відповідь більше цього максимального розміру, команда повертає помилку стану. Повідомлення про помилку говорить про те, що максимальний розмір файлу перевищено. Однак це не впливає на сторону сервера; сервер отримав і обробив запит належним чином.
Використовуйте розширення для обміну повідомленнями
ResultBody
параметр, щоб вирішити, як відформатувати тіло відповіді HTTP від сервера в командному результаті. У вас є три варіанти:
None: Не включайте тіло відповіді HTTP в результат команди.Base64: Base64 кодує тіло, перш ніж включити його в результат.PlainText: Включіть тіло в результат як звичайний текст. Якщо відповідь містить листи, які не можна надрукувати, команда повертає помилку стану з повідомленням про те, що дані, які не можна надрукувати, зустрічалися.
Використовуйте розширення для обміну повідомленнями
Timeout
параметр для установки періоду тайм-ауту (секунд). Якщо запит не виконано протягом цього періоду, API повертає помилку.
Введіть корисне навантаження (дані) відразу після того, як ви оформили команду. Все, що ви вводите, включаючи розриви рядків, є частиною корисного навантаження. Коли це буде зроблено, закінчіть розривом рядка ("\n") і окремим рядком, що містить лише крапку, за якою слідує розрив рядка (".\n"). Тепер команда виконана, і дані відправляються на сервер.
Приклади
Тіло повідомлення - JSON в обох цих прикладах. Це може бути будь-який формат, в залежності від очікуваного формату сервісу, який приймає повідомлення.
Приклад 1. Управління пристроєм IoT за допомогою HTTP Post
Ось функція макросів, яка включає світло, яке з'єднане з мостом Філіпса Хюе:
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, якщо вам потрібна допомога з макросами та кодом третьої сторони. Крім того, на цьому сайті є багато ресурсів розробників та інтеграторів.
