Transforme JSON e torne-o legível com jq

JavaScript Object Notation (JSON) é um dos formatos de dados mais populares do mundo. Tem amplo suporte e uma especificação simples. É fácil trabalhar com muitas linguagens de programação, especialmente aquelas voltadas para o desenvolvimento web.

Mas a inspeção manual dos dados JSON continua estranha. Embora seja um formato de texto legível, um conjunto de dados JSON pode conter grandes quantidades de dados. As fontes nem sempre formatam JSON em um formato fácil de ler.

javaA ferramenta jq permite aos usuários formatar, filtrar e transformar dados JSON.

O que é jq?

Como é uma ferramenta de linha de comando, você geralmente usará jq digitando comandos em um terminal. Há também um excelente playground online disponível, que abordaremos com mais detalhes abaixo.

A operação normal gira em torno de filtros e a aplicação de um filtro a algum JSON de entrada. Você pode usar jq para buscar um único item de um conjunto de muitos. Ou você pode remover certos campos de cada item em um conjunto, simplificando os dados. Você pode até executar operações complexas para traduzir a entrada em uma forma diferente.

Como fazer o download e instalar o jq

O programa jq não possui dependências externas, o que significa que é muito fácil de começar. Comece baixando um binário executável para Linux, macOS ou Windows por meio do botão na página inicial do jq . Depois de fazer o download do programa, você pode executá-lo diretamente da linha de comando. Você pode querer renomeá-lo ( mv jq-osx-amd64 jq ) por conveniência e pode precisar torná-lo executável ( chmod + x jq ).

Confirme se você pode executar jq executando-o a partir da linha de comando sem argumentos:

 $ ./jq

Você deve ver algumas informações gerais de uso, começando com um resumo simples de uma linha, como o seguinte:

 jq - commandline JSON processor [version 1.6]

Se você tem dificuldade com a abordagem acima, existem alternativas. O software jq tem suporte para gerenciadores de pacotes comuns e você sempre pode experimentar o sandbox online enquanto isso.

Uso básico de jq

O uso padrão é:

 jq [options] <jq filter> [file...]

Então, por exemplo:

 $ jq '.' data.json

Você também pode canalizar a entrada por meio de outro comando, como:

 $ echo '{"name":"john"}' | jq '.'
 {
 "name": "john"
 }

Isso é mais útil quando, por exemplo, o primeiro comando é algo como uma chamada para curl, que pode buscar dados JSON de um serviço da web.

O filtro mostrado nestes exemplos é o mais simples possível ,. (um ponto final) , que imprime a entrada de forma aprimorada. Isso já é bastante útil, mas os filtros do jq fornecem muito mais poder do que isso.

Como aplicar filtros básicos a JSON usando jq

Um filtro jq é um pouco como um seletor CSS ou uma expressão XPATH. É uma longa expressão composta de partes menores. Um filtro completo pode parecer complicado, mas depois de aprender o básico, cada parte deve ser compreensível.

Trabalhando com objetos

Você pode buscar o valor de uma propriedade de objeto usando a sintaxe .property :

 $ echo '{"name":"john"}' | jq '.name'
 "john"

Isso pode ser encadeado para acessar estruturas aninhadas profundas:

 $ echo '{"name":{"first":"john","last":"smith"}}' | jq '.name.last'
 "smith"

Trabalho com matrizes

A operação de matriz mais simples retorna um elemento por meio de seu índice:

 $ echo '[1,2,3]' | jq '.[2]'
 3

Observe que, como acontece com a maioria das linguagens de programação, matrizes de índices jq começando na posição 0. Você também pode dividir uma subarray usando esta sintaxe:

 $ echo '[1,2,3]' | jq '.[1:3]'
 [
 2,
 3
 ]

Sem um índice entre colchetes, jq transforma um único valor de matriz em seu próprio conteúdo, como vários valores:

 $ echo '[1,2,3]' | jq '.[]'
 1
 2
 3

Este é um método importante para encadear filtros, que mostraremos mais tarde.

Recursos mais avançados

Você só pode obter um entendimento completo do poder do jq lendo o manual do jq . Na verdade, o suporte do jq para operadores, variáveis ​​e até funções definidas pelo usuário o torna capaz de agir como qualquer linguagem de programação.

Esses recursos tornam o uso avançado possível, embora complicado. Mas o jq tem alguns recursos integrados, como funções e operadores, que beneficiam até mesmo tarefas simples. Aqui está um exemplo:

 $ echo '[2,4,8]' | jq 'add / length'
 4.666666666666667

