JSON Query (jq)

console

Cette commande est utilisée en ligne de commande pour mettre en forme du code JSON et n'afficher qu'une partie des enregistrements et/ou attributs.
Elle est particulièrement intéressante avec la commande cUrl lors d'exécution de tests en ligne de commande pour par exemple questionner une base de données, notamment via une API REST

Installer avec les droits d'administration le paquet jq

sudo apt install jq

Utilisation sans options.

jq fichier.json

ou en utilisant les pipes pour les commandes produisant du JSON :

curl https://jsonplaceholder.typicode.com/users?_limit=2 | jq # curl va rendre du JSON que JQ va manipuler

On peut aussi ne récupérer qu'un attribut (dans le cas où seule une liste sans clé supérieure est retournée, sinon reportez-vous à l'exemple concret plus pas) :

jq '.[] | .mon_attribut' fichier.json

Et on peut ne prendre que certains enregistrements, par exemple, si vous avez 10 enregistrements, pour voir les données que du 3^ème et 4^ème :

jq '.[3:5]' fichier.json

ou des deux derniers :

jq '.[-2:]' fichier.json

si le résultat attendu ne comporte plus qu’une chaîne de caractère, l’option –raw-output (ou -r) permet de supprimer les guillemets autour :

curl https://jsonplaceholder.typicode.com/users?_limit=1 | jq -r '.[] | "\(.name)"'

ce qui peut-être utile si on récupère cette chaîne dans la variable d’un script bash

#!/bin/bash
nom_depuis_api=$(curl https://jsonplaceholder.typicode.com/users?_limit=1 | jq -r '.[] | "\(.name)"')

Les tests utilisent l'outil en ligne de commande curl pour récupérer une réponse HTTP contenant du JSON à manipuler par JQ.

avec le serveur de test JSONPlaceholder

Pour réaliser des tests, si vous ne disposer pas de serveur REST, vous pouvez utiliser le serveur JSONPlaceholder qui propose de fausses données juste pour test,
ci-dessous récupération de 2 utilisateur (remarquer l'option _limit=2 pour limiter le nombre de retour) :

curl https://jsonplaceholder.typicode.com/users?_limit=2 | jq

et si on ne souhaite ne récupérer que le nom auquel on concatène la ville ¹⁾ :

curl https://jsonplaceholder.typicode.com/users?_limit=2 | jq '.[] | "\(.name) \(.address.city)"'

avec le serveur Etalab

Pour extraire, à partir de l'API REST d'Etalab, le nom d'une rue lyonnaise à partir de la chaîne professeur (et du code postal 69007), et ne récupérer que le premier retour (au cas où il y en aurait plusieurs)

curl "https://api-adresse.data.gouv.fr/search/?q=professeur&postcode=69007&limit=3" | jq '.features[0].properties.name'
# retourne :
"Rue Professeur Grignard"

avec un serveur elasticsearch exécuter sur votre poste/serveur

Autre exemple avec elasticsearch en reprenant l'exemple autour des movies :

curl "localhost:9200/_search" -X GET -H "Content-Type: application/json" -d '{"query":{"match_all": {}}}' \
 | jq '.hits.hits[] | ._source.movies.title'

avec gitlab

Récupération d'informations sur les tickets d'un projet Gitlab :

curl --header "PRIVATE-TOKEN:012-abc-345-def" "https://gitlab.com/api/v4/projects/380/issues?page=1" | jq '.[] | "\(.iid):\(.state):\(.title):\(.labels)"'

Il faut au préalable définir le token d'accès à l'API dans le projet à mettre à la place de 012-abc-345-def
récupérer le n° du projet (380 dans l'exemple ci-dessus)

Source : https://dev-tips.com/tools/using-jq-to-filter-json-output