發起 POST 請求 (http.post)

聲明

HTTP 狀態碼, 返回頭 JSON 文字, 返回主體 = http.post(URL [, 超時秒, 請求頭, 請求主體資料, URL 不 ESCAPE ])

聲明（命名參數）

20250625 支援，20260402 以後版本支援進度參數

HTTP 狀態碼, 返回頭 JSON 文字, 返回主體 = http.post{
    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, ...}，預設 {}
• 請求主體資料
  字串型，可選參數，使用 post 發送出去的內容，預設是空字串
  20250625 如果為表型，則以 application/x-www-form-urlencoded 的方式編碼發送
• 請求主體 multipart 表單
  表型，可選參數，使用 post 發送出去的 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 協定的 POST 方法發送資料到網路中
該函式可能會讓出，在其返回之前，其他 執行緒 可能會得到運行機會
若伺服器協定版本為 HTTP/1.0 或 HTTP/0.9，可使用

返回主體 = httpPost(URL, 字串型請求主體資料, 超時秒)

該方法替代

進度回調函式接收的 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.post("https://httpbin.org/post?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.post{
    url = "https://httpbin.org/post";
    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

POST 提交表單範例

local c, h, r = http.post('https://httpbin.org/post', 60, {}, 'name=alice&email=alice%40example.com')
if (c == 200) then
    sys.alert(r, 0, '提交成功')
else
    if (c == -1) then
        sys.alert('请求失败，请检查网络连接', 0, '连接超时')
    else
        sys.alert('错误代码 #'..c..'\n'..r, 0, 'HTTP 错误')
    end
end

注：上述代碼中使用了非本章函式 sys.alert