fetchRemote

Faz uma requisição HTTP e entrega a resposta a um callback.

Existem duas formas de chamar. A moderna, com uma tabela de opções:

Sintaxe

bool fetchRemote ( string url, table opcoes, function callback [, table argumentosDoCallback ] )

E a forma posicional:

bool fetchRemote ( string url [, string fila, number tentativas = 10, number timeout = 10000 ], function callback [, string postData, bool postBinario = false, ... ] )

Parâmetros

Nome	Tipo	Padrão	Descrição
url	string	—	Endereço completo, com o esquema (http:// ou https://).
opcoes	table	—	Configuração da requisição, detalhada abaixo.
callback	function	—	Chamada quando a requisição termina. Obrigatória.
argumentosDoCallback	table	—	Lista de valores repassados ao callback depois dos argumentos fixos.
fila	string	"default"	Nome da fila. Requisições da mesma fila são feitas uma de cada vez.
tentativas	number	10	Quantas vezes tentar conectar.
timeout	number	10000	Tempo limite de conexão, em milissegundos.
postData	string	""	Corpo a enviar. Preenchê-lo transforma a requisição em um POST.
postBinario	bool	false	true se o corpo for binário.
...	any	—	Valores repassados ao callback depois dos argumentos fixos.

Campos da tabela de opções

Campo	Tipo	Padrão	Descrição
queueName	string	"default"	Nome da fila.
connectionAttempts	number	10	Quantas vezes tentar conectar.
connectTimeout	number	10000	Tempo limite de conexão, em milissegundos.
method	string	""	Método HTTP. Vazio significa GET, ou POST quando há postData.
postData	string	""	Corpo da requisição.
postIsBinary	bool	false	true se o corpo for binário.
maxRedirects	number	8	Quantos redirecionamentos seguir.
username	string	""	Usuário para autenticação HTTP.
password	string	""	Senha para autenticação HTTP.
headers	table	—	Tabela de cabeçalhos, no formato ["Nome"] = "valor". Só pares de strings são enviados.

Retorno

true se a requisição foi enfileirada. false, com o motivo no console de debug, se o callback estiver faltando ou não for uma função.

Argumentos do callback

Com a tabela de opções, o callback recebe:

Posição	Descrição
1	Corpo da resposta, como string.
2	Tabela com informações da resposta.
3 em diante	Os valores de argumentosDoCallback, na ordem.

A tabela de informações traz:

Campo	Descrição
success	true quando o servidor respondeu com um código entre 200 e 299.
statusCode	Código HTTP da resposta. 0 se o servidor nunca respondeu.
headers	Cabeçalhos da resposta, no formato ["Nome"] = "valor".

Na forma posicional, o callback recebe:

Posição	Descrição
1	Corpo da resposta em caso de sucesso, ou a string "ERROR".
2	0 em caso de sucesso; senão o código HTTP, ou 1 se o servidor não foi alcançado.
3 em diante	Os argumentos extras que você passou, na ordem.

Nota

Não existe forma de cancelar uma requisição já enviada — ela vai até o fim e o callback será chamado de um jeito ou de outro. Se o resource for parado antes disso, o callback simplesmente não roda.

Exemplo

-- GET: lendo uma resposta em JSON
fetchRemote("https://api.exemplo.com/status", {}, function(corpo, info)
    if not info.success then
        outputDebugString("falha ao consultar a API: " .. info.statusCode, 1)
        return
    end

    local dados = fromJSON(corpo)
    if type(dados) ~= "table" then
        outputDebugString("a API respondeu algo que não é JSON", 2)
        return
    end

    outputDebugString("jogadores no site: " .. tostring(dados.online))
end)

-- POST: enviando JSON e repassando um jogador ao callback
function registrarEntrada(jogador)
    local corpo = toJSON({
        nome = getPlayerName(jogador),
        hora = getRealTime().timestamp
    })

    fetchRemote("https://api.exemplo.com/entradas", {
        method = "POST",
        postData = corpo,
        connectTimeout = 5000,
        headers = {
            ["Content-Type"] = "application/json",
            ["Authorization"] = "Bearer " .. TOKEN
        }
    }, function(resposta, info, quem)
        -- `quem` é o jogador que veio na tabela de argumentos abaixo
        if not isElement(quem) then return end

        if info.success then
            outputDebugString("entrada registrada")
        else
            outputDebugString("entrada recusada (" .. info.statusCode .. "): " .. resposta, 2)
        end
    end, { jogador })
end

Cuidado

Entre o envio e a resposta o jogador pode ter saído do servidor. Confira isElement antes de usar qualquer elemento dentro de um callback.

Veja também

• toJSON — Converte um valor Lua em texto JSON.
• fromJSON — Lê um texto JSON e devolve os valores correspondentes.