Comment interroger une sortie de commande Azure CLI à l’aide d’une requête JMESPath

  • Article

Azure CLI utilise le paramètre --query pour exécuter une requête JMESPath sur les résultats des commandes. JMESPath est un langage de requête pour JSON, qui vous permet de sélectionner et de modifier des données depuis une sortie CLI.

Toutes les commandes dans Azure CLI prennent en charge le paramètre --query. Cet article explique comment utiliser les fonctionnalités de JMESPath et fournit des exemples de requêtes. Découvrez les concepts JMESPath qui sont utiles pour l’interrogation sous l’onglet Concepts. Consultez des exemples de requêtes JMESPath sous l’onglet Exemples.

Azure CLI utilise des requêtes pour sélectionner et modifier la sortie des commandes Azure CLI. Les requêtes sont exécutées côté client sur l’objet JSON retourné par la commande Azure CLI avant toute mise en forme d’affichage.

Les caractères d’échappement nécessaires dans les requêtes diffèrent pour différents environnements. Il est recommandé d’exécuter les requêtes dans Azure Cloud Shell ou cmd, car ces interpréteurs de commandes nécessitent moins de caractères d’échappement. Pour faire en sorte que les exemples de requêtes soient syntaxiquement corrects, sélectionnez l’onglet de l’interpréteur de commandes que vous utilisez.

Résultats CLI de liste et de dictionnaire

Les résultats de la commande CLI sont tout d’abord traités en tant que JSON pour les requêtes, même lorsque le format de sortie n’est pas du JSON. Les résultats CLI se présentent sous la forme d’un dictionnaire ou d’un tableau JSON. Les tableaux sont des séquences d’objets qui peuvent être indexés, et les dictionnaires sont des objets non ordonnés accessibles avec des clés.

Voici un exemple de tableau :

[ 
  1,
  2,
  3
]

Voici un exemple de dictionnaire :

{
  "isRunning": false,
  "time": "12:00",
  "number": 1
}

Les commandes qui peuvent renvoyer plus d’un objet renvoient un tableau, et les commandes qui renvoient toujours et uniquement un seul objet renvoient un dictionnaire.

Récupérer des propriétés dans un dictionnaire

En utilisant des résultats de dictionnaire, vous pouvez accéder à des propriétés de niveau supérieur simplement avec la clé. Le caractère . (sous-expression) est utilisé pour accéder aux propriétés des dictionnaires imbriqués. Avant d’introduire des requêtes, examinez la sortie non modifiée de la commande az vm show :

az vm show --resource-group QueryDemo --name TestVM

La commande génère un dictionnaire. Certains contenus ont été omis.

{
  "additionalCapabilities": null,
  "availabilitySet": null,
  "diagnosticsProfile": {
    "bootDiagnostics": {
      "enabled": true,
      "storageUri": "https://xxxxxx.blob.core.windows.net/"
    }
  },
  ...
  "osProfile": {
    "adminPassword": null,
    "adminUsername": "azureuser",
    "allowExtensionOperations": true,
    "computerName": "TestVM",
    "customData": null,
    "linuxConfiguration": {
      "disablePasswordAuthentication": true,
      "provisionVmAgent": true,
      "ssh": {
        "publicKeys": [
          {
            "keyData": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso",
            "path": "/home/azureuser/.ssh/authorized_keys"
          }
        ]
      }
    },
    "secrets": [],
    "windowsConfiguration": null
  },
  ....
}

La commande suivante récupère les clés publiques SSH autorisées à se connecter à la machine virtuelle en ajoutant une requête :

az vm show --resource-group QueryDemo --name TestVM --query "osProfile.linuxConfiguration.ssh.publicKeys"

[
  {
    "keyData": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso",
    "path": "/home/azureuser/.ssh/authorized_keys"
  }
]

Les chaînes de requête respectent la casse. Par exemple, si vous remplacez « osProfile » par « OsProfile » dans la requête précédente, les résultats retournés sont incorrects.

Obtenir plusieurs valeurs

Pour récupérer plusieurs propriétés, placez des expressions sous la forme d’une liste séparée par des virgules entre crochets [ ] (une liste à sélection multiple). La commande suivante obtient le nom de machine virtuelle, l’utilisateur administrateur et la clé SSH en même temps :

az vm show --resource-group QueryDemo --name TestVM --query "[name, osProfile.adminUsername, osProfile.linuxConfiguration.ssh.publicKeys[0].keyData]"

[
  "TestVM",
  "azureuser",
  "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso"
]

