发起 PUT 请求 (http.put)
声明
HTTP状态码, 返回头JSON文本, 返回主体 = http.put(URL [, 超时秒, 请求头, 请求主体数据, URL不ESCAPE ])
声明(命名参数)
20250625 支持,20260402 以后版本支持进度参数
HTTP状态码, 返回头JSON文本, 返回主体 = http.put{
url = URL;
timeout = 超时秒;
headers = 请求头;
params = Query参数;
-- 以下请求主体参数不可并存,优先顺序为 multipart > data > json > upload_file
multipart = 请求主体multipart表单;
data = 请求主体数据;
json = 请求主体JSON;
upload_file = 请求主体上传文件路径;
download_file = 请求成功返回主体保存文件路径;
progress = 进度回调函数;
progress_interval_ms = 进度回调间隔毫秒;
}
参数
- URL
文本型,需要请求的 URL 地址,该方法默认会对 URL 进行 escape 处理,如不需要可参考 URL 不 ESCAPE 参数说明 - 超时秒
实数型,可选参数,请求超时时间,单位秒,默认 10 - 请求头
表型,可选参数,发出的请求的头部信息,形式 {field1 = value1, field2 = value2, ...},默认 {} - Query 参数
表型,可选参数,发出的请求的 Query 参数,形式 {field1 = value1, field2 = value2, ...},默认 {} - 请求主体数据
字符串型,可选参数,使用 PUT 发送出去的内容,默认为空字符串
20250625 如果为表型,则以 application/x-www-form-urlencoded 的方式编码发送 - 请求主体 multipart 表单
表型,可选参数,使用 PUT 发送出去的 multipart 表单数据,形式 {field1 = value1, field2 = value2, ...},默认 {} - 请求主体 JSON
表型,可选参数,以 application/json 的方式编码发送 - 请求主体上传文件路径
文本型,可选参数,将文件数据直接作为请求体发送 - 请求成功返回主体保存文件路径
文本型,可选参数,如果有该参数,则请求成功后返回主体为保存的文件路径 - 进度回调函数
函数型,可选参数,20260402 以后版本支持。请求上传或下载进度变化时调用,回调函数第一个参数为当前进度信息 - 进度回调间隔毫秒
整数型,可选参数,20260402 以后版本支持。控制进度回调触发间隔,单位毫秒 - URL 不 ESCAPE
布尔型,可选参数,true 表示不对 URL 进行 escape 直接请求,默认 false
对 URL 进行自定义 escape 可参考 lcurl 模块 的 easy:escape、easy:unescape
返回值
- HTTP 状态码
整数型,返回当次请求的 http 状态码,请求超时返回 -1 - 返回头 JSON 文本
文本型 或 nil,请求完成返回的 JSON 形式头部信息,请求超时返回 nil - 返回主体
字符串型 或 nil,请求完成返回的内容,如果请求主体保存到文件,则此值为文件路径,请求超时返回 nil
说明
使用 HTTP/1.1 协议的 PUT 方法发送数据到网络中,它与 POST 用法一致
该函数可能会让出,在其返回之前,其他 线程 可能会得到运行机会
进度回调函数接收的 info 结构如下:
{
count_of_bytes_sent = 已发送字节数;
count_of_bytes_expected_to_send = 预计需要发送字节数;
count_of_bytes_received = 已接收字节数;
count_of_bytes_expected_to_receive = 预计需要接收字节数;
}
示例
local code, res_headers, body = http.put("https://httpbin.org/put?hello=world&你好=世界", 15, {
["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)", -- 模拟 IE8 的请求
["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
}, "需要发送过去的数据")
if code == 200 then -- 如果返回的状态码是 HTTP_OK
sys.alert(body)
end
注:上述代码中使用了非本章函数 sys.alert
示例(命名参数)
local code, res_headers, body = http.put{
url = "https://httpbin.org/put";
timeout = 15;
headers = {
["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)"; -- 模拟 IE8 的请求
["Cookie"] = "a=1; b=2; c=3"; -- 顺带 Cookie 提交
};
params = {
["hello"] = "world";
["你好"] = "世界";
};
data = "需要发送过去的数据";
}
if code == 200 then -- 如果返回的状态码是 HTTP_OK
sys.alert(body)
end
注:上述代码中使用了非本章函数 sys.alert