使用宏，您可以在需要时将数据发送到 HTTPs 服务器。 您可以控制发送哪些数据及其组织方式，从而可以轻松调整数据以用于现有服务。

安全措施：

  • HTTP(S) 客户端请求功能默认禁用。 系统管理员必须通过将 HttpClient> Mode 设置为 On（xConfiguration HttpClient Mode：On ） 来 明确启用该功能。

  • 系统管理员可以通过将 HttpClient > AllowHTTP 设置为 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 设置为 On （ xConfiguration HttpClient AllowInsecureHTTPS：On ）。 这样便可使用 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 。