Interroger la sortie de commande Azure CLIQuery Azure CLI command output

Azure CLI utilise l’argument --query pour exécuter une requête JMESPath sur les résultats des commandes.The Azure CLI uses the --query argument to execute a JMESPath query on the results of commands. 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.JMESPath is a query language for JSON, giving you the ability to select and modify data from CLI output. Les requêtes sont exécutées sur la sortie JSON, avant toute mise en forme de l’affichage.Queries are executed on the JSON output before any display formatting.

L’argument --query est pris en charge par toutes les commandes dans Azure CLI.The --query argument is supported by all commands in the Azure CLI. Cet article explique comment utiliser les fonctionnalités de JMESPath avec une série d’exemples courts et simples.This article covers how to use the features of JMESPath with a series of small, simple examples.

Résultats CLI de liste et de dictionnaireDictionary and list CLI results

Même quand vous utilisez un format de sortie autre que JSON, les résultats de la commande CLI sont tout d’abord traités comme du code JSON pour les requêtes.Even when using an output format other than JSON, CLI command results are first treated as JSON for queries. Les résultats CLI se présentent sous la forme d’un dictionnaire ou d’un tableau JSON.CLI results are either a JSON array or dictionary. 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.Arrays are sequences of objects that can be indexed, and dictionaries are unordered objects accessed with keys. 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.Commands that could return more than one object return an array, and commands that always return only a single object return a dictionary.

Récupérer des propriétés dans un dictionnaireGet properties in a dictionary

En utilisant des résultats de dictionnaire, vous pouvez accéder à des propriétés de niveau supérieur simplement avec la clé.Working with dictionary results, you can access properties from the top level with just the key. Le caractère . (sous-expression) est utilisé pour accéder aux propriétés des dictionnaires imbriqués.The . (subexpression) character is used to access properties of nested dictionaries. Avant d’introduire des requêtes, examinez la sortie non modifiée de la commande az vm show :Before introducing queries, take a look at the unmodified output of the az vm show command:

az vm show -g QueryDemo -n TestVM -o json

La commande génère un dictionnaire.The command will output a dictionary. Certains contenus ont été omis.Some content has been omitted.

