通过使用宏,您可以随时将数据发送到 HTTP(S) 服务器。您可以选择要发送的数据,然后根据需要设置其结构。这样便可调整数据使其适应已建立的服务。

安全措施:

  • HTTP(S) 客户端请求功能默认禁用。系统管理员必须通过将 HttpClient > 模式设置为xConfiguration HttpClient 模式:开)来显式启用该功能。

  • 系统管理员可以将 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>

如果该列表不为空,您只能将 HTTP(S) 请求发送到列表中的服务器。如果该列表为空,您可以将请求发送到任何 HTTP(S) 服务器。

使用不安全 (HTTP) 和安全 (HTTPS) 数据传输时,将对允许的服务器列表进行检查。

无需证书验证的 HTTPS

通过 HTTPS 发送请求时,设备默认会检查 HTTPS 服务器的证书。如果未找到有效的 HTTPS 服务器证书,您会收到错误消息。设备不会发送任何数据到该服务器。

我们建议使用有证书验证的 HTTPS。如果无法进行证书验证,系统管理员可将 HttpClient > AllowInsecureHTTPS 设置为xConfiguration HttpClient AllowInsecureHTTPS:开)。这样便可使用 HTTPS 而无需验证服务器证书。

发送 HTTP(S) 请求

启用 HTTP(S) 客户端请求功能后,您可以使用以下命令将请求发送到 HTTP(S) 服务器。<method> 可以是 PostPutPatchGetDelete

  • 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 开发人员社区。此外,此站点上还有许多开发人员和集成商资源。