查看“︁AT模块 5: HTTP AT 命令（HTTP AT Commands）”︁的源代码

= HTTP AT 命令 =

== 指令列表 ==

{| class="wikitable"
! 指令
! 描述
|-
| <code>AT+HTTPCLIENT</code>
| 发送 HTTP Client 请求
|-
| <code>AT+HTTPGETSIZE</code>
| 获取 HTTP 资源大小
|-
| <code>AT+HTTPCGET</code>
| 获取 HTTP 资源
|-
| <code>AT+HTTPCPOST</code>
| 发送指定长度的 HTTP POST 数据
|-
| <code>AT+HTTPCPUT</code>
| 发送指定长度的 HTTP PUT 数据
|-
| <code>AT+HTTPURLCFG</code>
| 设置/获取长 HTTP URL
|-
| <code>AT+HTTPSSLCFG</code>
| 设置/获取 HTTPS 证书
|-
| <code>AT+HTTPRECVMODE</code>
| 查询/设置 socket 接收模式
|-
| <code>AT+HTTPRECVDATA</code>
| 在被动接收模式下获取 HTTP 数据
|-
| <code>AT+HTTPRECVLEN</code>
| 在被动接收模式下获取 HTTP 数据长度
|-
| <code>AT+HTTPRECVBUF</code>
| 查询/设置 HTTP 接收缓冲区大小
|}

== HTTP AT 命令描述 ==

=== AT+HTTPCLIENT ===

发送 HTTP Client 请求。

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPCLIENT=<linkid>,<opt>,<content-type>,<"url">,[,<"data">]
</pre>

'''响应：'''

<pre>
OK

+HTTPCGET:<linkid>,<size>,<data>

+HTTPSTATUS:<linkid>,<err_code>


或


+HTTPCPOST:<linkid>,<size>,<data>

+HTTPSTATUS:<linkid>,<err_code>


或


+HTTPCPUT:<linkid>,<size>,<data>

+HTTPSTATUS:<linkid>,<err_code>
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。范围：[0~2]

* '''<opt>''': HTTP Client 请求的方法。

  * 1: HEAD
  * 2: GET
  * 3: POST
  * 4: PUT

* '''<content-type>''': HTTP Client 请求的数据类型。

  * 0: application/x-www-form-urlencoded
  * 1: application/json
  * 2: multipart/form-data
  * 3: text/xml

* '''<url>''': HTTP/HTTPS URL。

* '''<data>''': 如果 <opt> 是 POST 请求，此参数保存您发送到 HTTP 服务器的数据。
             如果不是，此参数不存在，这意味着无需输入逗号来表示此参数。

* '''<err_code>''': 失败原因

  * 0: 文件成功接收
  * 1: 未知错误
  * 2: 连接服务器失败
  * 3: 解析服务器主机名失败
  * 4: 连接被远程服务器意外关闭
  * 5: 连接超时（服务器未及时响应）
  * 6: 服务器响应错误代码
  * 7: 本地内存错误
  * 8: 本地中止
  * 9: Content length 不匹配

==== 注意事项 ====

* 如果包含 URL 的整个命令长度超过 256 字节，请先使用 AT+HTTPURLCFG 命令预设 URL，然后将此命令的 <"url"> 参数设置为 ""。

* 如果 url 参数不为空，HTTP Client 将使用它并忽略 host 参数和 path 参数；如果 url 参数被省略或为空字符串，HTTP Client 将使用 host 参数和 path 参数。

* 该命令不支持重定向。从服务器获取状态码 301（永久重定向）或 302（临时重定向）后，AT 不会自动重定向到新的 URL 地址。您可以使用某些工具获取实际的 URL，然后使用此命令访问。

* 如果包含 <"data"> 的整个命令长度超过 256 字节，请使用 AT+HTTPCPOST 命令。

* 当启用被动模式时，响应将变为 +HTTPC:<linkid>,<size>。

==== 示例 ====

<pre>
// HEAD 请求
AT+HTTPCLIENT=0,1,0,"http://httpbin.org/get"

// GET 请求
AT+HTTPCLIENT=0,2,0,"http://httpbin.org/get"

// POST 请求
AT+HTTPCLIENT=0,3,0,"http://httpbin.org/post","field1=value1&field2=value2"

// HTTPS HEAD 请求
AT+HTTPCLIENT=0,1,0,"https://httpbin.org/get"
</pre>

=== AT+HTTPGETSIZE ===

获取 HTTP 资源大小。

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPGETSIZE=<linkid>,<"url">[,<timeout>]
</pre>

'''响应：'''

<pre>
OK

+HTTPGETSIZE:<linkid>,<size>

+HTTPSTATUS:<linkid>,<err_code>
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。

* '''<url>''': HTTP/HTTPS URL。它是字符串参数，应用引号括起来。

