esp-idf/docs/zh_CN/api-reference/protocols/esp_http_client.rst

118 lines
6.2 KiB
ReStructuredText
Raw Normal View History

ESP HTTP 客户端
===============
:link_to_translation:`en:[English]`
概述
----
``esp_http_client`` 提供了一组 API用于从 ESP-IDF 应用程序中发起 HTTP/S 请求,具体的使用步骤如下:
* 首先调用 :cpp:func:`esp_http_client_init`,创建一个 :cpp:type:`esp_http_client_handle_t` 实例,即基于给定的 :cpp:type:`esp_http_client_config_t` 配置创建 HTTP 客户端句柄。此函数必须第一个被调用。若用户未明确定义参数的配置值,则使用默认值。
* 其次调用 :cpp:func:`esp_http_client_perform`,执行 ``esp_http_client`` 的所有操作,包括打开连接、交换数据、关闭连接(如需要),同时在当前任务完成前阻塞该任务。所有相关的事件(在 :cpp:type:`esp_http_client_config_t` 中指定)将通过事件处理程序被调用。
* 最后调用 :cpp:func:`esp_http_client_cleanup` 来关闭连接(如有),并释放所有分配给 HTTP 客户端实例的内存。此函数必须在操作完成后最后一个被调用。
应用示例
--------
使用 ESP HTTP 客户端发起 HTTP/S 请求的简单示例,可参考 :example:`protocols/esp_http_client`
HTTP 基本请求
-------------
如需了解实现细节,请参考应用示例中的 ``http_rest_with_url````http_rest_with_hostname_path`` 函数。
持久连接
--------
持久连接是 HTTP 客户端在多次交换中重复使用同一连接的方法。如果服务器没有使用 ``Connection: close`` 头来请求关闭连接,连接就会一直保持开放,用于其他新请求。
为了使 ESP HTTP 客户端充分利用持久连接的优势,建议尽可能多地使用同一个句柄实例来发起请求,可参考应用示例中的函数 ``http_rest_with_url````http_rest_with_hostname_path``。示例中,一旦创建连接,即会在连接关闭前发出多个请求(如 ``GET````POST````PUT`` 等)。
.. only:: esp32
为 TLS 使用安全元件 (ATECC608)
__________________________________
安全元件 (ATECC608) 也可用于 HTTP 客户端连接中的底层 TLS 连接。请参考 :doc:`ESP-TLS 文档 </api-reference/protocols/esp_tls>` 中的 *ESP-TLS 中的 ATECC608A安全元件支持* 小节,了解更多细节。如需支持安全元素,必须首先在 menuconfig 中通过 :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT` 对其进行启用,此后,可配置 HTTP 客户端使用安全元素,如下所示:
.. code-block:: c
esp_http_client_config_t cfg = {
/* other configurations options */
.use_secure_element = true,
};
HTTPS 请求
-----------
ESP HTTP 客户端支持使用 **mbedTLS** 的 SSL 连接,需将 ``url`` 配置为以 ``https`` 开头,或将 ``transport_type`` 设置为 ``HTTP_TRANSPORT_OVER_SSL``。可以通过 :ref:`CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS` 来配置 HTTPS 支持(默认启用)。
.. note:: 在发起 HTTPS 请求时,如需服务器验证,首先需要向 ``esp_http_client_config_t`` 配置中的 ``cert_pem`` 成员提供额外的根证书PEM 格式)。用户还可以通过 ``esp_http_client_config_t`` 配置中的 ``crt_bundle_attach`` 成员,使用 ``ESP x509 Certificate Bundle`` 进行服务器验证。
如需了解上文备注中的实现细节,请参考应用示例中的函数 ``https_with_url````https_with_hostname_path``
HTTP 流
--------
有些应用程序需要主动打开连接并控制数据交换(数据流)。在这种情况下,应用流程与常规请求不同。请参考以下示例:
* :cpp:func:`esp_http_client_init`:创建一个 HTTP 客户端句柄。
* ``esp_http_client_set_*````esp_http_client_delete_*``:修改 HTTP 连接参数(可选)。
* :cpp:func:`esp_http_client_open`:用 ``write_len`` (该参数为需要写入服务器的内容长度)打开 HTTP 连接,设置 ``write_len=0`` 为只读连接。
* :cpp:func:`esp_http_client_write`:向服务器写入数据,最大长度为 :cpp:func:`esp_http_client_open` 函数中的 ``write_len`` 值;配置 ``write_len=0`` 无需调用此函数。
* :cpp:func:`esp_http_client_fetch_headers`:在发送完请求头和服务器数据(如有)后,读取 HTTP 服务器的响应头。从服务器返回 ``content-length``,并可以由 :cpp:func:`esp_http_client_get_status_code` 继承,以获取连接的 HTTP 状态。
* :cpp:func:`esp_http_client_read`:读取 HTTP 流。
* :cpp:func:`esp_http_client_close`:关闭连接。
* :cpp:func:`esp_http_client_cleanup`:释放分配的资源。
如需了解实现细节,请参考应用示例中的函数 ``http_perform_as_stream_reader``
HTTP 认证
---------
ESP HTTP 客户端同时支持 **基本****摘要** 认证。
* 用户可以在 ``url````esp_http_client_config_t`` 配置中的 ``username````password`` 处输入用户名和密码。对于 ``auth_type = HTTP_AUTH_TYPE_BASIC``HTTP 客户端只需执行一项操作就可通过认证过程。
* 如果 ``auth_type = HTTP_AUTH_TYPE_NONE``,但配置中有 ``username````password`` 字段HTTP 客户端需要执行两项操作。客户端在第一次尝试连接服务器时,会收到 ``401 Unauthorized`` 头,而后再根据这些信息来选择认证方法,并在第二项操作中执行。
* 如需了解实现细节,请参考应用示例中的函数 ``http_auth_basic````http_auth_basic_redirect`` (用于基本认证)和 ``http_auth_digest`` (用于摘要认证)。
认证配置示例
^^^^^^^^^^^^
* 基于 URI 的认证
.. highlight:: c
::
esp_http_client_config_t config = {
.url = "http://user:passwd@httpbin.org/basic-auth/user/passwd",
.auth_type = HTTP_AUTH_TYPE_BASIC,
};
* 基于用户名和密码的认证
.. highlight:: c
::
esp_http_client_config_t config = {
.url = "http://httpbin.org/basic-auth/user/passwd",
.username = "user",
.password = "passwd",
.auth_type = HTTP_AUTH_TYPE_BASIC,
};
API 参考
---------
.. include-build-file:: inc/esp_http_client.inc