Ces valeurs sont répertoriées dans le tableau des résultats, dans l’ordre où ils ont été donnés dans la requête. Étant donné que le résultat est un tableau, aucune clé n’est associée aux résultats. Pour obtenir un dictionnaire au lieu d’un tableau, consultez la section suivante.

Renommer des propriétés dans une requête

Pour récupérer un dictionnaire à la place d’un tableau lors de l’interrogation de plusieurs valeurs, utilisez l’opérateur { } (code de hachage à sélection multiple). Le format d’un hachage à sélection multiple est {displayName:JMESPathExpression, ...}. displayName correspond à la chaîne indiquée dans la sortie, tandis que JMESPathExpression correspond à l’expression JMESPath à évaluer. Modifiez l’exemple de la dernière section en modifiant la liste à sélection multiple en hachage :

Remarque

Si vous choisissez d’utiliser un espace dans un nouveau nom de colonne, comme VM name au lieu de , les règles de VMNameguillemet changent à la fois dans Bash et PowerShell. Pour obtenir des exemples, consultez Passer des espaces dans les paramètres Azure CLI.

az vm show --resource-group QueryDemo --name TestVM --query "{VMName:name, admin:osProfile.adminUsername, sshKey:osProfile.linuxConfiguration.ssh.publicKeys[0].keyData}"

{
  "VMName": "TestVM",
  "admin": "azureuser",
  "ssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso"
}

Récupérer des propriétés dans un tableau

Un tableau n’a aucune propriété propre, mais il peut être indexé. Cette fonctionnalité est illustrée dans le dernier exemple avec l’expression publicKeys[0], qui obtient le premier élément du tableau publicKeys. Le fait que la sortie CLI soit ordonnée n’étant pas garanti, nous vous conseillons d’éviter d’utiliser l’indexation, sauf si vous êtes certain de l’ordre ou si le type d’élément que vous récupérerez vous importe peu. Pour accéder aux propriétés des éléments dans un tableau, vous effectuez l’une des deux opérations suivantes : mise à plat ou filtrage. Cette section explique comment aplatir un tableau.

La mise à plat d’un tableau est effectuée avec l’opérateur JMESPath []. Toutes les expressions après l’opérateur [] sont appliquées à chaque élément du tableau actuel. Si l’opérateur [] apparaît au début de la requête, il aplatit le résultat de la commande CLI. Les résultats de az vm list peuvent être examinés avec cette fonctionnalité. La requête suivante récupère le nom, le système d’exploitation et le nom d’administrateur de chacune des machines virtuelles dans un groupe de ressources :

az vm list --resource-group QueryDemo --query "[].{Name:name, OS:storageProfile.osDisk.osType, admin:osProfile.adminUsername}"

[
  {
    "Name": "Test-2",
    "OS": "Linux",
    "admin": "sttramer"
  },
  {
    "Name": "TestVM",
    "OS": "Linux",
    "admin": "azureuser"
  },
  {
    "Name": "WinTest",
    "OS": "Windows",
    "admin": "winadmin"
  }
]

Tous les tableaux peuvent être aplatis, pas seulement le résultat de niveau supérieur renvoyé par la commande. Dans la dernière section, l’expression osProfile.linuxConfiguration.ssh.publicKeys[0].keyData a été utilisée pour récupérer la clé publique SSH pour la connexion. Pour récupérer chaque clé publique SSH, l’expression peut plutôt être écrite sous la forme osProfile.linuxConfiguration.ssh.publicKeys[].keyData. Cette expression de requête aplatit le tableau osProfile.linuxConfiguration.ssh.publicKeys, puis exécute l’expression keyData sur chaque élément :

az vm show --resource-group QueryDemo --name TestVM --query "{VMName:name, admin:osProfile.adminUsername, sshKeys:osProfile.linuxConfiguration.ssh.publicKeys[].keyData }"

{
  "VMName": "TestVM",
  "admin": "azureuser",
  "sshKeys": [
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso\n"
  ]
}

Filtrer les tableaux avec des expressions booléennes

Le filtrage est l’autre opération utilisée pour récupérer des données à partir d’un tableau. Il est effectué avec l’opérateur JMESPath [?...]. Cet opérateur utilise un prédicat en tant que contenus. Un prédicat est une instruction (comprenant des propriétés booléennes) qui peut être évaluée à true ou false. Les expressions dans lesquelles la valeur d’évaluation du prédicat est true sont incluses dans la sortie.

