Curl: como usar e principais opções

O que é o curl

Curl é uma ferramenta para transferir dados de/para um servidor, usando um dos protocolos suportados. Normalmente, usamos o HTTP, mas as opções são muitas, de FTP e GOPHER a IMAP e LDAP.

O cURL é uma ferramenta de linha de comando que funciona como interface para a biblioteca que faz o serviço pesado, o libcurl.

De forma geral, seu navegador realiza requisições web, recebe respostas, lê/escreve cookies e renderiza sua página. Você pode usar o cURL para fazer tudo isso, exceto a renderização, que cabe ao seu navegador.

Ele oferece uma infinidade de funções úteis como realização de autenticação, interação com API's, preencher formulários HTML, download de arquivos e páginas HTML, etc.

Instalando: como ativar o cURL

No Linux

• Para instalar, se você for usuário de GNU/Linux e usar distribuições baseadas em Debian (como o Ubuntu), basta executar:

sudo apt install curl

• Para distros baseadas em Arch Linux execute:

sudo pacman -S curl

Para outras distribuições, basta usar o seu gerenciador de pacotes padrão.

No macOS

• Há alguns anos o macOS já vem com o curl instalado. Execute curl --version para verificar. Se por algum motivo não estiver presente, é possivel instalar através do Homebrew:

brew install curl

No Windows

• As últimas versões do Windows também já estão vindo com o curl por padrão. Mas você pode baixar um instalador gráfico. Após isso, o curl deve estar em seu PATH e pronto para usar pelo CMD ou PowerShell.

Visualizando um HTML

• Por exemplo, você pode visualizar o conteúdo HTML da página da Alura executando:

 curl www.alura.com/

• Nesse caso, não recebemos nenhum retorno, pois quando não incluímos o https:// na url, o site da Alura nos redireciona automaticamente para o endereço que usa HTTPS e o curl, por padrão, não faz redirecionamento. Para alterar esse comportamento e sermos redirecionados, é possível usar a opção -L:

curl -L www.alura.com/

• Agora temos um retorno, o conteúdo do site em HTML:

<!DOCTYPE html><html
lang="pt-BR"><head><meta
charset="UTF-8"><meta
name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1.0"><title>Alura | Cursos online de Tecnologia</title><
= =>
[continua ...]

Também é possível obter uma resposta mais verbosa, permitindo visualizar os cabeçalhos da requisição HTTP usando a opção -i. Executando o comando abaixo você poderá vizualizar informações como o Status Code da resposta, a data e hora em que ela foi enviada, o tipo do conteúdo da resposta e várias outras informações que podem variar a depender da implementação do servidor.

# usando a url completa com https
curl -i https://www.alura.com/

• Agora o retorno é diferente, primeiro vem as informações de cabeçalho e depois o conteúdo:

HTTP/2 200
date: Mon, 04 Jan 2021 23:06:25 GMT
content-type: text/html; charset=UTF-8
set-cookie: __cfduid=dc9b75f76fba8047815c55beb2f027c441609801585; expires=Wed, 03-Feb-21 23:06:25 GMT; path=/; domain=.alura.com.br; HttpOnly; SameSite=Lax; Secure
expires: Mon, 04 Jan 2021 23:18:29 GMT
cache-control: public, max-age=1800
vary: Accept-Encoding
x-cache: Hit from cloudfront
via: 1.1 6840113c714f694919508fbd89b7f29d.cloudfront.net (CloudFront)
x-amz-cf-pop: EWR53-C1
x-amz-cf-id: oRw4hguQKkUsLXsQ1iZhvwpJ9JQi6LDLkvzcyAAi99Gz1yMe1v2s8A==
age: 1076
cf-cache-status: DYNAMIC
cf-request-id: 07713fec650000f6b7dc289000000001





<!DOCTYPE html><html
lang=><head><meta
charset=><meta
name= content=><title>Alura | Cursos online de Tecnologia</title><meta
name= content=>
[...]

