Dominando a Filtragem de Saída da AWS CLI com JQ: Técnicas Avançadas

A filtragem da saída da AWS CLI fica confusa quando um comando retorna JSON profundamente aninhado. Você pode precisar apenas de um ID de instância, um valor de tag ou um relatório CSV curto, mas comandos como aws ec2 describe-instances retornam muito mais dados do que isso.

A AWS CLI tem uma opção interna --query que usa JMESPath, e geralmente é a ferramenta certa para consultas simples. O jq é útil quando você deseja uma remodelagem JSON mais rica, lógica condicional, saída CSV ou filtros que podem ser reutilizados em scripts de shell.

Comece com Saída JSON

O jq lê JSON, então faça a AWS CLI retornar JSON explicitamente:

aws ec2 describe-instances --output json

Você também pode definir JSON como padrão configurado com aws configure, mas usar --output json em exemplos e scripts torna a dependência óbvia.

Instale o jq com o gerenciador de pacotes do seu sistema se ele ainda não estiver disponível:

sudo apt update && sudo apt install jq

sudo dnf install jq

brew install jq

Leia e Inspecione JSON da AWS

O filtro de identidade, ., retorna o JSON de entrada. É útil quando você deseja uma saída bem formatada enquanto aprende a forma de uma resposta:

aws ec2 describe-instances --output json | jq '.'

Para selecionar uma chave de nível superior, use a notação de ponto:

aws ec2 describe-instances --output json | jq '.Reservations'

A maioria dos comandos da AWS envolve dados úteis em arrays. Para instâncias EC2, a estrutura é Reservations[] seguida por Instances[], então você geralmente precisa de ambos os níveis.

Itere Através de Arrays

Use .[] para emitir cada item de um array. Este comando imprime cada ID de instância EC2 em todas as reservas:

aws ec2 describe-instances --output json | jq '.Reservations[].Instances[].InstanceId'

Por padrão, a saída de string inclui aspas JSON. Adicione -r quando precisar de texto bruto para um loop de shell ou outro comando:

aws ec2 describe-instances --output json | jq -r '.Reservations[].Instances[].InstanceId'

Você também pode construir um objeto menor com apenas os campos que lhe interessam:

aws ec2 describe-instances --output json |
  jq '.Reservations[].Instances[] | {id: .InstanceId, state: .State.Name, type: .InstanceType}'

Isso fornece registros JSON compactos em vez da resposta EC2 completa.

Filtre com select()

Use select() quando quiser apenas registros que correspondam a uma condição. Este exemplo lista IDs de instâncias em execução:

aws ec2 describe-instances --output json |
  jq -r '.Reservations[].Instances[] | select(.State.Name == "running") | .InstanceId'

Literais de string dentro de um filtro jq usam aspas duplas, como "running". Se você envolver todo o programa jq em aspas simples, seu shell passará essas aspas duplas com segurança.

Para uma verificação mais específica, filtre por tipo de instância:

aws ec2 describe-instances --output json |
  jq -r '.Reservations[].Instances[] | select(.InstanceType == "t3.micro") | .InstanceId'

Lide com Campos Opcionais com Segurança

Os recursos da AWS frequentemente omitem campos. Tags são um exemplo comum. Se uma instância não tem array Tags, .Tags[] pode falhar. Use o iterador opcional .Tags[]?:

aws ec2 describe-instances --output json |
  jq '.Reservations[].Instances[] | {id: .InstanceId, name: (.Tags[]? | select(.Key == "Name") | .Value)}'

Isso funciona, mas pode produzir nenhum valor name quando a tag está faltando. Para scripts, um valor padrão geralmente é mais fácil de consumir:

aws ec2 describe-instances --output json |
  jq '.Reservations[].Instances[] | {
    id: .InstanceId,
    name: ((.Tags[]? | select(.Key == "Name") | .Value) // "sem_nome")
  }'

Retorne um Array em Vez de um Fluxo

Muitos filtros jq emitem um fluxo de valores. Se outra ferramenta espera um array JSON válido, envolva a expressão em colchetes:

aws ec2 describe-instances --output json |
  jq '[.Reservations[].Instances[].InstanceId]'

Isso é útil quando você está escrevendo um arquivo JSON para outra etapa de automação.

Exporte CSV ou TSV

Para relatórios amigáveis a planilhas, construa um array de campos e passe para @csv ou @tsv. Use -r para que jq escreva linhas CSV brutas em vez de strings JSON:

aws ec2 describe-instances --output json |
  jq -r '.Reservations[].Instances[] | [.InstanceId, .InstanceType, .State.Name] | @csv'

Para incluir uma linha de cabeçalho, emita-a antes das linhas de dados:

aws ec2 describe-instances --output json |
  jq -r '["instance_id","instance_type","state"], (.Reservations[].Instances[] | [.InstanceId, .InstanceType, .State.Name]) | @csv'

Exemplo Prático: Encontre Elastic IPs Não Anexados

Elastic IPs não anexados podem gerar custos evitáveis. Este comando lista IPs públicos onde a AWS não retornou um AssociationId:

aws ec2 describe-addresses --output json |
  jq -r '.Addresses[] | select(.AssociationId == null) | .PublicIp'

Se imprimir endereços, revise-os antes de liberar:

aws ec2 release-address --allocation-id eipalloc-0123456789abcdef0

Não canalize comandos de liberação diretamente de uma consulta de descoberta até que você tenha verificado os resultados. Uma breve etapa de revisão é mais barata do que se recuperar da exclusão do recurso errado.

Quando Usar --query em Vez

Use --query da AWS CLI para projeções simples porque ele é executado antes da formatação da saída e mantém o comanto autocontido:

aws ec2 describe-instances \
  --query 'Reservations[].Instances[].InstanceId' \
  --output text

Recorra ao jq quando o resultado precisar de mais transformação, como valores de fallback, formatação CSV, combinação de campos ou filtros mais longos que são mais fáceis de ler na sintaxe do jq.

Conclusão

Use --output json como ponto de transferência entre a AWS CLI e o jq. Em seguida, combine .[], select(), construção de objetos, padrões // e saída bruta -r para transformar grandes respostas da AWS nos dados exatos que seu script ou relatório precisa.