* '''<timeout>''': 网络超时。单位：毫秒。默认值：5000。范围：[0,180000]。

* '''<size>''': HTTP 资源大小。

==== 注意事项 ====

* 如果包含 URL 的整个命令长度超过 256 字节，请先使用 AT+HTTPURLCFG 命令预设 URL，然后将此命令的 <"url"> 参数设置为 ""。

==== 示例 ====

<pre>
AT+HTTPGETSIZE=0,"https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_92x30dp.png"

OK

// 响应
+HTTPGETSIZE:0,1575

+HTTPSTATUS:0,0
</pre>

=== AT+HTTPCGET ===

获取 HTTP 资源。

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPCGET=<linkid>,<"url">[,<timeout>]
</pre>

'''响应：'''

<pre>
OK

+HTTPCGET:<linkid>,<size>,<data>

+HTTPSTATUS:<linkid>,<err_code>
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。

* '''<url>''': HTTP/HTTPS URL。它是字符串参数，应用引号括起来。

* '''<timeout>''': 网络超时。单位：毫秒。默认值：5000。范围：[0,180000]。

* '''<size>''': HTTP 资源大小。

==== 注意事项 ====

* 如果包含 URL 的整个命令长度超过 256 字节，请先使用 AT+HTTPURLCFG 命令预设 URL，然后将此命令的 <"url"> 参数设置为 ""。

* 当启用被动模式时，响应将变为 +HTTPC:<linkid>,<size>。

=== AT+HTTPCPOST ===

发送指定长度的 HTTP POST 数据。

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPCPOST=<linkid>,<"url">,<length>
</pre>

'''响应：'''

<pre>
OK

>
</pre>

符号 > 表示 AT 已准备好接收串口数据，您现在可以输入数据。当满足由参数 <length> 确定的消息长度要求时，传输开始。

如果传输成功，AT 返回：

<pre>
SEND OK
</pre>

否则，返回：

<pre>
SEND FAIL
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。

* '''<url>''': HTTP/HTTPS URL。它是字符串参数，应用引号括起来。

* '''<length>''': 要 POST 的 HTTP 数据长度。最大长度等于系统可分配的堆大小。

==== 注意事项 ====

* 如果包含 URL 的整个命令长度超过 256 字节，请先使用 AT+HTTPURLCFG 命令预设 URL，然后将此命令的 <"url"> 参数设置为 ""。

* 此命令的 content-type 默认类型为 application/x-www-form-urlencoded。

* 当启用被动模式时，响应将变为 +HTTPC:<linkid>,<size>。

=== AT+HTTPCPUT ===

发送指定长度的 HTTP PUT 数据。

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPCPUT=<linkid>,<"url">,<content_type>,<length>
</pre>

'''响应：'''

<pre>
OK

>
</pre>

符号 > 表示 AT 已准备好接收串口数据，您现在可以输入数据。当满足由参数 <length> 确定的消息长度要求时，传输开始。

如果传输成功，AT 返回：

<pre>
SEND OK
</pre>

否则，返回：

<pre>
SEND FAIL
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。

* '''<url>''': HTTP/HTTPS URL。它是字符串参数，应用引号括起来。

* '''<content_type>''': HTTP Client 请求的数据类型。

  * 0: application/x-www-form-urlencoded
  * 1: application/json
  * 2: multipart/form-data
  * 3: text/xml

* '''<length>''': 要 PUT 的 HTTP 数据长度。最大长度等于系统可分配的堆大小。

==== 注意事项 ====

* 如果包含 URL 的整个命令长度超过 256 字节，请先使用 AT+HTTPURLCFG 命令预设 URL，然后将此命令的 <"url"> 参数设置为 ""。

* 当启用被动模式时，响应将变为 +HTTPC:<linkid>,<size>。

=== AT+HTTPURLCFG ===

设置/获取长 HTTP URL。

==== 查询命令 ====

'''命令：'''

<pre>
AT+HTTPURLCFG=0?
</pre>

'''响应：'''

<pre>
+HTTPURLCFG:<linkid>,<url length>,<url>

OK
</pre>

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPURLCFG=<linkid>,<url length>
</pre>

'''响应：'''

<pre>
OK

>
</pre>

此响应表示 AT 已准备好接收串口数据。您现在应该输入 URL，当 URL 长度达到 <url length> 值时，系统返回：

<pre>
SEND OK
</pre>

否则，返回：

<pre>
SEND FAIL
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。

* '''<url length>''': HTTP URL 长度。单位：字节。

  * 0: 清除 HTTP URL 配置。

  * [8,8192]: 设置 HTTP URL 配置。

* '''<url>''': HTTP/HTTPS URL 数据。

=== AT+HTTPSSLCFG ===

