メインコンテンツまでスキップ

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 を使用しています