此功能使 Board、Desk 或 Room 系列设备能够通过 HTTPs 服务器发起和接收 HTTPs 请求。 这些设备支持发布、放置、修补、获取和删除等方法,允许与服务器进行不同的交互。
使用宏,您可以在需要时将数据发送到 HTTPs 服务器。 您可以控制发送哪些数据及其组织方式,从而可以轻松调整数据以用于现有服务。
安全措施:
-
HTTP(S) 客户端请求功能默认禁用。 系统管理员必须通过将 HttpClient>
:On )来
明确启用该功能。 -
系统管理员可以通过将
False(xConfiguration HttpClient AllowHTTP :False)
来阻止使用 HTTP。 -
系统管理员可以指定允许设备向其发送数据的 HTTP(S) 服务器列表。 (请参阅
xCommand HttpClient Allow Hostname
命令。) -
并发的 HTTP(S) 请求数量受限。
本文中提到的配置既从设备的 Web 界面有空,也从 API 中。 命令通过 API 有空。 有关如何访问 Web 界面和使用 API 的信息,请阅读《高级设置》一文。
允许的 HTTP(S) 服务器列表
系统管理员可以使用以下命令设置和维护最多十个允许的 HTTP(S) 服务器(主机)的列表:
-
xCommand HttpClient Allow Hostname Add Expression: <匹配 HTTP(S) 服务器主机名或 IP 地址的正则表达式>
-
xCommand HttpClient Allow Hostname Clear
-
xCommand HttpClient Allow Hostname List
-
xCommand HttpClient Allow Hostname Remove Id: <列表中条目的 id>
如果列表包含服务器条目,则只能向这些服务器发送 HTTPs 请求。 但是,如果列表为空,则可以向任何 HTTPs 服务器发送请求。
使用不安全 (HTTP) 和安全 (HTTPS) 数据传输时,将对允许的服务器列表进行检查。
不进行证书验证的 HTTPS
通过 HTTPS 发送请求时,设备默认会检查 HTTPS 服务器的证书。 如果未找到有效的 HTTPS 服务器证书,您会收到错误消息。 设备不会发送任何数据到该服务器。
我们建议使用有证书验证的 HTTPS。 如果无法进行证书验证,系统管理员可以将 HttpClient>AllowInsecureHTTPS 设置为 这样便可使用 HTTPS 而无需验证服务器证书。
发送 HTTPs 请求
启用 HTTP(S) 客户端请求功能后,您可以使用以下命令将请求发送到 HTTP(S) 服务器。 <method>
可以是 Post
、Put
、Patch
、Get
或 Delete
。
-
xCommand HttpClient <Method> [AllowInsecureHTTPS:<True/False>] [标头:<标头文本>] [ResponseSizeLimit:<最大响应大小>] [ResultBody:<None/PlainText/Base64>] [超时:<超时期限>] URL:<要将请求发送到的 URL>
添加标题字段是可选的,您最多可以添加 20 个字段。
AllowInsecureHTTPS
参数仅当系统管理员允许使用 HTTPS 而不验证服务器证书时有效。 这样一来,您便可在该参数设置为真
时将数据发送到服务器而无需验证服务器证书。 如果忽略该参数,或将其设置为假
,则证书验证失败时不会发送数据。
ResposenSizeLimit
参数是设备作为服务器响应接受的最大负载大小(字节)。 如果响应负载大于此最大值,命令会返回状态错误。 错误消息中会指明超出了最大文件大小。 但是,这对服务器端没有影响;服务器已正确接收并处理请求。
使用 ResultBody
参数决定如何在命令结果中格式化来自服务器的 HTTP 响应正文。 您会看到三个选项:
-
无
:不将 HTTP 响应的正文添加到命令结果中。 -
Base64
:Base64 先对正文编码,再将其添加到结果中。 -
明文
:以纯文本形式将正文添加到结果中。 如果响应包含不可打印的字母,则命令会返回状态错误以及一则消息,说明遇到了不可打印的数据。
使用 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”:“一位用户报告了该系统的问题”,“systemName”:“BoardRoom 4th floor”,“softwareVersion”:“ce9.6.0”,“softwareReleaseDate”:“2018-12-13”,“videoMonitors”:“Dual”} .
更多信息
自定义指南中提供了有关如何使用 HTTP 客户端请求的更多详细信息。 选择最新版本。
思科支持 (TAC) 不支持调试第三方代码,包括宏。 如果您需要有关宏和第三方代码的帮助,请查看 https://roomos.cisco.com 。