此功能可傳送任意 HTTP(S) 請求,從 Board、會議室或桌上裝置傳送至 HTTP(S) 伺服器。 此外,裝置會接收伺服器回送的回應。 裝置支援 Post、Put、Patch、Get 和 Delete 方法。
使用宏,可以隨時傳送資料至 HTTP(S) 伺服器。 您可以選擇要傳送的資料,並如其需要建立結構。 這樣,您可以調整資料以適合已建立的服務。
安全性措施:
HTTP(S) 用戶端請求功能預設為停用。 系統管理員必須明確啟用此功能,將 HttpClient 模式設定
xConfiguration HttpClient Mode: On
)。系統管理員可禁止使用 HTTP,將 HttpClient
> False (xConfiguration HttpClient AllowHTTP: False
)。系統管理員可以指定允許裝置傳送資料至的 HTTP(S) 伺服器清單。(請參閱
xCommand HttpClient Allow Hostname
指令。)並行 HTTP(S) 請求數有限制。
此文章所引用的組配置可從裝置的網頁介面和 API 使用。 API 中提供指令。 閱讀進 程式設定文章 ,以取得如何存取 Web 介面和使用 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 Clear
xCommand HttpClient Allow Hostname List
xCommand 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: 使用 HTTP Post 進行 IoT 裝置控制
以下是可開啟連接至 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 Collaboration Developer 社群。 此外,此網站上有許多開發人員和整合者資源。