Este filtro alimenta a entrada nas funções add e length , dividindo os resultados. Em operação, ele calcula a média de uma matriz de números.

O operador de divisão também pode atuar em strings para dividi-las com base em um separador:

 $ echo '"Just testing"' | jq '. / " "'
 [
 "Just",
 "testing"
 ]

A função select filtra uma matriz, mantendo apenas os itens que passam por uma determinada restrição:

 $ echo '[2,4,8]' | jq '.[] | select(. >= 3)'
 4
 8

Observe que este também é um exemplo do operador de pipe de jq ( | ), que é como um pipe de shell. Ele alimenta o resultado de seu filtro do lado esquerdo como a entrada para o filtro do lado direito.

A função de mapa é muito útil ao trabalhar com matrizes. Ele realiza uma operação em cada elemento da matriz em vez de toda a matriz em si:

 $ echo '[1,2,3]' | jq 'map(.+1)'
 [
 2,
 3,
 4
 ]

Você frequentemente o usará em conjunto com select, por exemplo

 $ echo '[2,4,8]' | jq 'map(select(. >= 3))'
 [
 4,
 8
 ]

Juntando tudo: um exemplo prático de jq

Como o jq processa qualquer JSON válido canalizado para ele, você pode enviar a saída do comando curl . Isso permite que você busque JSON de um URL e o processe imediatamente na linha de comando:

O feed JSON é uma alternativa JSON aos formatos RSS e Atom. O site NPR é um exemplo que suporta feed JSON, mas é difícil de visualizar da fonte e contém muitos dados:

De imediato, você pode ver como é muito mais fácil ler, buscando esses dados e canalizando-os por meio do jq:

 $ curl -s https://feeds.npr.org/1019/feed.json | jq '.'

Aqui está um exemplo mais completo de um filtro que busca a id, o título e a data de cada história que o site publicou em uma terça-feira.

 $ curl -s https://feeds.npr.org/1019/feed.json |
 jq '.items | .[] |
 select(
 .date_published |
 .[0:19] + "Z" |
 fromdate |
 strftime("%a") == "Tue"
 ) |
 {id: .id, title:.title, date:.date_published}'

Depois de selecionar a propriedade de itens , este filtro usa . [] Para iterar sobre cada item. A maior parte do filtro usa a função select para manter apenas as postagens com um valor date_published cujo dia da semana ( strftime ("% a") ) seja terça . A função strftime requer uma data formatada muito especificamente que o filtro . [0:19] + "Z" constrói.

Após selecionar os itens desejados, o filtro final constrói um objeto para cada um com os campos obrigatórios. Observe que cada vez que o feed muda, os resultados serão diferentes. Aqui está um exemplo tirado no momento da publicação:

 {
 "id": "959667930",
 "title": "Deplatforming: Not A First Amendment Issue, But Still A Tough Call For Big Tech",
 "date": "2021-01-26T17:00:00-05:00"
 }
 {
 "id": "960679189",
 "title": "My Pillow CEO Mike Lindell Permanently Suspended From Twitter",
 "date": "2021-01-26T10:17:15-05:00"
 }
 {
 "id": "960220477",
 "title": "Is Your 401(k) Colluding To Make Cereal More Expensive?",
 "date": "2021-01-26T06:31:24-05:00"
 }

Consulte também: Análise JSON Python: um guia simples

Como processar JSON online usando jqplay

Se você quiser experimentar o jq antes de baixá-lo, o jqplay é o lugar perfeito para começar. Por meio de uma interface simples, o site permite que você insira um JSON de amostra e um filtro e, em seguida, visualize o resultado.

Também permite que você experimente algumas opções diferentes. Isso inclui –compact-output (para remover os espaços em branco) e –null-input (para mostrar o resultado na entrada ausente).

A interface também inclui uma seção de cheatsheet muito útil. Aqui está uma captura de tela do longo exemplo anterior :

Observe que, como acontece com esse link, você também pode compartilhar exemplos por meio de um URL.

Use jq para ler e manipular dados JSON

Você pode encontrar informações completas sobre o jq no tutorial e no manual, ambos disponíveis no site do jq. O próprio programa oferece uma quantidade limitada de ajuda por meio da opção –help .

Se você deseja realizar filtros e transformações básicas ou ler um grande pedaço de JSON, jq é uma ferramenta valiosa.