mirror of
https://github.com/espressif/esp-idf
synced 2025-03-10 09:39:10 -04:00
Docs: add CN trans for esp_http_client.rst
This commit is contained in:
Mo Fei Fei
parent
8574ec3bd3
commit
f0060a7a76
@ -1,58 +1,59 @@
|
||||
ESP HTTP Client
|
||||
===============
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
``esp_http_client`` provides an API for making HTTP/S requests from ESP-IDF applications. The steps to use this API are as follows:
|
||||
``esp_http_client`` component provides a set of APIs for making HTTP/S requests from ESP-IDF applications. The steps to use these APIs are as follows:
|
||||
|
||||
* :cpp:func:`esp_http_client_init`: Creates an :cpp:type:`esp_http_client_handle_t` instance i.e. a HTTP client handle based on the given :cpp:type:`esp_http_client_config_t` configuration. This function must be the first to be called; default values will be assumed for the configuration values that are not explicitly defined by the user.
|
||||
* :cpp:func:`esp_http_client_perform`: Performs all operations of the esp_http_client - opening the connection, exchanging data and closing the connection (as required), while blocking the current task until its completion. All related events will be invoked through the event handler (as specified in :cpp:type:`esp_http_client_config_t`).
|
||||
* :cpp:func:`esp_http_client_init`: Creates an :cpp:type:`esp_http_client_handle_t` instance, i.e., an HTTP client handle based on the given :cpp:type:`esp_http_client_config_t` configuration. This function must be the first to be called; default values will be assumed for the configuration values that are not explicitly defined by the user.
|
||||
* :cpp:func:`esp_http_client_perform`: Performs all operations of the ``esp_http_client`` - opening the connection, exchanging data, and closing the connection (as required), while blocking the current task before its completion. All related events will be invoked through the event handler (as specified in :cpp:type:`esp_http_client_config_t`).
|
||||
* :cpp:func:`esp_http_client_cleanup`: Closes the connection (if any) and frees up all the memory allocated to the HTTP client instance. This must be the last function to be called after the completion of operations.
|
||||
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Simple example that uses ESP HTTP Client to make HTTP/S requests at :example:`protocols/esp_http_client`.
|
||||
Simple example that uses ESP HTTP Client to make HTTP/S requests can be found at :example:`protocols/esp_http_client`.
|
||||
|
||||
|
||||
Basic HTTP request
|
||||
Basic HTTP Request
|
||||
------------------
|
||||
|
||||
Check out the example functions ``http_rest_with_url`` and ``http_rest_with_hostname_path`` in the application example for implementation details.
|
||||
|
||||
|
||||
Persistent Connections
|
||||
----------------------
|
||||
|
||||
Persistent connection means that the HTTP client can re-use the same connection for several exchanges. If the server does not request to close the connection with the ``Connection: close`` header, the connection is not dropped but is instead kept open and used for further requests.
|
||||
|
||||
To allow ESP HTTP client to take full advantage of persistent connections, one should make as many requests as possible using the same handle instance.
|
||||
|
||||
Check out the example functions ``http_rest_with_url`` and ``http_rest_with_hostname_path`` in the application example. Here, once the connection is created, multiple requests (``GET``, ``POST``, ``PUT``, etc.) are made before the connection is closed.
|
||||
To allow ESP HTTP client to take full advantage of persistent connections, one should make as many requests as possible using the same handle instance. Check out the example functions ``http_rest_with_url`` and ``http_rest_with_hostname_path`` in the application example. Here, once the connection is created, multiple requests (``GET``, ``POST``, ``PUT``, etc.) are made before the connection is closed.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Use Secure Element (ATECC608) for TLS
|
||||
_____________________________________
|
||||
|
||||
A secure element (ATECC608) can be also used for the underlying TLS connection in the HTTP client connection. Please refer to Secure Element with ESP-TLS section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The secure element support has to be first enabled in menuconfig through :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`. Then the HTTP client can be configured to use secure element as follows:
|
||||
|
||||
|
||||
A secure element (ATECC608) can be also used for the underlying TLS connection in the HTTP client connection. Please refer to the *ATECC608A (Secure Element) with ESP-TLS* section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The secure element support has to be first enabled in menuconfig through :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`. Then the HTTP client can be configured to use secure element as follows:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
|
||||
esp_http_client_config_t cfg = {
|
||||
/* other configurations options */
|
||||
.use_secure_element = true,
|
||||
};
|
||||
|
||||
|
||||
HTTPS Request
|
||||
-------------
|
||||
|
||||
ESP HTTP client supports SSL connections using **mbedTLS**, with the ``url`` configuration starting with ``https`` scheme or ``transport_type`` set to ``HTTP_TRANSPORT_OVER_SSL``. HTTPS support can be configured via :ref:`CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS` (enabled by default).
|
||||
|
||||
.. note:: While making HTTPS requests, if server verification is needed, additional root certificate (in PEM format) needs to be provided to the ``cert_pem`` member in ``esp_http_client_config_t`` configuration. Users can also use the ``ESP x509 Certificate Bundle`` for server verification using the ``crt_bundle_attach`` member of the ``esp_http_client_config_t`` configuration.
|
||||
.. note:: While making HTTPS requests, if server verification is needed, an additional root certificate (in PEM format) needs to be provided to the ``cert_pem`` member in the ``esp_http_client_config_t`` configuration. Users can also use the ``ESP x509 Certificate Bundle`` for server verification using the ``crt_bundle_attach`` member of the ``esp_http_client_config_t`` configuration.
|
||||
|
||||
Check out the example functions ``https_with_url`` and ``https_with_hostname_path`` in the application example. (Implementation details of the above note are found here)
|
||||
Check out the example functions ``https_with_url`` and ``https_with_hostname_path`` in the application example for implementation details of the above note.
|
||||
|
||||
|
||||
HTTP Stream
|
||||
@ -60,14 +61,14 @@ HTTP Stream
|
||||
|
||||
Some applications need to open the connection and control the exchange of data actively (data streaming). In such cases, the application flow is different from regular requests. Example flow is given below:
|
||||
|
||||
* :cpp:func:`esp_http_client_init`: Create a HTTP client handle
|
||||
* ``esp_http_client_set_*`` or ``esp_http_client_delete_*``: Modify the HTTP connection parameters (optional)
|
||||
* :cpp:func:`esp_http_client_open`: Open the HTTP connection with ``write_len`` parameter (content length that needs to be written to server), set ``write_len=0`` for read-only connection
|
||||
* :cpp:func:`esp_http_client_write`: Write data to server with a maximum length equal to ``write_len`` of :cpp:func:`esp_http_client_open` function; no need to call this function for ``write_len=0``
|
||||
* :cpp:func:`esp_http_client_init`: Create a HTTP client handle.
|
||||
* ``esp_http_client_set_*`` or ``esp_http_client_delete_*``: Modify the HTTP connection parameters (optional).
|
||||
* :cpp:func:`esp_http_client_open`: Open the HTTP connection with ``write_len`` parameter (content length that needs to be written to server), set ``write_len=0`` for read-only connection.
|
||||
* :cpp:func:`esp_http_client_write`: Write data to server with a maximum length equal to ``write_len`` of :cpp:func:`esp_http_client_open` function; no need to call this function for ``write_len=0``.
|
||||
* :cpp:func:`esp_http_client_fetch_headers`: Read the HTTP Server response headers, after sending the request headers and server data (if any). Returns the ``content-length`` from the server and can be succeeded by :cpp:func:`esp_http_client_get_status_code` for getting the HTTP status of the connection.
|
||||
* :cpp:func:`esp_http_client_read`: Read the HTTP stream
|
||||
* :cpp:func:`esp_http_client_close`: Close the connection
|
||||
* :cpp:func:`esp_http_client_cleanup`: Release allocated resources
|
||||
* :cpp:func:`esp_http_client_read`: Read the HTTP stream.
|
||||
* :cpp:func:`esp_http_client_close`: Close the connection.
|
||||
* :cpp:func:`esp_http_client_cleanup`: Release allocated resources.
|
||||
|
||||
Check out the example function ``http_perform_as_stream_reader`` in the application example for implementation details.
|
||||
|
||||
@ -76,10 +77,11 @@ HTTP Authentication
|
||||
-------------------
|
||||
|
||||
ESP HTTP client supports both **Basic** and **Digest** Authentication.
|
||||
* Users can provide the username and password in the ``url`` or the ``username`` and ``password`` members of the ``esp_http_client_config_t`` configuration. For ``auth_type = HTTP_AUTH_TYPE_BASIC``, the HTTP client takes only 1 perform operation to pass the authentication process.
|
||||
* If ``auth_type = HTTP_AUTH_TYPE_NONE``, but the ``username`` and ``password`` fields are present in the configuration, the HTTP client takes 2 perform operations. The client will receive the ``401 Unauthorized`` header in its first attempt to connect to the server. Based on this information, it decides which authentication method to choose and performs it in the second operation.
|
||||
* Users can provide the username and password in the ``url`` or the ``username`` and ``password`` members of the ``esp_http_client_config_t`` configuration. For ``auth_type = HTTP_AUTH_TYPE_BASIC``, the HTTP client takes only one perform operation to pass the authentication process.
|
||||
* If ``auth_type = HTTP_AUTH_TYPE_NONE``, but the ``username`` and ``password`` fields are present in the configuration, the HTTP client takes two perform operations. The client will receive the ``401 Unauthorized`` header in its first attempt to connect to the server. Based on this information, it decides which authentication method to choose and performs it in the second operation.
|
||||
* Check out the example functions ``http_auth_basic``, ``http_auth_basic_redirect`` (for Basic authentication) and ``http_auth_digest`` (for Digest authentication) in the application example for implementation details.
|
||||
|
||||
|
||||
Examples of Authentication Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -109,7 +111,6 @@ Examples of Authentication Configuration
|
||||
};
|
||||
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
|
||||
@ -1 +1,117 @@
|
||||
.. include:: ../../../en/api-reference/protocols/esp_http_client.rst
|
||||
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user