Cabeçalhos de resposta HTTP no cURL: Cada flag, técnica e receita de scripting

Os cabeçalhos de resposta HTTP são os metadados que um servidor envia de volta com cada resposta, abrangendo tudo, desde o tipo de conteúdo e políticas de cache até contadores de limite de taxa e diretivas de segurança. Quando está a depurar uma API instável, a verificar se um CDN está a servir os cabeçalhos de cache corretos ou a verificar se um site define a política CORS correta, a primeira ferramenta a que a maioria dos programadores recorre é o cURL.

Por predefinição, o cURL apenas imprime o corpo da resposta para o stdout, o que significa que é necessário solicitar explicitamente os cabeçalhos de resposta HTTP no cURL antes de os poder ver. O desafio é que o cURL oferece pelo menos meia dúzia de sinalizadores e técnicas para exibir esses cabeçalhos, e cada um está otimizado para um fluxo de trabalho diferente. Deve recorrer a -i, -I, -vou -D? E quanto às mais recentes -w variáveis de saída que permitem extrair um único cabeçalho pelo nome ou exportar todos os cabeçalhos como JSON?

Este guia percorre todas as abordagens para visualizar cabeçalhos de resposta HTTP no cURL, desde a mais simples linha de comando até receitas de scripts fáceis de automatizar, para que possa escolher a ferramenta certa para o trabalho sem ter de memorizar todas as secções da página de manual.

Cada resposta HTTP contém um conjunto de cabeçalhos que indicam ao cliente como interpretar a carga útil. Um Content-Type cabeçalho que diz application/json significa uma coisa; text/html significa outra. Para além do básico, os cabeçalhos revelam o comportamento de cache (Cache-Control, ETag), requisitos de autenticação (WWW-Authenticate), o estado do limite de taxa (X-RateLimit-Remaining) e políticas de segurança (Strict-Transport-Security, Content-Security-Policy).

Para quem trabalha com web scraping, os cabeçalhos de resposta são especialmente reveladores. Eles podem indicar se um servidor está a comprimir as suas respostas, se os seus pedidos estão a ser redirecionados através de uma cadeia de URLs intermediárias ou se está prestes a atingir um limite de taxa. É por isso que aprender a inspecionar cabeçalhos de resposta HTTP no cURL de forma rápida e precisa é uma competência fundamental para qualquer pessoa que trabalhe com HTTP na linha de comandos.

Antes de mergulhar nos exemplos, aqui está uma tabela comparativa que pode adicionar aos favoritos. Ela mapeia cada sinalizador para o seu comportamento e o cenário em que é mais útil quando precisa de exibir cabeçalhos de resposta HTTP no cURL.

Escolha a linha que corresponde ao seu fluxo de trabalho e, em seguida, leia a secção correspondente abaixo para obter detalhes e exemplos.

A forma mais simples de ver os cabeçalhos de resposta HTTP no cURL é a -i sinalizador (forma longa: --include). Ela instrui o cURL a antepor o conjunto completo de cabeçalhos de resposta à saída do corpo, separados por uma linha em branco.

curl -i https://httpbin.org/get

A saída começa com a linha de estado (HTTP/1.1 200 OK), seguida de cada cabeçalho na sua própria linha, depois uma linha em branco e, finalmente, o corpo da resposta. Esta é uma solicitação GET, não uma solicitação HEAD, pelo que obtém a resposta real que o servidor enviaria a um navegador.

Use -i quando quiser dar uma vista de olhos rápida tanto aos cabeçalhos como ao corpo com um único comando de terminal. A desvantagem é que os cabeçalhos e o corpo ficam misturados num único fluxo, o que torna mais difícil a análise programática. Para scripts, uma das técnicas posteriores (como -D ou -w) é geralmente mais adequada.

Quando precisar apenas dos cabeçalhos e não se importar com o corpo, use -I (ou a sua forma longa equivalente, --head). Ambas as opções enviam uma solicitação HTTP HEAD, que pede ao servidor apenas os cabeçalhos.

curl -I https://httpbin.org/get

A saída é apenas a linha de estado mais os cabeçalhos. Sem corpo, sem ruído extra. A --head sintaxe faz o mesmo, mas é mais clara em scripts de shell, tornando a sua intenção óbvia para quem estiver a rever o código.