{
  "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 :The following command gets the SSH public keys authorized to connect to the VM by adding a query:

az vm show -g QueryDemo -n TestVM --query osProfile.linuxConfiguration.ssh.publicKeys -o json
[
  {
    "keyData": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso",
    "path": "/home/azureuser/.ssh/authorized_keys"
  }
]

Obtenir une seule valeurGet a single value

Voici un cas courant : vous avez besoin obtenir une seule valeur d’une commande CLI, telle qu’un ID de ressource Azure, un nom de ressource, un nom d’utilisateur ou un mot de passe.A common case is that you need to only get one value out of a CLI command, such as an Azure resource ID, a resource name, a username, or a password. Dans ce cas, vous souhaitez également souvent stocker la valeur dans une variable d’environnement locale.In that case, you also often want to store the value in a local environment variable. Pour obtenir une seule propriété, veillez d’abord à obtenir une seule propriété de la requête.To get a single property, first make sure that you're only getting one property out of the query. Modification de l’exemple précédent pour obtenir uniquement le nom d’utilisateur administrateur :Modifying the last example to get only the admin username:

az vm show -g QueryDemo -n TestVM --query 'osProfile.adminUsername' -o json
"azureuser"

Cela ressemble à une seule valeur valide. Toutefois, notez que les caractères " sont retournés dans la sortie.This looks like a valid single value, but note that the " characters are returned as part of the output. Cela indique que l’objet est une chaîne JSON.This indicates that the object is a JSON string. Note importante : lorsque vous affectez cette valeur directement en tant que sortie de la commande vers une variable d’environnement, les guillemets ne peuvent pas être interprétées par l’interpréteur de commandes :It's important to note that when you assign this value directly as output from the command to an environment variable, the quotes may not be interpreted by the shell:

USER=$(az vm show -g QueryDemo -n TestVM --query 'osProfile.adminUsername' -o json)
echo $USER
"azureuser"

Ce n’est probablement pas ce que vous voulez.This is almost certainly not what you want. Dans ce cas, utilisez un format de sortie qui ne place pas les valeurs retournées entre des informations de type.In this case, you want to use an output format which doesn't enclose returned values with type information. La meilleure option de sortie de l’interface CLI à cette fin est tsv (valeurs séparées par une tabulation).The best output option that the CLI offers for this purpose is tsv, tab-separated values. En particulier, quand vous récupérez une valeur qui n’est qu’une seule valeur (pas un dictionnaire ou une liste), vous avez la garantie que la sortie tsv n’est pas entre guillemets.In particular, when retrieving a value that's only a single value (not a dictionary or list), tsv output is guaranteed to be unquoted.

az vm show -g QueryDemo -n TestVM --query 'osProfile.adminUsername' -o tsv
azureuser

Pour plus d’informations sur le format de sortie tsv, consultez Formats de sortie : format de sortie TSVFor more information about the tsv output format, see Output formats - TSV output format

Obtenir plusieurs valeursGet multiple values

Pour récupérer plusieurs propriétés, placez des expressions entre crochets [ ] (une liste à sélection multiple) sous la forme d’une liste séparée par des virgules.To get more than one property, put expressions in square brackets [ ] (a multiselect list) as a comma-separated list. Pour récupérer en une seule fois le nom de la machine virtuelle, l’utilisateur administrateur et la clé SSH, utilisez la commande :To get the VM name, admin user, and SSH key all at once use the command:

az vm show -g QueryDemo -n TestVM --query '[name, osProfile.adminUsername, osProfile.linuxConfiguration.ssh.publicKeys[0].keyData]' -o json
[
  "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.These values are listed in the result array in the order they were given in the query. Étant donné que le résultat est un tableau, aucune clé n’est associée aux résultats.Since the result is an array, there are no keys associated with the results.

Renommer des propriétés dans une requêteRename properties in a query

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).To get a dictionary instead of an array when querying for multiple values, use the { } (multiselect hash) operator. Le format d’un hachage à sélection multiple est {displayName:JMESPathExpression, ...}.The format for a multiselect hash is {displayName:JMESPathExpression, ...}. displayName correspond à la chaîne indiquée dans la sortie, tandis que JMESPathExpression correspond à l’expression JMESPath à évaluer.displayName will be the string shown in output, and JMESPathExpression is the JMESPath expression to evaluate. Modification de l’exemple de la dernière section en remplaçant la liste à sélection multiple par un hachage :Modifying the example from the last section by changing the multiselect list to a hash:

az vm show -g QueryDemo -n TestVM --query '{VMName:name, admin:osProfile.adminUsername, sshKey:osProfile.linuxConfiguration.ssh.publicKeys[0].keyData }' -o json
{
  "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 tableauGet properties in an array

Un tableau n’a aucune propriété propre, mais il peut être indexé.An array has no properties of its own, but it can be indexed. Cette fonctionnalité est illustrée dans le dernier exemple avec l’expression publicKeys[0], qui obtient le premier élément du tableau publicKeys.This feature is shown in the last example with the expression publicKeys[0], which gets the first element of the publicKeys array. Le fait que la sortie CLI soit ordonnée n’est pas garanti ; nous vous conseillons donc 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.There's no guarantee CLI output is ordered, so avoid using indexing unless you're sure of the order or don't care what element you get. Pour accéder aux propriétés des éléments dans un tableau, vous effectuez l’une des deux opérations suivantes : mise à plat et filtrage.To access the properties of elements in an array, you do one of two operations: flattening and filtering. Cette section explique comment aplatir un tableau.This section covers how to flatten an array.

La mise à plat d’un tableau est effectuée avec l’opérateur JMESPath [].Flattening an array is done with the [] JMESPath operator. Toutes les expressions après l’opérateur [] sont appliquées à chaque élément du tableau actuel.All expressions after the [] operator are applied to each element in the current array. Si l’opérateur [] apparaît au début de la requête, il aplatit le résultat de la commande CLI.If [] appears at the start of the query, it flattens the CLI command result. Les résultats de az vm list peuvent être examinés avec cette fonctionnalité.The results of az vm list can be inspected with this feature. Pour récupérer le nom, le système d’exploitation et le nom d’administrateur de chacune des machines virtuelles dans un groupe de ressources :To get the name, OS, and administrator name for each VM in a resource group:

az vm list -g QueryDemo --query '[].{Name:name, OS:storageProfile.osDisk.osType, admin:osProfile.adminUsername}' -o json
[
  {
    "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 :When combined with the --output table output format, the column names match up with the displayKey value of the multiselect hash:

az vm list -g 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

Notes

Certaines clés sont filtrées et non pas imprimées dans l’affichage de table.Certain keys are filtered out and not printed in the table view. Il s’agit des clés id, type et etag.These keys are id, type, and etag. Pour afficher ces valeurs, vous pouvez modifier le nom de clé dans un hachage à sélection multiple.To see these values, you can change the key name in a multiselect hash.

az vm show -g QueryDemo -n TestVM --query "{objectID:id}" -o table

Tous les tableaux peuvent être aplatis, pas seulement le résultat de niveau supérieur renvoyé par la commande.Any array can be flattened, not just the top-level result returned by the command. 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.In the last section, the expression osProfile.linuxConfiguration.ssh.publicKeys[0].keyData was used to get the SSH public key for sign-in. Pour récupérer chaque clé publique SSH, l’expression peut plutôt être écrite sous la forme osProfile.linuxConfiguration.ssh.publicKeys[].keyData.To get every SSH public key, the expression could instead be written as 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 :This query expression flattens the osProfile.linuxConfiguration.ssh.publicKeys array, and then runs the keyData expression on each element:

az vm show -g QueryDemo -n TestVM --query '{VMName:name, admin:osProfile.adminUsername, sshKeys:osProfile.linuxConfiguration.ssh.publicKeys[].keyData }' -o json
{
  "VMName": "TestVM",
  "admin": "azureuser",
  "sshKeys": [
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso\n"
  ]
}

Filtrer des tableauxFilter arrays

Le filtrage est l’autre opération utilisée pour récupérer des données à partir d’un tableau.The other operation used to get data from an array is filtering. Il est effectué avec l’opérateur JMESPath [?...].Filtering is done with the [?...] JMESPath operator. Cet opérateur utilise un prédicat en tant que contenus.This operator takes a predicate as its contents. Un prédicat est une instruction qui peut être évaluée avec les valeurs true ou false.A predicate is any statement that can be evaluated to either true or false. Les expressions dans lesquelles la valeur d’évaluation du prédicat est true sont incluses dans la sortie.Expressions where the predicate evaluates to true are included in the output.

JMESPath propose la comparaison standard et des opérateurs logiques.JMESPath offers the standard comparison and logical operators. Ces derniers comprennent <, <=, >, >=, == et !=.These include <, <=, >, >=, ==, and !=. JMESPath prend également en charge les opérateurs logiques Et (&&), Ou (||) et Non (!).JMESPath also supports logical and (&&), or (||), and not (!). Les expressions peuvent être regroupées dans des parenthèses, ce qui permet d’obtenir des expressions de prédicat plus complexes.Expressions can be grouped within parenthesis, allowing for more complex predicate expressions. Pour plus d’informations sur les prédicats et les opérations logiques, consultez JMESPath Specification (Spécification JMESPath).For the full details on predicates and logical operations, see the JMESPath specification.

Dans la dernière section, nous avons aplati un tableau pour récupérer la liste complète des machines virtuelles dans un groupe de ressources.In the last section, we flattened an array to get the complete list of all VMs in a resource group. Grâce à des filtres, nous pouvons réduire cette sortie pour afficher uniquement les machines virtuelles Linux :Using filters, this output can be restricted to only Linux VMs:

az vm list -g QueryDemo --query "[?storageProfile.osDisk.osType=='Linux'].{Name:name,  admin:osProfile.adminUsername}" --output table
Name    Admin
------  ---------
Test-2  sttramer
TestVM  azureuser

Important

Dans JMESPath, les chaînes sont toujours placées entre des guillemets simples (').In JMESPath, strings are always surrounded by single quotes ('). Si vous utilisez des guillemets doubles comme partie d’une chaîne dans un prédicat de filtre, vous obtiendrez une sortie vide.If you use double quotes as part of a string in a filter predicate, you'll get empty output.

JMESPath dispose également de fonctions intégrées qui peuvent simplifier le filtrage.JMESPath also has built-in functions that can help with filtering. C’est le cas de la fonction contains(string, substring), qui vérifie si une chaîne contient une sous-chaîne.One such function is contains(string, substring), which checks to see if a string contains a substring. Les expressions étant évaluées avant d’appeler la fonction, le premier argument peut être une expression JMESPath complète.Expressions are evaluated before calling the function, so the first argument can be a full JMESPath expression. L’exemple suivant recherche toutes les machines virtuelles utilisant un stockage SSD pour leur disque de système d’exploitation :The next example finds all VMs using SSD storage for their OS disk:

az vm list -g QueryDemo --query "[?contains(storageProfile.osDisk.managedDisk.storageAccountType,'SSD')].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType}" -o json
[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

Cette requête est un peu longue.This query is a little long. La clé storageProfile.osDisk.managedDisk.storageAccountType est mentionnée à deux reprises, puis récréée dans la sortie.The storageProfile.osDisk.managedDisk.storageAccountType key is mentioned twice, and rekeyed in the output. Pour raccourcir ce processus, vous pouvez appliquer le filtre après la mise à plat et la sélection des données.One way to shorten it is to apply the filter after flattening and selecting data.

az vm list -g QueryDemo --query "[].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType}[?contains(Storage,'SSD')]" -o json
[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

Pour les tableaux volumineux, il peut être plus rapide d’appliquer le filtre avant de sélectionner des données.For large arrays, it may be faster to apply the filter before selecting data.

Consultez JMESPath specification - Built-in Functions (Spécification JMESPath - Fonctions intégrées) pour obtenir la liste complète des fonctions.See the JMESPath specification - Built-in Functions for the full list of functions.

Modifier la sortieChange output

Les fonctions JMESPath jouent également un autre rôle, celui d’agir sur les résultats d’une requête.JMESPath functions also have another purpose, which is to operate on the results of a query. Toutes les fonctions qui renvoient une valeur non booléenne modifient le résultat d’une expression.Any function that returns a non-boolean value changes the result of an expression. Par exemple, vous pouvez trier des données par valeur de propriété avec sort_by(array, &sort_expression).For example, you can sort data by a property value with 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.JMESPath uses a special operator, &, for expressions that should be evaluated later as part of a function. L’exemple suivant montre comment trier une liste de machines virtuelles par taille de disque de système d’exploitation :The next example shows how to sort a VM list by OS disk size:

az vm list -g QueryDemo --query "sort_by([].{Name:name, Size:storageProfile.osDisk.diskSizeGb}, &Size)" --output table
Name     Size
-------  ------
TestVM   30
Test-2   32
WinTest  127

Consultez JMESPath specification - Built-in Functions (Spécification JMESPath - Fonctions intégrées) pour obtenir la liste complète des fonctions.See the JMESPath specification - Built-in Functions for the full list of functions.

Essayer des requêtes de façon interactiveExperiment with queries interactively

Pour commencer à expérimenter JMESPath, le package Python JMESPath-terminal propose un environnement interactif permettant d’utiliser des requêtes.To start experimenting with JMESPath, the JMESPath-terminal Python package offers an interactive environment to work with queries. Les données sont transmises en tant qu’entrées, puis les requêtes sont écrites et exécutées dans l’éditeur.Data is piped as input, and then queries are written and run in the editor.

pip install jmespath-terminal
az vm list --output json | jpterm