Uma resposta de API chega em JSON, você procura um valor e, em seguida, termina com grep e cut. Isso pode funcionar enquanto o arquivo mantiver exatamente o mesmo formato. Assim que uma chave passa para um objeto aninhado, um array aparece ou a resposta se torna uma página HTML após um erro HTTP, o script às vezes lê o dado errado.
jq lê a estrutura JSON em vez de procurar uma sequência de caracteres. É a ferramenta certa para extrair um campo, filtrar um array e fazer um script falhar quando o dado esperado está ausente.
Verificar jq e o arquivo antes da requisição
No Debian ou Ubuntu, instale o pacote com sudo apt update && sudo apt install jq. Fedora, RHEL e suas derivas normalmente usam sudo dnf install jq. Comece por verificar o comando e o documento que seu script irá ler.
jq --version
jq empty config.json
jq empty não exibe o documento. Ele verifica sua sintaxe e retorna um erro se o arquivo estiver truncado ou inválido. Faça esse controle antes de um loop, uma implantação ou uma modificação de configuração. Uma resposta HTTP 502 registrada em um arquivo .json continua sendo HTML, não JSON.
Extrair um campo e filtrar um array
Para este arquivo de teste, o serviço possui um nome e uma porta, enquanto cada nó tem seu próprio estado.
{
"service": {"name": "api", "port": 8080},
"nodes": [
{"name": "web-1", "enabled": true},
{"name": "worker-1", "enabled": false}
]
}
A opção -r remove as aspas em torno de uma string. Ela é útil quando o valor deve ser utilizado por outro comando.
jq -r '.service.name' config.json
jq -r '.nodes[] | select(.enabled == true) | .name' config.json
O primeiro comando exibe api. O segundo percorre nodes, mantém os objetos cujo enabled é igual a true, e em seguida exibe apenas seus nomes. O manual oficial do jq descreve esse percurso com .[], os filtros e select().
Fazer o script falhar se o valor estiver ausente
Um script de administração não deve continuar com uma variável vazia. A opção -e fornece um código de retorno utilizável: zero se o último resultado estiver presente e diferente de false ou null, um se o valor for false ou null, quatro se nenhum resultado for produzido.
#!/usr/bin/env bash
set -euo pipefail
fichier="config.json"
jq empty "$fichier"
if port=$(jq -er '.service.port? // empty' "$fichier"); then
printf 'Porta configurada: %sn' "$port"
else
printf 'Porta ausente ou JSON inválidon' >&2
exit 1
fi
Mantenha os filtros jq entre aspas sob Bash. O shell não tentará interpretar $, [] ou | antes do jq. Se o campo puder conter um segredo, evite também exibi-lo com printf nos registros de CI.
Por que grep acaba quebrando
grep busca texto. Ele não distingue uma chave port em service de outra chave com o mesmo nome em um objeto adjacente. A ordem dos campos, os espaços, as quebras de linha e os caracteres escapados também podem mudar sem modificar os dados JSON.
Mantenha grep para um log de texto ou uma busca rápida em um arquivo que você controla. Para uma resposta de API, um arquivo de configuração ou uma exportação, passe pelo jq. Se você precisar primeiro recuperar da API, o guia curl no Linux ajuda a controlar o código HTTP e os cabeçalhos antes de passar a resposta ao jq.
Manter jq em seu lugar na automação
Para um arquivo de configuração ou uma resposta API de tamanho normal, jq ainda é a escolha mais legível. Em um documento muito grande, evite --slurp: essa opção carrega todo o fluxo em um array. O modo --stream existe para processar grandes fluxos, mas impõe um filtro diferente e merece um teste em uma cópia.
Eu também manteria uma cópia antes de modificar JSON no local. Para uma configuração versionada, faça o jq escrever primeiro em um novo arquivo, compare com diff -u, e então substitua o original se o resultado corresponder ao esperado. O mesmo princípio evita surpresas com sed no Linux.
Antes de deixar um valor guiar outro comando, valide o JSON, extraia o campo com -e e verifique sua saída. É mais curto do que um pipeline grep | cut, e, principalmente, o script para quando a estrutura não é mais a esperada.