A primeira linha indica a versão do protocolo HTTP usada e o Status Code de sucesso (200).

• Caso queira ignorar o conteúdo da página e receber somente o cabeçalho, você pode usar a opção -I (i maiúsculo):

curl -I https://www.alura.com/

• Resultando em:

HTTP/2 200
date: Tue, 05 Jan 2021 13:43:08 GMT
content-type: text/html; charset=UTF-8
set-cookie: __cfduid=d75dfc6609f183345868c94247f2d49831609854187; expires=Thu, 04-Feb-21 13:43:07 GMT; path=/; domain=.alura.com.br; HttpOnly; SameSite=Lax; Secure
expires: Tue, 05 Jan 2021 14:00:22 GMT
cache-control: public, max-age=1800
vary: Accept-Encoding
x-cache: Hit  cloudfront
  dff867205390cf91b170b9bf1251e39b.cloudfront.net (CloudFront)
x-amz-cf-pop: EWR53-C1
x-amz-cf-id: aaSzZDNSOrAq8TSJp6w19RWg3XOACJT_lvVo9vradu_kqbtIko6NXg==
 
cf-cache-status: DYNAMIC
cf-request-id: a70000f1f226039000000001
expect-ct: max-age=, report-uri=
report-: {:[{:}],:,:}
 {:,:}
 cloudflare
cf-ray: cda0610dfcf1f2-GRU

Fazendo download de arquivos

Vamos utilizar aqui a mídia de instalação da última versão do Ubuntu como exemplo. Para fazer o download de um arquivo, salvando com o mesmo nome do arquivo definido pelo servidor, basta usar a opção -O.

curl -O https://releases.ubuntu.com/20.04.1/ubuntu-20.04.1-desktop-amd64.iso

O download será iniciado e as informações sobre ele serão exibidas:

• Para escolher o nome do arquivo que será salvo, basta adicionar o nome desejado no final do comando:

curl -O https://releases.ubuntu.com/20.04.1/ubuntu-20.04.1-desktop-amd64.iso ubuntu20.iso

• Você também pode esconder informações de progresso do download usando a opção -s:

curl -s -O https://releases.ubuntu.com/20.04.1/ubuntu-20.04.1-desktop-amd64.iso ubuntu20.iso

• Ou definir uma barra de progresso simples ao invés da informação mais completa com -#:

curl -# -O https://releases.ubuntu.com/20.04.1/ubuntu-20.04.1-desktop-amd64.iso ubuntu20.iso

• O progresso do download será mostrado da seguinte forma:

#############                                                             10.6%

• Caso um download seja interrompido, é possível continuá-lo usando a opção -C (mesmo que não tenha sido iniciado com o curl):

curl -C - -O https://releases.ubuntu.com/20.04.1/ubuntu-20.04.1-desktop-amd64.iso

O hífen (-) após o 'C' indica ao curl para que ele descubra automaticamente onde/como continuar o download.

Interagindo com API's REST com GET e POST

O curl também é útil para realizar testes de API's REST. Tomemos como exemplo a aplicação da JSONPlaceholder que foi feita justamente para fins de testes.

• Ela possui as seguintes rotas:

• GET /posts
• GET /posts/:id
• GET /posts/:id/comments
• GET /comments?postId={:id}
• POST /posts
• PUT /posts/:id
• PATCH /posts/:id
• DELETE /posts/:id

• Por padrão, o curl usa o método HTTP GET para realizar as requisições. Para fazer uma requisição GET, basta executar:

curl https://jsonplaceholder.typicode.com/posts

• O retorno será em formato JSON contendo uma lista de posts:

[
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  },
  {
    "userId": 1,
    "id": 2,
    "title": "qui est esse",
    "body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
  },
  {
    "userId": ,
    : ,
    : ,
    : 
  },
  [continua ]

• Também é possível especificar qual método usar, passando a opção -X e o método como argumento:

curl -X GET https://jsonplaceholder.typicode.com/posts