Uma ressalva: uma resposta HEAD nem sempre é idêntica a uma resposta GET. Alguns servidores devolvem cabeçalhos diferentes (ou ignoram completamente certos cabeçalhos) para pedidos HEAD. Se estiver a resolver um problema com um cabeçalho que só aparece num GET real, este sinalizador irá induzi-lo em erro.

A solução alternativa é a -s -o /dev/null -D - técnica, que envia uma solicitação GET completa, mas descarta o corpo e imprime apenas os cabeçalhos da resposta para o stdout:

curl -s -o /dev/null -D - https://httpbin.org/get

Eis o que cada parte faz: -s silencia o medidor de progresso, -o /dev/null envia o corpo para lugar nenhum e -D - escreve os cabeçalhos para o stdout (o traço significa «stdout» em vez de um nome de ficheiro). Isto dá-lhe os cabeçalhos GET reais sem o ruído do corpo, e é um padrão essencial quando precisa de cabeçalhos de resposta HTTP precisos no cURL, mas o HEAD não é fiável.

O modo detalhado é o canivete suíço da depuração HTTP. O -v (ou --verbose) faz com que o cURL imprima a transação completa: detalhes do handshake TLS, cabeçalhos de solicitação, cabeçalhos de resposta e o corpo.

curl -v https://httpbin.org/get

Na saída, as linhas precedidas por > são os cabeçalhos de solicitação que o seu cliente enviou, as linhas com o prefixo < são os cabeçalhos de resposta que o servidor devolveu, e as linhas precedidas por * são mensagens informativas do próprio cURL (informações de ligação, negociação TLS, etc.).

Para reduzir o ruído, combine -v com -s para suprimir o medidor de progresso. Se quiser capturar apenas as linhas de cabeçalho da saída detalhada num script, pode redirecionar o stderr (onde -v escreve as suas informações de depuração) e filtrar:

curl -vs https://httpbin.org/get 2>&1 | grep '^<'

Isto canaliza tanto o stdout como o stderr em conjunto, mantendo apenas as linhas que começam por <, fornecendo-lhe uma lista limpa de cabeçalhos de resposta a partir da saída detalhada do cURL. É ótimo para depuração rápida e pontual, embora para scripts de produção seja preferível utilizar as abordagens mais estruturadas abordadas a seguir.

A -D (abreviatura de --dump-header) grava os cabeçalhos de resposta num ficheiro em vez de na saída padrão (stdout). Combine-a com -o para guardar o corpo separadamente:

curl -D headers.txt -o body.html https://example.com

Após a execução, headers.txt contém todos os cabeçalhos de resposta e body.html contém o conteúdo da página. Isto é ideal para registo, onde pretende arquivar cabeçalhos e corpo lado a lado para revisão posterior.

Para registos com data e hora (útil em scripts de monitorização), gere o nome do ficheiro dinamicamente:

curl -D "headers_$(date +%Y%m%d_%H%M%S).txt" -o /dev/null https://example.com

Cada execução cria um novo ficheiro como headers_20240615_143022.txt, para que possa acompanhar como os cabeçalhos de resposta HTTP no cURL mudam ao longo do tempo. Combine isto com uma tarefa cron e terá um monitor de cabeçalhos leve, sem qualquer ferramenta de terceiros.

Às vezes, só te interessa um cabeçalho, como Content-Type ou X-RateLimit-Remaining. Canalizar a saída do cURL através de ferramentas Unix padrão permite-lhe chegar lá rapidamente.

Extraia um único cabeçalho pelo nome com o grep, que não distingue maiúsculas de minúsculas:

curl -sI https://httpbin.org/get | grep -i "content-type"

Para isolar apenas o valor (sem o nome do cabeçalho), adicione cut ou awk:

curl -sI https://httpbin.org/get | grep -i "content-type" | cut -d':' -f2- | xargs

O cut comando divide na vírgula e mantém tudo o que vem a seguir, enquanto xargs elimina os espaços em branco à volta. Em alternativa, awk pode fazê-lo de uma só vez:

curl -sI https://httpbin.org/get | awk -F': ' '/^[Cc]ontent-[Tt]ype/ {print $2}'

