Curl: como usar e principais opções

almeida-vitor
almeida-vitor

Compartilhe

O que é o curl

Curl é uma ferramenta para transferir dados de/para um servidor, usando um dos protocolos suportados. Normalmente estamos usando o HTTP.

Mas as opções são muitas. De FTP e GOPHER a IMAP e LDAP.

Ele é 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. O curl pode 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 paginas HTML etc.

Instalando o CURL

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.

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

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 grafico. Após isso, o curl deve estar em seu PATH e pronto para usar pelo CMD ou PowerShell.

Visualizando um HTML e fazendo download de arquivos:

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><meta
name="description" content="Aprenda Programação, Front-end, Data Science, UX, DevOps, Marketing, Inovação e Gestão na maior plataforma de tecnologia do Brasil"><link
rel="canonical" href="https://www.alura.com.br"><link
href="https://fonts.googleapis.com/css?display=swap&family=Open+Sans:300,400,400i,600,700,800" rel="stylesheet" crossorigin><link
rel="preconnect" href="https://fonts.gstatic.com/" crossorigin><link
rel="stylesheet" href="/bundle,base/_reset,base/base,base/buttons,base/colors,base/titulos.1606791285.css"><link
rel="stylesheet" href="/bundle,home/homeNova/career-colors,home/homeNova/careers,home/homeNova/companies,home/homeNova/features,home/homeNova/home,home/homeNova/mobile,home/homeNova/testimonies.1606791285.css"><link
rel="stylesheet" href="/assets/css/block/elasticMedia.1570550707.css"><meta
property="og:locale" content="pt_BR"><meta
property="og:description" content="Aprenda Programação, Front-end, Data Science, UX, DevOps, Marketing, Inovação e Gestão na maior plataforma de tecnologia do Brasil"><meta
property="og:title" content="Alura | Cursos online de Tecnologia"><meta
property="og:site_name" content="Alura">
[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
expect-ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
report-to: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report?s=jCtQad61F4%2BAgG1On8yzqLOj7Su2x65Ee3Rva9wYXgVkVCJooAuEk4p0ROzoW%2FLnm7EzVDwJMIWgsxWWdZwZIK6BVlhgfWwXQAK7eVpqe8jE5weey8fBGLzbC2Fa"}],"group":"cf-nel","max_age":604800}
nel: {"report_to":"cf-nel","max_age":604800}
server: cloudflare
cf-ray: 60c89c270e59f6b7-GRU

<!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><meta
name="description" content="Aprenda Programação, Front-end, Data Science, UX, DevOps, Marketing, Inovação e Gestão na maior plataforma
de tecnologia do Brasil">

[...]

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 from cloudfront
via: 1.1 dff867205390cf91b170b9bf1251e39b.cloudfront.net (CloudFront)
x-amz-cf-pop: EWR53-C1
x-amz-cf-id: aaSzZDNSOrAq8TSJp6w19RWg3XOACJT_lvVo9vradu_kqbtIko6NXg==
age: 765
cf-cache-status: DYNAMIC
cf-request-id: 07746290a70000f1f226039000000001
expect-ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
report-to: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report?s=Z8B8%2FuB2xMZcwNSOgGUvDCVtVMwtjauvrsNMjlkTioeb%2BhJawMefk9n4xiXWAWfQKk04YpbZzPKxozIwbGtIyjK3iAPPQb8h7eAdG5CHsDiZFEbvWkG0e%2BqyucdD"}],"group":"cf-nel","max_age":604800}
nel: {"report_to":"cf-nel","max_age":604800}
server: cloudflare
cf-ray: 60cda0610dfcf1f2-GRU

Fazendo download de arquivos:

Vamos utilizar aqui a mídia de instalação da ultima 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:


  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  3 2656M    3 83.3M    0     0  6638k      0  0:06:49  0:00:12  0:06:37 9014k

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 https://jsonplaceholder.typicode.com/ 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": 1,
    "id": 3,
    "title": "ea molestias quasi exercitationem repellat qui ipsa sit aut",
    "body": "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut"
  },
  [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 usando para automatizar tarefas.

Já o Postman possui uma interface gráfica, é mais amigável, 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 video tutorial sobre a ferramenta no Alura+:

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 curl na Alura, tanto para testes quanto para automatizações.

Veja outros artigos sobre DevOps