Pular para o conteúdo principal

API HTTP

As utilidades de cliente HTTP estão disponíveis em ptool.http e p.http.

ptool.http.request​

v0.1.0 - Introduced.

ptool.http.request(options) envia uma requisição HTTP e retorna um objeto Response.

Campos de options:

  • url (string, obrigatório): A URL da requisição.
  • method (string, opcional): O método HTTP. O padrão é "GET".
  • headers (table, opcional): Cabeçalhos da requisição, em que chaves e valores são strings.
  • query (table, opcional): Parâmetros de consulta adicionados à URL da requisição. As chaves devem ser strings. Os valores podem ser strings, números ou booleanos.
  • body (string, opcional): O corpo da requisição.
  • json (valor Lua, opcional): Um valor Lua codificado como JSON e usado como corpo da requisição. Quando content-type não está definido, o padrão passa a ser application/json.
  • form (table, opcional): Campos codificados como application/x-www-form-urlencoded e usados como corpo da requisição. As chaves devem ser strings. Os valores podem ser strings, números ou booleanos.
  • timeout_ms (integer, opcional): Tempo limite em milissegundos. O padrão é 30000.
  • connect_timeout_ms (integer, opcional): Tempo limite de conexão em milissegundos.
  • follow_redirects (boolean, opcional): Se os redirecionamentos devem ser seguidos.
  • max_redirects (integer, opcional): Número máximo de redirecionamentos a seguir.
  • user_agent (string, opcional): Define o cabeçalho user-agent.
  • basic_auth (table, opcional): Credenciais HTTP Basic com os campos string username e password.
  • bearer_token (string, opcional): Token Bearer usado no cabeçalho authorization.
  • fail_on_http_error (boolean, opcional): Quando true, respostas HTTP 4xx e 5xx geram erro. O padrão é false.

Notas:

  • body, json e form são mutuamente exclusivos.
  • basic_auth e bearer_token são mutuamente exclusivos.

Exemplo:

local resp = ptool.http.request({
  url = "https://httpbin.org/post",
  method = "POST",
  query = {
    page = 1,
    draft = false,
  },
  json = {
    name = "alice",
    tags = {"admin", "beta"},
  },
  user_agent = "ptool-script/1.0",
  fail_on_http_error = true,
})

print(resp.status, resp.ok)
print(resp:header("content-type"))
local data = resp:json()
print(data.json.name)

Response​

v0.1.0 - Introduced.

Response representa uma resposta HTTP retornada por ptool.http.request(...).

Campos:

  • status (integer): O código de status HTTP.
  • ok (boolean): Se o código de status está na faixa 2xx.
  • url (string): A URL final após redirecionamentos.
  • headers (table): Visão simplificada dos cabeçalhos da resposta (table<string, string>). Cabeçalhos repetidos são unidos com , .

Métodos:

  • resp:text(): Lê e retorna o corpo da resposta como texto.
  • resp:json(): Lê o corpo da resposta, faz parse como JSON e retorna um valor Lua.
  • resp:bytes(): Lê e retorna os bytes brutos como uma string Lua.
  • resp:header(name): Retorna o primeiro valor de cabeçalho correspondente, ou nil.
  • resp:header_values(name): Retorna todos os valores de cabeçalho correspondentes como um array.
  • resp:raise_for_status(): Gera erro para respostas HTTP 4xx e 5xx.

text​

Canonical API name: ptool.http.Response:text.

resp:text() lê e retorna o corpo da resposta como texto.

  • Retorna: string.

json​

Canonical API name: ptool.http.Response:json.

resp:json() lê o corpo da resposta, faz parse como JSON e retorna um valor Lua.

bytes​

Canonical API name: ptool.http.Response:bytes.

resp:bytes() lê e retorna o corpo da resposta como bytes brutos.

  • Retorna: string.

Canonical API name: ptool.http.Response:header.

resp:header(name) retorna o primeiro valor de cabeçalho de resposta que corresponde a name.

  • name (string, obrigatório): O nome do cabeçalho a consultar.
  • Retorna: string | nil.

header_values​

Canonical API name: ptool.http.Response:header_values.

resp:header_values(name) retorna todos os valores de cabeçalho de resposta que correspondem a name.

  • name (string, obrigatório): O nome do cabeçalho a consultar.
  • Retorna: string[].

raise_for_status​

Canonical API name: ptool.http.Response:raise_for_status.

resp:raise_for_status() gera erro quando o código de status da resposta está na faixa 4xx ou 5xx.

Notas:

  • Por padrão, status HTTP fora de 2xx não geram erro. Quem chama pode verificar resp.ok, definir fail_on_http_error = true ou chamar resp:raise_for_status().
  • O corpo da resposta é armazenado em cache após a primeira leitura, então text, json e bytes podem ser chamados várias vezes.