Fazer uma requisição POST (http.post)

Declaração

código_HTTP, texto_JSON_dos_cabeçalhos, corpo = http.post(URL [, segundos_de_timeout, cabeçalhos, dados_do_corpo, URL_NÃO_ESCAPADA ])

Declaração (parâmetros nomeados)

Aceito a partir de 20250625; parâmetros de progresso aceitos a partir de 20260402.

code_HTTP, texto_JSON_dos_cabeçalhos, corpo = http.post{
    url = URL;
    timeout = segundos_de_timeout;
    headers = cabeçalhos;
    params = parâmetros_de_Query;

    -- estes parâmetros de corpo não podem coexistir; a prioridade é multipart > data > json > upload_file
    multipart = formulário_multipart_do_corpo;
    data = dados_do_corpo;
    json = JSON_do_corpo;
    upload_file = caminho_do_arquivo_de_upload;

    download_file = caminho_para_salvar_o_corpo_em_caso_de_sucesso;
    progress = função_de_callback_de_progresso;
    progress_interval_ms = intervalo_do_callback_em_milissegundos;
}

Parâmetros

• URL
  Texto; endereço URL a requisitar. Por padrão, este método aplica escape à URL; se isso não for desejado, consulte a descrição de URL NÃO ESCAPADA.
• segundos de timeout
  Número real opcional; tempo limite da requisição, em segundos. O padrão é 10.
• cabeçalhos
  Tabela opcional; cabeçalhos enviados, no formato \{field1 = value1, field2 = value2, ...\}; o padrão é \{\}.
• parâmetros de Query
  Tabela opcional; parâmetros de Query enviados, no formato \{field1 = value1, field2 = value2, ...\}; o padrão é \{\}.
• dados do corpo
  String opcional; conteúdo enviado por post. O padrão é uma string vazia.
  20250625 Se for uma tabela, será codificada e enviada como application/x-www-form-urlencoded.
• formulário multipart do corpo
  Tabela opcional; dados de formulário multipart enviados por post, no formato \{field1 = value1, field2 = value2, ...\}; o padrão é \{\}.
• JSON do corpo
  Tabela opcional; codificada e enviada como application/json.
• caminho do arquivo de upload do corpo
  Texto opcional; envia os dados do arquivo diretamente como corpo da requisição.
• caminho para salvar o corpo em caso de sucesso
  Texto opcional; quando fornecido, salva nesse caminho o corpo retornado após o sucesso.
• função de callback de progresso
  Função opcional, aceita a partir de 20260402. É chamada quando o progresso de upload ou download muda; seu primeiro argumento contém as informações de progresso atuais.
• intervalo do callback em milissegundos
  Inteiro opcional, aceito a partir de 20260402. Controla o intervalo de disparo do callback de progresso, em milissegundos.
• URL NÃO ESCAPADA
  Booleano opcional; true envia a URL diretamente, sem escape, e o padrão é false.
  Para aplicar escape personalizado à URL, consulte o módulo lcurl, easy:escape e easy:unescape.

Valores retornados

• código de status HTTP
  Inteiro; código de status http da requisição atual. Retorna -1 em caso de timeout.
• texto JSON dos cabeçalhos retornados
  Texto ou nil; cabeçalhos em JSON retornados ao concluir a requisição. Retorna nil em caso de timeout.
• corpo retornado
  String ou nil; conteúdo retornado ao concluir a requisição. Se o corpo for salvo em arquivo, este valor será o caminho do arquivo. Retorna nil em caso de timeout.

Descrição

Usa o método POST do protocolo HTTP/1.1 para enviar dados à rede.
Esta função pode ceder a execução; antes de retornar, outras threads podem ter a oportunidade de executar.
Se a versão do protocolo do servidor for HTTP/1.0 ou HTTP/0.9, use

corpo = httpPost(URL, dados_do_corpo, segundos_de_timeout)

como alternativa.

O callback de progresso recebe uma estrutura info como a seguinte:

{
    count_of_bytes_sent = bytes_enviados;
    count_of_bytes_expected_to_send = bytes_a_enviar_estimados;
    count_of_bytes_received = bytes_recebidos;
    count_of_bytes_expected_to_receive = bytes_a_receber_estimados;
}

Exemplo

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)", -- simula uma requisição do IE8
    ["Cookie"] = "a=1; b=2; c=3"; -- envia também o Cookie
}, "需要发送过去的数据")
if code == 200 then -- se o código de status retornado for HTTP_OK
    sys.alert(body)
end

Observação: o código acima usa a função sys.alert, que não pertence a este capítulo.

Exemplo (parâmetros nomeados)

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)"; -- simula uma requisição do IE8
        ["Cookie"] = "a=1; b=2; c=3"; -- envia também o Cookie
    };
    params = {
        ["hello"] = "world";
        ["你好"] = "世界";
    };
    data = "需要发送过去的数据";
}
if code == 200 then -- se o código de status retornado for HTTP_OK
    sys.alert(body)
end

Observação: o código acima usa a função sys.alert, que não pertence a este capítulo.

Exemplo de envio de formulário por 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

Observação: o código acima usa a função sys.alert, que não pertence a este capítulo.