Cuidado com correspondências parciais de nomes. Pesquisar por Content também corresponderia a Content-Length, Content-Encodinge qualquer outra coisa que comece da mesma forma. Procure sempre o nome completo do cabeçalho seguido de dois pontos para evitar falsos positivos.

A partir da versão 7.83 (lançada no início de 2022), o cURL introduziu duas variáveis de saída que simplificam a extração de cabeçalhos de resposta HTTP em scripts cURL: %header{name} para um único cabeçalho e %{header_json} para todos os cabeçalhos como JSON.

Extraia um cabeçalho de forma limpa, sem necessidade de grep:

curl -s -o /dev/null -w '%header{content-type}' https://httpbin.org/get

Isto imprime apenas o valor do Content-Type cabeçalho. Sem análise, sem pipes, sem expressões regulares.

Para obter todos os cabeçalhos de resposta como um objeto JSON, use:

curl -s -o /dev/null -w '%{header_json}' https://httpbin.org/get

A saída é JSON válido, o que significa que pode canalizá-la diretamente para jq para formatação ou extração de campos:

curl -s -o /dev/null -w '%{header_json}' https://httpbin.org/get | jq '.["content-type"]'

Quando aparecem nomes de cabeçalhos duplicados (como vários Set-Cookie cabeçalhos), o cURL agrupa-os na primeira ocorrência e recolhe todos os valores numa matriz JSON, para que nunca perca dados.

Uma nota importante: estas variáveis de saída requerem o cURL 7.83 ou posterior. Execute curl --version para verificar a sua versão. Se estiver a utilizar uma versão mais antiga, a grep/awk abordagem da secção anterior continua a ser a sua melhor opção.

Depois de conseguir extrair cabeçalhos de resposta HTTP no cURL, o próximo passo é criar fluxos de trabalho repetíveis em torno deles. Aqui estão três padrões que funcionam bem para auditar cabeçalhos em escala.

Auditar um cabeçalho específico em vários URLs:

while IFS= read -r url; do
  val=$(curl -s -o /dev/null -w '%header{strict-transport-security}' "$url")
  echo "$url → $val"
done < urls.txt

Alimente um ficheiro de URLs e obtenha um relatório rápido sobre quais definem o Strict-Transport-Security cabeçalho.

Monitorizar alterações nos cabeçalhos ao longo do tempo com o diff:

curl -sI https://example.com > /tmp/headers_prev.txt
# ... wait, or run via cron ...
curl -sI https://example.com > /tmp/headers_now.txt
diff /tmp/headers_prev.txt /tmp/headers_now.txt

Incorpore isto numa tarefa cron e envie a saída do diff para um webhook do Slack ou por e-mail. É uma forma simples de detetar alterações inesperadas na configuração.

Crie um alias de shell para verificações frequentes:

alias hcheck='curl -s -o /dev/null -D - -w "\n"'

Agora pode digitar hcheck https://example.com para extrair rapidamente os cabeçalhos de resposta de qualquer URL com uma solicitação GET limpa.

Mesmo as inspeções simples de cabeçalhos podem correr mal. Abaixo estão três situações com as quais é provável que se depare ao trabalhar com cabeçalhos de resposta HTTP no cURL, juntamente com os sinalizadores que as resolvem.

Se o cURL se recusar a estabelecer ligação devido a um problema de certificado, pode ignorar a verificação com -k (ou --insecure):

curl -kI https://self-signed.example.com

Utilize isto apenas em ambientes de desenvolvimento ou de testes internos. Em produção, a melhor solução é fornecer o pacote de CA correto com --cacert /path/to/ca-bundle.crt para que a ligação seja efetivamente verificada.

Por predefinição, o cURL não segue redirecionamentos. Se um URL devolver um 301 ou 302, só verá os cabeçalhos da resposta inicial. Adicione -L (ou --location) para seguir a cadeia:

curl -LI https://example.com

Para capturar os cabeçalhos em cada salto (não apenas no destino final), combine -L com -D:

curl -L -D all_headers.txt -o /dev/null https://example.com

O ficheiro all_headers.txt conterá blocos de cabeçalho de cada redirecionamento, separados por linhas em branco. Também pode definir --max-redirs 5 para limitar o número de saltos e evitar loops infinitos.