La première requête montre comment lister les noms de tous les abonnements Azure connectés à votre compte dont la propriété isDefault a la valeur true. Les deuxième et troisième requêtes montrent deux façons différentes de répertorier tous les abonnements dont la propriété isDefault est définie sur false.

# Boolean values are assumed to be true, so you can directly evaluate the isDefault property to return the default subscription.
az account list --query "[?isDefault].name"

# To check if a Boolean property is false, you can use the comparison operator == or the logical operator !.
az account list --query '[?!isDefault].name'
az account list --query "[?isDefault == \`false\`].name"

JMESPath propose la comparaison standard et des opérateurs logiques. Ces derniers comprennent <, <=, >, >=, == et !=. JMESPath prend également en charge les opérateurs logiques Et (&&), Ou (||) et Non (!). Les expressions peuvent être regroupées dans des parenthèses, ce qui permet d’obtenir des expressions de prédicat plus complexes. Pour plus d’informations sur les prédicats et les opérations logiques, consultez JMESPath Specification (Spécification JMESPath).

Dans la dernière section, vous avez aplati un tableau pour récupérer la liste complète des machines virtuelles dans un groupe de ressources. Grâce à l’utilisation de filtres, cette sortie peut être limitée aux seules machines virtuelles Linux :

az vm list --resource-group QueryDemo --query "[?storageProfile.osDisk.osType=='Linux'].{Name:name,  admin:osProfile.adminUsername}" --output table

Name    Admin
------  ---------
Test-2  sttramer
TestVM  azureuser

Vous pouvez également filtrer les valeurs numériques telles que la taille du disque du système d’exploitation. L’exemple suivant montre comment filtrer la liste des machines virtuelles pour afficher celles dont la taille de disque est supérieure ou égale à 50 Go.

az vm list --resource-group QueryDemo --query "[?storageProfile.osDisk.diskSizeGb >=\`50\`].{Name:name,  admin:osProfile.adminUsername, DiskSize:storageProfile.osDisk.diskSizeGb }" --output table

Name     Admin     DiskSize
-------  --------  --------
WinTest  winadmin  127

Pour les tableaux volumineux, il peut être plus rapide d’appliquer le filtre avant de sélectionner des données.

Important