设置/获取 HTTPS 证书。

==== 查询命令 ====

'''命令：'''

<pre>
AT+HTTPSSLCFG=0?
</pre>

'''响应：'''

<pre>
+HTTPSSLCFG:<linkid>,<scheme>,[<"cert_file">][,<"key_file">][,<"ca_file">]

OK
</pre>

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPSSLCFG=<linkid>,<scheme>,[<"cert_file">][,<"key_file">][,<"ca_file">]
</pre>

'''响应：'''

<pre>
OK
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。

* '''<scheme>''':

  * 0: HTTPS 不验证证书。
  * 1: HTTPS 验证服务器证书。
  * 2: HTTPS 提供客户端证书。
  * 3: HTTPS 验证服务器证书并提供客户端证书。

* '''<"cert_file">''': 证书的文件名。

* '''<"key_file">''': 私钥的文件名。

* '''<"ca_file">''': 客户端用于验证服务器的 CA 文件名。

=== AT+HTTPRECVMODE ===

功能：查询/设置 HTTP 接收模式。

==== 查询命令 ====

'''功能：'''

查询 HTTP 接收模式。

'''命令：'''

<pre>
AT+HTTPRECVMODE?
</pre>

'''响应：'''

<pre>
+HTTPRECVMODE:<mode>

OK
</pre>

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPRECVMODE=<mode>
</pre>

'''响应：'''

<pre>
OK
</pre>

==== 参数 ====

* '''<mode>''': HTTP 数据的接收模式。默认值：0。

  * 0: 主动模式。BLC-AT 将立即把所有接收到的 HTTP 数据发送到主机 MCU，并带有 "+HTTPC" 头。

  * 1: 被动模式。BLC-AT 将把接收到的 HTTP 数据保存在内部缓冲区（HTTP 接收缓冲区，默认为 1024 字节），并等待主机 MCU 读取。如果缓冲区已满，socket 传输将被阻塞。

==== 注意事项 ====

* 此参数适用于所有 linkids。

* <len> 是缓冲区中 socket 数据的总长度。

* 一旦有 +HTTPC 报告，您应该通过运行 AT+HTTPRECVDATA 来读取数据。否则，在读取前一个 +HTTPC 之前，不会向主机 MCU 报告下一个 +HTTPC。

* 断开连接时，缓存仍然保存。

==== 示例 ====

<pre>
AT+HTTPRECVMODE=1
</pre>

=== AT+HTTPRECVBUF ===

功能：查询/设置 HTTP 接收缓冲区大小。

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPRECVBUF=<size>
</pre>

'''响应：'''

<pre>
+HTTPRECVBUF

OK
</pre>

==== 参数 ====

* '''<size>''': 设置缓冲区大小，单位字节。

==== 查询命令 ====

'''命令：'''

<pre>
AT+HTTPRECVBUF?
</pre>

'''响应：'''

返回缓冲区大小，默认缓冲区大小为 15360（此值不会占用系统的堆内存）。

<pre>
+HTTPRECVBUF:<size>

OK
</pre>

==== 注意事项 ====

* 此值的理论上限是 lwip 堆的大小。

=== AT+HTTPRECVDATA ===

在被动接收模式下获取 HTTP 数据。

==== 设置命令 ====

'''命令：'''

<pre>
AT+HTTPRECVDATA=<linkid>,<len>
</pre>

'''响应：'''

<pre>
+HTTPRECVDATA:<actual_len>,<data>

OK
</pre>

==== 参数 ====

* '''<linkid>''': HTTP Client 请求的链路 ID。

* '''<mode>''': socket 数据的接收模式。默认值：0。

* '''<len>''': 最大值为 0x7fffffff。如果接收到的数据的实际长度小于 len，则返回实际长度。

* '''<actual_len>''': 您实际获得的数据长度。

* '''<data>''': 您想要获取的数据。

==== 示例 ====

<pre>
AT+HTTPRECVMODE=1

// 例如，如果主机 MCU 收到一条消息，显示在 No.0 连接中接收到 100 字节数据，
// 该消息将为 "+HTTPC:0,100"。
// 然后您可以使用以下命令读取这 100 字节数据。
AT+HTTPRECVDATA=0,100
</pre>

=== AT+HTTPRECVLEN ===

功能：在被动接收模式下获取 HTTP 数据长度。

==== 查询命令 ====

'''功能：'''

查询为连接缓冲的整个数据的长度。

'''命令：'''

<pre>
AT+HTTPRECVLEN=0?
</pre>

'''响应：'''

<pre>
+HTTPRECVLEN:<linkid>,<data length of link>

OK
</pre>

==== 示例 ====

<pre>
AT+HTTPRECVLEN=0?

+CIPRECVLEN:0,100

OK
</pre>

----