此功能可将任意 HTTP(S) 请求从会议平板、协作室或桌面设备发送到 HTTP(S) 服务器。此外,设备会接收服务器发回的响应。设备支持 Post、Put、Patch、Get 和 Delete 方法。
通过使用宏,您可以随时将数据发送到 HTTP(S) 服务器。您可以选择要发送的数据,然后根据需要设置其结构。这样便可调整数据使其适应已建立的服务。
安全措施:
-
HTTP(S) 客户端请求功能默认禁用。系统管理员必须通过将
设置为开(xConfiguration HttpClient 模式:开
)来显式启用该功能。 -
系统管理员可以将
设置为 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>
如果该列表不为空,您只能将 HTTP(S) 请求发送到列表中的服务器。如果该列表为空,您可以将请求发送到任何 HTTP(S) 服务器。
使用不安全 (HTTP) 和安全 (HTTPS) 数据传输时,将对允许的服务器列表进行检查。
无需证书验证的 HTTPS
通过 HTTPS 发送请求时,设备默认会检查 HTTPS 服务器的证书。如果未找到有效的 HTTPS 服务器证书,您会收到错误消息。设备不会发送任何数据到该服务器。
我们建议使用有证书验证的 HTTPS。如果无法进行证书验证,系统管理员可将 xConfiguration HttpClient AllowInsecureHTTPS:开
)。这样便可使用 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 而不验证服务器证书时有效。这样一来,您便可在该参数设置为真
时将数据发送到服务器而无需验证服务器证书。如果忽略该参数,或将其设置为假
,则证书验证失败时不会发送数据。
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":"A user reported an issue with this system","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"}
.
更多信息
自定义指南中提供了有关如何使用 HTTP 客户端请求的更多详细信息。选择最新版本。
思科支持 (TAC) 不支持调试第三方代码,包括宏。如果您需要有关宏和第三方代码的帮助,请查看 Cisco Collaboration 开发人员社区。此外,此站点上还有许多开发人员和集成商资源。