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.
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 1) :
curl https://jsonplaceholder.typicode.com/users?_limit=2 | jq '.[] | "\(.name) \(.address.city)"'
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"
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'
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