使用宏,您可以随时将数据发送到 HTTP(S) 服务器。 您可以根据个人需要选择要发送的数据,并组织它们。 通过这种方法,您可以将数据适应已建立的服务。

安全措施:

  • HTTP(S) 客户端请求功能在缺省情况下被禁用。 系统管理员必须将 HttpClient >模式设置为打开 来明确启用此功能( xConfiguration HttpClient Mode: On )。

  • 系统管理员可以通过设置 HttpClient >设置为 False 来禁止使用 HTTP( xConfiguration HttpClient AllowHTTP: False )。

  • 系统管理员可以指定允许设备发送数据的 HTTP(S) 服务器列表。(请参阅 xCommand HttpClient Allow Hostname 命令。)

  • 并发 HTTP(S) 请求的数量受限。

本文引用的配置在设备的 Web 界面和 API 中均可用。 API 中提供了命令。 阅读高级 设置文章 ,了解如何访问 Web 界面和使用 API。

允许的 HTTP(S) 服务器列表

系统管理员可以使用这些命令设置和维护最多 10 个允许的 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 进行证书验证。 如果无法进行证书验证,系统管理员 可以将 HttpClient >安全 HTTPS 设置为打开 ( xConfiguration HttpClient AllowInsecureHTTPS: On )。 这样允许在不验证服务器证书的情况下使用 HTTPS。

发送 HTTP 请求

在启用 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 设备

以下为一个宏函数,该宏函数会打开一个连接至一个和一个和一个高亮桥相连的浅色:


     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 Community。 此外,该站点上有许多开发人员和集成器资源。