Pular para o conteúdo principal

Remote - Cliente HTTP

Introdução​

Muitas vezes, em nossas aplicações, precisamos fazer requisições HTTP para serviços externos. Isso pode ser feito utilizando o recurso _remote.

Para fazer chamadas HTTP internamente para outros serviços ou servidores internos no computador, ou para chamar algum serviço na internet, a utilização do recurso Remote é essencial.

Veja documentação do recurso Remote.

Inclusive podemos enviar e receber dados em JSON e fazer upload ou download de arquivos.

Inicialização​

Para podermos realizar uma chamada HTTP, devemos primeiramente inicia-la, para isso utilizaremos o método init do _remote e então guardaremos o resultado desta operação em uma variável chamada remote para que assim tenhamos como referenciar a requisição:

// Suporta enviar Parâmetros HTTP
const remoteSimples = _remote.init()
// Suporta enviar JSON:
const remoteJSON = _remote.init().asJSON()

Configuração​

Também podemos definir configurações globais na aplicação, repare neste exemplo completo:

  ...
  "remote": { 
    "exemplo-basic-auth": {
      "url": "https://exemplo.com/api/rest/exemplo",
      "form": true,
      "authorization": {
        "username": "admin",
        "password": "pass"
      },
      "data": {
        "param1": "valor 1...",
        "param2": "valor 2..."
      }
    },
    "exemplo-auth-token": {
      "urlPrefix": "https://exemplo.com/api",
      "json": true,
      "authorization": "Bearer AUTH-TOKEN-AQUI",
      "connectTimeout": 5000,
      "readTimeout": 60000,
    }
  },
  ...

Podemos configurar um prefixo de URL (urlPrefix) ou a URL completa (url).

Podemos definir se a requisição por padrão deve enviar os dados como Form ou JSON.

Suporta enviar autorização básica com login e senha ou token.

E é possível definir os dados padrão que serão enviados (data), e ainda os tempos limites de conexão (connectTimeout) e leitura (readTimeout).

Como Usar​

Para utilizar o recurso Remote com as configurações definidas na aplicação, basta iniciar o recurso com a chave da configuração, por exemplo:

const resposta = _remote.init("exemplo-basic-auth").post()

E caso seja definida a URL de prefixo:

const remote = _remote.init("exemplo-auth-token")
const resposta = remote.post(
    "/services/carrega-dados",
    _val.map()
        .set("param1", "valor 1")
        .set("param2", "valor 2")
)

Pedido HTTP​

Veja como podemos iniciar um pedido HTTP utilizando o recurso Remote.

Enviar JSON​

Para enviar dados no formato JSON precisamos sinalizar o tipo de conteúdo como JSON:

A forma simples de fazer isso é utilizando o método asJSON(), por exemplo:

const remote = _remote.init().asJSON()
remote.setURL("http://exemplo.com/salva")
const resposta = remote.post(
    _val.map()
        .set("dados", "exemplo")
        .set("json", true)
)

Assim os dados vão ser enviados como JSON para os métodos HTTP de POST e de PUT, mas para GET e DELETE os dados são sempre enviados na querystring porque para estes métodos não é suportado pelo protocolo HTTP conter corpo com dados.

Métodos HTTP​

Não precisamos indicar explicitamente no cabeçalho da chamada o seu método HTTP, para isso a nossa referência da chamada possui uma função própria para cada tipo de método HTTP:

const remote = _remote.init()

remote.setURL("http://exemplo.com")

remote.get(); // para chamadas GET
remote.post(); // para chamadas POST
remote.put(); // para chamadas PUT
remote.delete(); // para chamadas DELETE

Cabeçalho HTTP​

Para configurar os parâmetros do cabeçalho HTTP podemos definir as chaves com o método getHeader(), por exemplo:

const remote = _remote.init()

remote.getHeader().set("CHAVE", "VALOR")

URL da Requisição​

Para indicar a URL da requisição basta passar como o primeiro parâmetro das funções dos respectivos métodos HTTP:

const remote = _remote.init().asJSON()

remote.get("http://exemplo.com") // para chamadas GET
remote.post("http://exemplo.com") // para chamadas POST
remote.put("http://exemplo.com") // para chamadas PUT
remote.delete("http://exemplo.com") // para chamadas DELETE

Adicionando dados à requisição​

Caso precise adicionar dados ao corpo do pedido, basta passar os mesmos como segundo parâmetro da função do respectivo método:

const remote = _remote.init().asJSON()

remote.get("http://exemplo.com", _val.map().set("user_id", 1)) // para chamadas GET
remote.post("http://exemplo.com", _val.map().set("user_id", 1)) // para chamadas POST
remote.put("http://exemplo.com", _val.map().set("user_id", 1)) // para chamadas PUT
remote.delete("http://exemplo.com", _val.map().set("user_id", 1)) // para chamadas DELETE

Resposta​

Depois de receber a resposta da requisição podemos ler seus dados utilizando o método json ou content:

const remote = _remote.init().asJSON()

const resposta = remote.post("http://exemplo.com", _val.map().set("user_id", 1))

if (resposta.ok()) {
    _log.info("Resposta em JSON", resposta.json())
} else {
    _log.info("Falhou com o status: "+ resposta.statusCode(), resposta.content())
}

Na resposta com a função json() obtemos o array ou o objeto fornecido como Values, e com a função content() obtemos conteúdo em texto crú ou o HTML, e o número do código de status recebido vem no statusCode(), sendo que o ok() retorna um valor booleano sendo verdadeiro se o código de status for dentro do intervalo de 200 e 299.

Conclusão​

Com o recurso Remote podemos integrar APIs externas, podemos exportar, importar ou sincronizar dados.

Inclusive podemos integrar serviços implementados em outras tecnologias, o que permite realizar operações específicas fornecidas por outras linguagens.