From 3a0aebbc6056a5e4b552ea0614b008b190f4ada7 Mon Sep 17 00:00:00 2001 From: "xjin.gao@quectel.com" Date: Thu, 3 Apr 2025 11:04:51 +0800 Subject: [PATCH] =?UTF-8?q?docs=20(ussl&request&umqtt):=20ussl&request&umq?= =?UTF-8?q?tt=20api=E6=96=87=E6=A1=A3=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 固件版本: N 是否需要文案翻译: 否 --- en/networklib/request.md | 72 +++++++++++++++++++++++++++++++++++----- en/networklib/umqtt.md | 2 +- en/networklib/ussl.md | 5 ++- zh/networklib/request.md | 60 +++++++++++++++++++++++++++------ zh/networklib/umqtt.md | 2 +- zh/networklib/ussl.md | 5 ++- 6 files changed, 123 insertions(+), 23 deletions(-) diff --git a/en/networklib/request.md b/en/networklib/request.md index 47bb049..93a4a0d 100644 --- a/en/networklib/request.md +++ b/en/networklib/request.md @@ -14,17 +14,41 @@ Sends a GET request. **Parameter** -- `url` - Required parameter. The server IP address in the request. +- `url` - Required parameter. The server IP address in the request(Automatically identify http/https requests, and enable ssl on https). - `data` - Optional parameter. Parameters to be carried in JSON format in the request. - `headers` - Dictionary type. Optional parameter. The header information in the request. - `decode` - Boolean type. Optional parameter. Decode the response result with UTF-8 after the request is successful. True: Decode. False: Not decode. Default value: True. Bytes will be returned if False is entered. This parameter is only used for *response.content*. -- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 255. The larger the value, the faster the read speed. Unit: byte. -- `ssl_params` - Optional parameter. The secret key information in the SSL authentication. Format: {"cert": certificate_content, "key": private_content}. +- `timeout` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `ipvtype` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `username` - Optional parameter. User name for user authentication, string type. +- `password` - Optional parameter. Password for user authentication, string type. +- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 2048. The larger the value, the faster the read speed. Unit: byte. +- `ssl_params` - Optional parameter. When the URL is an https request, if the key needs to be passed in during SSL authentication, Format: {"cert": certificate_content, "key": private_content}, content is a string type. **Return Value** - A response object containing all information returned by the server, such as response status codes, response headers, and response bodies. +**Example** + +```python +import request +import utime + +url = "http://www.example.com" +response = request.get(url) + +for i in response.text: + print(i);utime.sleep_ms(10) + +url = "https://www.example.com" +response = request.get(url) + +for i in response.text: + print(i);utime.sleep_ms(10) + +``` + ### `request.post` ```python @@ -35,11 +59,16 @@ Sends a POST request. **Parameter** -- `url` - Required parameter. The server IP address in the request. +- `url` - Required parameter. The server IP address in the request(Automatically identify http/https requests, and enable ssl on https). - `data` - Optional parameter. Parameters to be carried in JSON format in the request. - `headers` - Dictionary type. Optional parameter. The header information in the request. - `decode` - Boolean type. Optional parameter. Decode the response result with UTF-8 after the request is successful. True: Decode. False: Not decode. Default value: True. Bytes will be returned if False is entered. This parameter is only used for *response.content*. -- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 255. The larger the value, the faster the read speed. Unit: byte. +- `timeout` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `ipvtype` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `username` - Optional parameter. User name for user authentication, string type. +- `password` - Optional parameter. Password for user authentication, string type. +- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 2048. The larger the value, the faster the read speed. Unit: byte. +- `ssl_params` - Optional parameter. When the URL is an https request, if the key needs to be passed in during SSL authentication, Format: {"cert": certificate_content, "key": private_content}, content is a string type. **Return Value** @@ -54,6 +83,21 @@ There are four types of data submitted in the POST method: - application/json: JSON format. - application/octet-stream: Binary data stream. This type is used for downloading files. +**Example** + +```python +import request + +url = "http://httpbin.org/post" +data = {"key1": "value1", "key2": "value2", "key3": "value3"} +header = {'key1': 'value1', "key2": "value2", "key3": "value3"} +response = request.post(url, data=ujson.dumps(data), header) + +for i in response.text: + print(i) + +``` + ### `request.put` ```python @@ -64,11 +108,16 @@ Sends a PUT request. **Parameter** -- `url` - Required parameter. The server IP address in the request. +- `url` - Required parameter. The server IP address in the request(Automatically identify http/https requests, and enable ssl on https). - `data` - Optional parameter. Parameters to be carried in JSON format in the request. - `headers` - Dictionary type. Optional parameter. The header information in the request. - `decode` - Boolean type. Optional parameter. Decode the response result with UTF-8 after the request is successful. True: Decode. False: Not decode. Default value: True. Bytes will be returned if False is entered. This parameter is only used for *response.content*. -- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 255. The larger the value, the faster the read speed. Unit: byte. +- `timeout` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `ipvtype` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `username` - Optional parameter. User name for user authentication, string type. +- `password` - Optional parameter. Password for user authentication, string type. +- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 2048. The larger the value, the faster the read speed. Unit: byte. +- `ssl_params` - Optional parameter. When the URL is an https request, if the key needs to be passed in during SSL authentication, Format: {"cert": certificate_content, "key": private_content}, content is a string type. **Return Value** @@ -84,11 +133,16 @@ Sends a HEAD request. **Parameter** -- `url` - Required parameter. The server IP address in the request. +- `url` - Required parameter. The server IP address in the request(Automatically identify http/https requests, and enable ssl on https). - `data` - Optional parameter. Parameters to be carried in JSON format in the request. - `headers` - Dictionary type. Optional parameter. The header information in the request. - `decode `- Boolean type. Optional parameter. Decode the response result with UTF-8 after the request is successful. True: Decode. False: Not decode. Default value: True. Bytes will be returned if False is entered. This parameter is only used for *response.content*. -- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 255. The larger the value, the faster the read speed. Unit: byte. +- `timeout` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `ipvtype` - Optional parameter. Timeout, Default value: 20. Unit: s. +- `username` - Optional parameter. User name for user authentication, string type. +- `password` - Optional parameter. Password for user authentication, string type. +- `sizeof` - Optional parameter. The size of the data blocks in the buffer. Recommended value: 255–4096. Default value: 2048. The larger the value, the faster the read speed. Unit: byte. +- `ssl_params` - Optional parameter. When the URL is an https request, if the key needs to be passed in during SSL authentication, Format: {"cert": certificate_content, "key": private_content}, content is a string type. **Return Value** diff --git a/en/networklib/umqtt.md b/en/networklib/umqtt.md index 5fd82eb..790cfba 100644 --- a/en/networklib/umqtt.md +++ b/en/networklib/umqtt.md @@ -33,7 +33,7 @@ Creates MQTT clients. | password | String | Password registered on the server (optional). | | keepalive | Integer | Timeout of keep-alive (optional). Default value: 60. Unit: s. | | ssl | bool | Enable or disable SSL/TSL encryption. | -| ssl_params | String | SSL/TLS parameter (optional). | +| ssl_params | String | SSL/TLS parameter (optional). if the key needs to be passed in during SSL authentication, Format: {"cert": certificate_content, "key": private_content}, content is a string type.| | reconn | bool | Enable or disable the internal reconnection mechanism (optional). Default value: True (enable). | | version | Integer | The selected MQTT version (optional). version=3 indicates MQTTv3.1. Default value: 4. version=4 indicates MQTTv3.1.1. | diff --git a/en/networklib/ussl.md b/en/networklib/ussl.md index f3a2c17..8e40d2b 100644 --- a/en/networklib/ussl.md +++ b/en/networklib/ussl.md @@ -89,7 +89,10 @@ sock = ussl.wrap_socket(sock, server_hostname="myssl.com", cert=cert, key=key) ## List of Supported Cipher Suites - +``` +SSL version description: +ussl supports SSL 3.0 up to TLS 1.2 and DTLS communication. +``` | Cipher Suite | | ------------------------------------------------------ | diff --git a/zh/networklib/request.md b/zh/networklib/request.md index 34c726e..98ed323 100644 --- a/zh/networklib/request.md +++ b/zh/networklib/request.md @@ -14,17 +14,41 @@ response = request.get(url) **参数描述：** -- `url`- 必填参数，请求的远端地址。 +- `url`- 必填参数，请求的远端地址(自动识别http/https请求，https主动使能ssl)。 - `data`-可选参数，请求中需要携带参数，JSON格式。 - `headers`-可选参数，请求头信息，字典类型。 - `decode`-可选参数，将请求成功后的响应结果解码（UTF8），默认为True，输入False则返回bytes，仅配合response.content使用。 -- `sizeof`-可选参数，读取缓冲区的数据块大小，默认255 个字节，建议255-4096，数值越大读取的速度越快。 -- `ssl_params`-可选参数，SSL认证时传入密钥，格式为{"cert": certificate_content, "key": private_content}。 +- `timeout`-可选参数，socket网络请求超时时间（单位为秒），默认为20，范围：>0。 +- `ipvtype`-可选参数，默认为：0 发送ipv4请求，设置为：1 发送ipv6请求。 +- `username`-可选参数，用户身份验证的用户名，字符串类型。 +- `password`-可选参数，用户身份验证的密码，字符串类型。 +- `sizeof`-可选参数，读取缓冲区的数据块大小，默认2048 个字节，建议255-4096，数值越大读取的速度越快。 +- `ssl_params`-可选参数，url为https请求时，如果SSL认证时需传入密钥，密钥格式为{"cert": certificate_content, "key": private_content}，内容为字符串类型。 **返回值描述：** - 返回响应对象，对象包含了服务器返回的所有信息，例如响应状态码、响应头、响应体等。 +**示例：** + +```python +import request +import utime + +url = "http://www.example.com" +response = request.get(url) + +for i in response.text: + print(i);utime.sleep_ms(10) + +url = "https://www.example.com" +response = request.get(url) + +for i in response.text: + print(i);utime.sleep_ms(10) + +``` + ### `request.post` ```python @@ -35,11 +59,16 @@ response = request.post(url,data) **参数描述：** -- `url`- 必填参数，请求的远端地址。 +- `url`- 必填参数，请求的远端地址(自动识别http/https请求，https主动使能ssl)。 - `data`-可选参数，请求中需要携带的参数，JSON格式。 - `headers`-可选参数，请求头信息，字典类型。 - `decode`-可选参数，将请求成功后的响应结果解码（UTF8），默认为True，输入False则返回bytes，仅配合response.content使用。 -- `sizeof`-可选参数，读取缓冲区的数据块大小，默认255 个字节，建议255-4096， 数值越大读取的速度越快。 +- `timeout`-可选参数，socket网络请求超时时间（单位为秒），默认为20，范围：>0。 +- `ipvtype`-可选参数，默认为：0 发送ipv4请求，设置为：1 发送ipv6请求。 +- `username`-可选参数，用户身份验证的用户名，字符串类型。 +- `password`-可选参数，用户身份验证的密码，字符串类型。 +- `sizeof`-可选参数，读取缓冲区的数据块大小，默认2048 个字节，建议255-4096，数值越大读取的速度越快。 +- `ssl_params`-可选参数，url为https请求时，如果SSL认证时需传入密钥，密钥格式为{"cert": certificate_content, "key": private_content}，内容为字符串类型。 **返回值描述：** @@ -61,7 +90,8 @@ import request url = "http://httpbin.org/post" data = {"key1": "value1", "key2": "value2", "key3": "value3"} -response = request.post(url, data=ujson.dumps(data)) +header = {'key1': 'value1', "key2": "value2", "key3": "value3"} +response = request.post(url, data=ujson.dumps(data), header) for i in response.text: print(i) @@ -79,11 +109,16 @@ response = request.put(url) **参数描述：** -- `url`- 必填参数，请求的远端地址。 +- `url`- 必填参数，请求的远端地址(自动识别http/https请求，https主动使能ssl)。 - `data`-可选参数，请求中需要携带的参数，JSON格式。 - `headers`-可选参数，请求头信息，字典类型。 - `decode`-可选参数，将请求成功后的响应结果解码（UTF8），默认为True，输入False则返回bytes，仅配合response.content使用。 -- `sizeof`-可选参数，读取缓冲区的数据块大小，默认255 个字节，建议255-4096， 数值越大读取的速度越快。 +- `timeout`-可选参数，socket网络请求超时时间（单位为秒），默认为20，范围：>0。 +- `ipvtype`-可选参数，默认为：0 发送ipv4请求，设置为：1 发送ipv6请求。 +- `username`-可选参数，用户身份验证的用户名，字符串类型。 +- `password`-可选参数，用户身份验证的密码，字符串类型。 +- `sizeof`-可选参数，读取缓冲区的数据块大小，默认2048 个字节，建议255-4096，数值越大读取的速度越快。 +- `ssl_params`-可选参数，url为https请求时，如果SSL认证时需传入密钥，密钥格式为{"cert": certificate_content, "key": private_content}，内容为字符串类型。 **返回值描述：** @@ -99,11 +134,16 @@ response = request.head(url) **参数描述：** -- `url`- 必填参数，请求的远端地址。 +- `url`- 必填参数，请求的远端地址(自动识别http/https请求，https主动使能ssl)。 - `data`-可选参数，请求中需要携带的参数，JSON格式。 - `headers`-可选参数，请求头信息，字典类型。 - `decode`-可选参数，将请求成功后的响应结果解码（UTF8），默认为True，输入False则返回bytes，仅配合response.content使用。 -- `sizeof`-可选参数，读取缓冲区的数据块大小，默认255 个字节，建议255-4096， 数值越大读取的速度越快。 +- `timeout`-可选参数，socket网络请求超时时间（单位为秒），默认为20，范围：>0。 +- `ipvtype`-可选参数，默认为：0 发送ipv4请求，设置为：1 发送ipv6请求。 +- `username`-可选参数，用户身份验证的用户名，字符串类型。 +- `password`-可选参数，用户身份验证的密码，字符串类型。 +- `sizeof`-可选参数，读取缓冲区的数据块大小，默认2048 个字节，建议255-4096，数值越大读取的速度越快。 +- `ssl_params`-可选参数，url为https请求时，如果SSL认证时需传入密钥，密钥格式为{"cert": certificate_content, "key": private_content}，内容为字符串类型。 **返回值描述：** diff --git a/zh/networklib/umqtt.md b/zh/networklib/umqtt.md index 673a907..9f324c8 100644 --- a/zh/networklib/umqtt.md +++ b/zh/networklib/umqtt.md @@ -38,7 +38,7 @@ class umqtt.MQTTClient(client_id, server, port=0, user=None, password=None, keep * `ssl` - （可选）是否使能 SSL/TLS 支持，布尔值类型。 -* `ssl_params` - （可选）SSL/TLS 参数，字符串类型。 +* `ssl_params` - （可选）SSL/TLS 参数，如果SSL认证时需传入密钥，密钥格式为{"cert": certificate_content, "key": private_content}，内容为字符串类型。 * `reconn` - （可选）控制是否使用内部重连的标志，布尔值类型，默认开启为True。 diff --git a/zh/networklib/ussl.md b/zh/networklib/ussl.md index 83b4f2c..9e15c30 100644 --- a/zh/networklib/ussl.md +++ b/zh/networklib/ussl.md @@ -89,7 +89,10 @@ sock = ussl.wrap_socket(sock, server_hostname="myssl.com", cert=cert, key=key) ## ssl加密算法套件支持 - +``` +ssl版本说明： +ussl 支持 SSL 3.0 至 TLS 1.2 和 DTLS通信。 +``` | 算法套件 | | ------------------------------------------------------ | -- Gitee