Muitos servidores comprimem as respostas com gzip ou Brotli, o que pode fazer com que a saída do corpo bruto pareça lixo. O --compressed sinalizador diz ao cURL para enviar o cabeçalho apropriado Accept-Encoding cabeçalho e descomprimir automaticamente a resposta:

curl --compressed -i https://example.com

Isto não altera os próprios cabeçalhos, mas garante que pode ler o corpo juntamente com eles. Se estiver apenas a inspecionar cabeçalhos, a compressão não é um problema, mas é importante quando combina -i para visualizar ambos.

• Use -i para verificações visuais rápidas que mostram os cabeçalhos de resposta em linha com o corpo, e -I quando precisar apenas dos cabeçalhos de uma solicitação HEAD.
• O -s -o /dev/null -D - padrão é essencial quando as respostas HEAD diferem das GET: fornece-lhe cabeçalhos GET reais sem ruído do corpo.
• O modo detalhado (-v) é a ferramenta mais completa do seu arsenal, mostrando cabeçalhos de solicitação, cabeçalhos de resposta e detalhes de TLS de uma só vez.
• Variáveis de saída do cURL 7.83+ (%header{name} e %{header_json}) eliminam a necessidade de pipelines grep/awk e integram-se perfeitamente com fluxos de trabalho baseados em JSON.
• Combine -L com -D para capturar cabeçalhos de cada redirecionamento e verifique sempre a sua versão do cURL antes de utilizar funcionalidades mais recentes.

curl -i envia uma solicitação GET padrão e inclui os cabeçalhos de resposta acima do corpo na saída. curl -I envia uma solicitação HEAD, que retorna apenas cabeçalhos, sem corpo algum. O -i dá-lhe a resposta completa; a maiúscula -I é mais rápido, mas pode devolver cabeçalhos diferentes dos de um GET real em alguns servidores.

Use a -w '%{header_json}' variável write-out, disponível no cURL 7.83 e versões posteriores. Execute curl -s -o /dev/null -w '%{header_json}' <URL> para obter um objeto JSON válido contendo todos os cabeçalhos. Envie o resultado para jq para formatação ou extração de campos. Os cabeçalhos duplicados são automaticamente agrupados em matrizes JSON.

No Windows, curl no PowerShell é um alias para Invoke-WebRequest. Execute (Invoke-WebRequest -Uri "https://example.com" -Method Head).Headers para ver uma tabela hash dos cabeçalhos de resposta. Se quiser o binário cURL real, chame curl.exe -I https://example.com para ignorar o alias e use os mesmos sinalizadores descritos neste guia.

Combine -L (seguir redirecionamentos) com -D (descarregar cabeçalhos) da seguinte forma: curl -L -D headers.txt -o /dev/null https://example.com. O ficheiro resultante conterá blocos de cabeçalhos separados para cada salto de redirecionamento, delimitados por linhas em branco. Também pode usar curl -Lv para ver os cabeçalhos de cada etapa em tempo real no stderr.

Inspecionar cabeçalhos de resposta HTTP no cURL é uma daquelas competências que compensa todos os dias, uma vez que a domine. Para verificações rápidas, -i e -I levam-no até lá com um único comando. Quando precisar de uma visibilidade mais aprofundada, -v mostra a transação completa e -D permite-lhe registar cabeçalhos em ficheiros para análise posterior. E se estiver a construir pipelines automatizados, as mais recentes -w variáveis de saída (disponíveis no cURL 7.83+) permitem-lhe extrair cabeçalhos como JSON limpo, sem qualquer complexidade de processamento de texto.

O segredo é combinar o sinalizador certo com a tarefa. Use a tabela de referência rápida deste guia como sua folha de referência e aproveite as receitas de script para transformar comandos pontuais em verificações repetíveis.

Se os seus scripts cURL estiverem a encontrar proteções anti-bot, CAPTCHAs ou bloqueios de IP antes mesmo de conseguir inspecionar os cabeçalhos, a WebScrapingAPI pode tratar da camada de pedidos por si, gerindo a rotação de proxies e a prevenção de bloqueios por trás de um único ponto de extremidade da API, para que se possa concentrar nos dados em vez de na infraestrutura.