• Para realizar a criação de um post, você pode executar:

curl -i -X POST https://jsonplaceholder.typicode.com/comments \
     -H 'Content-Type: application/json' \
     -d $'{
            "postId": 101, 
            "name": "Vitor Almeida", 
            "email": "[email protected]",
            "body": "De acordo ao manual do curl ( disponível online [...]"
          }' 

• Resultando em:

HTTP/2 201
date: Tue, 05 Jan 2021 01:17:53 GMT
content-type: application/json; charset=utf-8
content-length: 168
set-cookie: __cfduid=d4f15935c351e1b9ece6e8d8cdb1ffa1a1609809470; expires=Thu, 04-Feb-21 01:17:50 GMT; path=/; domain=.typicode.com; HttpOnly; SameSite=Lax
x-powered-by: Express
[continua ...]
{
  "postId": 101,
  "name": "Vitor Almeida",
  "email": "[email protected]",
  "body": "De acordo ao manual do curl ( disponível online [...]",
  "id": 501
}

A opção -H permite adicionar um cabeçalho e a -d permite passar os dados da requisição. Nesse caso, definimos que o conteúdo é no formato JSON e passamos o conteúdo da requisição que será usado para criar uma conta. Podemos ver no resultado que o status foi 201, indicando que um novo recurso foi criado.

Usando o cURL em scripts

É indicado que sua aplicação possua testes automatizados para verificar se seu código está correto e se comportando da forma desejada. De preferência, esses testes devem implementados com bibliotecas nativas da tecnologia em que ela foi implementada, mas também é possível usar o curl em scripts para analisar o comportamento da aplicação.

Abaixo temos um exemplo de script usando o curl para verificar o status de cada requisição feita baseada num arquivo contendo uma lista de URLs para teste.

• Dado um arquivo chamado urls.txt contendo uma lista de URLs:

https://jsonplaceholder.typicode.com/posts
https://jsonplaceholder.typicode.com/posts/1
https://jsonplaceholder.typicode.com/posts/1/comments

• Executando o script no mesmo local onde o arquivo está localizado:

# define o interpretador que será utilizado
#!/bin/bash
# define qual arquivo será usado para ler a lista de URLs
URL_LIST="urls.txt"
# carrega o conteúdo do arquivo num array
readarray URLS < ${URL_LIST}
# para cada URL, executa o curl, extrai o status da requisição, verifica se foi bem sucedido
# e informa o resultado
for URL in ${URLS[@]}
do
	RESPONSE="$(curl -s -I ${URL})"
	STATUS=$(echo $RESPONSE | grep "HTTP" | cut -d " " -f 2)
	if [[ ${STATUS} -eq "200" ]]
	then
		echo $URL [SUCESSO]
	fi
done

• Temos o resultado:

https://jsonplaceholder.typicode.com/posts [SUCESSO]
https://jsonplaceholder.typicode.com/posts/1 [SUCESSO]
https://jsonplaceholder.typicode.com/posts/1/comments [SUCESSO]

Dessa forma não é necessario executar manualmente todos os comandos para realizar o teste basta adicionar os endereços desejados na lista de URLs.

cURL versus Postman

O curl, por ser uma ferramenta de linha de comando, tem uma interface menos amigável, mas permite um fluxo diferente no seu uso, podendo ser usado para automatizar tarefas.

Já o Postman possui uma interface gráfica que é mais amigável e permite criação de sessões e organizar seus testes por projetos e de várias outras formas. Se quiser saber mais sobre o Postman, confira este vídeo tutorial sobre a ferramenta no Alura+:

https://www.youtube.com/watch?v=op81bMbgZXs

Como na grande parte das questões relativas à tecnologia, qual das ferramentas usar vai depender do seu contexto e do seu objetivo. Avalie bem suas necessidades, teste as duas aplicações e decida o que for melhor para você.

Usamos muito Postman e cURLna Alura, tanto para testes quanto para automatizações.