Dans JMESPath, les chaînes sont toujours placées entre des guillemets simples (') ou des caractères d’échappement (`). Si vous utilisez des guillemets doubles comme partie d’une chaîne dans un prédicat de filtre, vous obtiendrez une sortie vide.

Fonctions JMESPath

JMESPath a également des fonctions intégrées qui permettent d’obtenir des requêtes plus complexes et de modifier la sortie de requête. Cette section se concentre sur l’utilisation de fonctions JMESPath pour créer des requêtes tandis que la section Manipulation de la sortie avec des fonctions montre comment utiliser des fonctions pour modifier la sortie.

Les expressions étant évaluées avant d’appeler la fonction, les arguments eux-mêmes peuvent être des expressions JMESPath. Les exemples suivants illustrent ce concept par l’utilisation de contains(string, substring), qui vérifie si une chaîne contient une sous-chaîne. Cette commande recherche toutes les machines virtuelles utilisant un stockage SSD pour leur disque de système d’exploitation :

az vm list --resource-group QueryDemo --query "[?contains(storageProfile.osDisk.managedDisk.storageAccountType,'SSD')].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType}"

[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

Expressions de canal

Semblable à la façon dont | est utilisé dans la ligne de commande, | peut être utilisé dans des requêtes JMESPath pour appliquer des expressions aux résultats de requête intermédiaires. Nous pouvons également utiliser | pour décomposer les requêtes complexes en sous-expressions plus simples. Pour raccourcir la requête de la section précédente, utilisez | pour appliquer le filtre après l’aplatissement et la sélection des données.

az vm list --resource-group QueryDemo --query "[].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType} | [? contains(Storage,'SSD')]"

[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

Consultez JMESPath specification - Built-in Functions (Spécification JMESPath - Fonctions intégrées) pour obtenir la liste complète des fonctions.

Manipulation de la sortie avec des fonctions

Les fonctions JMESPath jouent également un autre rôle, celui d’agir sur les résultats d’une requête. Les fonctions qui retournent une valeur non booléenne modifient le résultat d’une expression. Par exemple, vous pouvez trier des données par valeur de propriété avec sort_by(array, &sort_expression). JMESPath utilise un opérateur spécial, &, pour les expressions qui doivent être évaluées ultérieurement dans le cadre d’une fonction. L’exemple suivant montre comment trier une liste de machines virtuelles par taille de disque de système d’exploitation :

az vm list --resource-group QueryDemo --query "sort_by([].{Name:name, Size:storageProfile.osDisk.diskSizeGb}, &Size)" --output table

Name     Size
-------  ------
Test-2   30
TestVM   32
WinTest  127

Consultez JMESPath specification - Built-in Functions (Spécification JMESPath - Fonctions intégrées) pour obtenir la liste complète des fonctions.

Mise en forme des résultats de requête

Azure CLI utilise JSON comme format de sortie par défaut, mais différents formats de sortie peuvent mieux correspondre à une requête en fonction de son objectif et de ses résultats. Les requêtes sont toujours exécutées sur la sortie JSON dans un premier temps avant d’être mises en forme.

Cette section traite de la mise en forme de tsv et table à et de certains cas d’usage pour chaque format. Pour en savoir plus sur les formats de sortie, consultez l’article Formats de sortie pour les commandes Azure CLI.

Format de sortie TSV

Le format de sortie tsv retourne des valeurs séparées par des tabulations et des sauts de ligne sans mise en forme, clés ou autres symboles supplémentaires. Ce format est utile lorsque la sortie est stockée dans un paramètre et utilisée dans une autre commande.

Un cas d’usage pour la mise en forme tsv est des requêtes qui récupèrent une valeur hors d’une commande CLI, telle qu’un ID de ressource Azure ou un nom de ressource, et stockent la valeur dans une variable d’environnement locale. Par défaut, les résultats sont retournés au format JSON, ce qui peut être un problème lorsque des caractères " se situent de part et d’autre des chaînes JSON. Les guillemets peuvent ne pas être interprétés par l’interpréteur de commandes si la sortie de commande est directement affectée à la variable d’environnement. Ce problème est visible dans l’exemple suivant qui affecte un résultat de requête à une variable d’environnement :

USER=$(az vm show --resource-group QueryDemo --name TestVM --query "osProfile.adminUsername")
echo $USER

"azureuser"

Utilisez la mise en forme tsv, comme illustré dans la requête suivante, pour éviter d’inclure des valeurs de retour avec des informations de type :

USER=$(az vm show --resource-group QueryDemo --name TestVM --query "osProfile.adminUsername" --output tsv)
echo $USER

azureuser

Format de sortie de la table

Le format table imprime la sortie sous forme de tableau ASCII, ce qui la rend facile à lire et à analyser. Certains champs ne sont pas compris dans le tableau. Ainsi, ce format est le plus approprié pour obtenir un aperçu des données rapide et consultable pour un être humain. Les champs qui ne sont pas inclus dans la table peuvent toujours être filtrés dans le cadre d’une requête.

Remarque

Certaines clés sont filtrées et non pas imprimées dans l’affichage de table. Il s’agit des clés id, type et etag. Pour afficher ces valeurs, vous pouvez modifier le nom de clé dans un hachage à sélection multiple.

az vm show --resource-group QueryDemo --name TestVM --query "{objectID:id}" --output table

Nous pouvons utiliser une requête précédente pour illustrer ce concept. La requête d’origine a retourné un objet JSON contenant le nom, le système d’exploitation et le nom administrateur de chaque machine virtuelle du groupe de ressources :

az vm list --resource-group QueryDemo --query "[].{Name:name, OS:storageProfile.osDisk.osType, admin:osProfile.adminUsername}"

[
  {
    "Name": "Test-2",
    "OS": "Linux",
    "admin": "sttramer"
  },
  {
    "Name": "TestVM",
    "OS": "Linux",
    "admin": "azureuser"
  },
  {
    "Name": "WinTest",
    "OS": "Windows",
    "admin": "winadmin"
  }
]

Combinés avec le format de sortie --output table, les noms de colonne correspondent à la valeur displayKey du hachage à sélection multiple, ce qui permet de parcourir plus facilement les informations :

az vm list --resource-group QueryDemo --query "[].{Name:name, OS:storageProfile.osDisk.osType, Admin:osProfile.adminUsername}" --output table

Name     OS       Admin
-------  -------  ---------
Test-2   Linux    sttramer
TestVM   Linux    azureuser
WinTest  Windows  winadmin

Étapes suivantes

Pour en savoir plus sur les requêtes JMESPath, consultez le Tutoriel sur JMESPath.

Pour en savoir plus sur d’autres concepts Azure CLI mentionnés dans cet article, consultez les ressources suivantes :