Come eseguire query sull'output dei comandi dell'interfaccia della riga di comando di Azure usando una query JMESPath

  • Articolo

L'interfaccia della riga di comando di Azure usa il --query parametro per eseguire una query JMESPath sui risultati dei comandi. JMESPath è un linguaggio di query per JSON che offre la possibilità di selezionare e modificare i dati dell'output dell'interfaccia della riga di comando.

Tutti i comandi nell'interfaccia della riga di comando di Azure supportano il --query parametro . Questo articolo illustra come usare le funzionalità di JMESPath e fornisce esempi di query. Informazioni sui concetti di JMESPath utili per l'esecuzione di query nella scheda Concetti. Vedere esempi di query JMESPath nella scheda degli esempi.

L'interfaccia della riga di comando di Azure usa query per selezionare e modificare l'output dei comandi dell'interfaccia della riga di comando di Azure. Le query vengono eseguite sul lato client nell'oggetto JSON restituito dal comando dell'interfaccia della riga di comando di Azure prima di qualsiasi formattazione di visualizzazione.

I caratteri di escape necessari nelle query variano per ambienti diversi. È consigliabile eseguire query in Azure Cloud Shell o cmd perché queste shell richiedono un minor numero di caratteri di escape. Per assicurarsi che gli esempi di query siano sintatticamente corretti, selezionare la scheda per la shell in uso.

Risultati dell'interfaccia della riga di comando di tipo dizionario ed elenco

I risultati dei comandi dell'interfaccia della riga di comando vengono prima trattati come JSON per le query, anche quando il formato di output è diverso da JSON. L'interfaccia della riga di comando restituisce risultati sotto forma di matrice o di dizionario JSON. Le matrici sono sequenze di oggetti che possono essere indicizzati e i dizionari sono oggetti non ordinati accessibili tramite chiavi.

Di seguito è riportato un esempio di matrice:

[ 
  1,
  2,
  3
]

Di seguito è riportato un esempio di dizionario:

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

I comandi che potrebbero restituire più di un oggetto restituiscono una matrice e i comandi che restituiscono sempresolo un singolo oggetto restituiscono un dizionario.

Ottenere le proprietà in un dizionario

Usando i risultati dei dizionari è possibile accedere alle proprietà dal livello principale semplicemente mediante la chiave. Il carattere . (sottoespressione) viene usato per accedere alle proprietà dei dizionari annidati. Prima di introdurre query, esaminare l'output non modificato del comando az vm show :

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

Il comando restituisce un dizionario. Alcuni contenuti sono stati omessi.

{
  "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
  },
  ....
}

Il comando seguente ottiene le chiavi pubbliche SSH autorizzate alla connessione alla VM mediante l'aggiunta di una query:

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"
  }
]

Le stringhe di query fanno distinzione tra maiuscole e minuscole. Ad esempio, la modifica di 'osProfile' in 'OsProfile' nella query precedente non restituisce i risultati corretti.

Ottenere più valori

Per ottenere più proprietà, inserire espressioni separate da virgole tra parentesi quadre [ ] (un elenco a selezione multipla). Il comando seguente ottiene il nome della macchina virtuale, l'utente amministratore e la chiave SSH contemporaneamente:

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"
]

Questi valori vengono elencati nella matrice di risultati in base all'ordine in cui sono stati specificati nella query. Poiché il risultato è una matrice, non sono presenti chiavi associate ai risultati. Per ottenere un dizionario anziché una matrice, vedere la sezione successiva.

Rinominare le proprietà in una query

Per ottenere un dizionario invece di una matrice durante l'esecuzione di query per più valori, usare l'operatore { } (hash a selezione multipla). Il formato di un hash a selezione multipla è {displayName:JMESPathExpression, ...}. displayName è la stringa visualizzata nell'output ed JMESPathExpression è l'espressione JMESPath da valutare. Modificare l'esempio dall'ultima sezione modificando l'elenco a selezione multipla in un hash:

Nota

Se si sceglie di usare uno spazio in un nuovo nome di colonna, ad esempio VM name invece di VMName, le regole di virgolette cambiano sia in Bash che in PowerShell. Per esempi, vedere Passare spazi nei parametri dell'interfaccia della riga di comando di Azure.

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"
}

Ottenere le proprietà in una matrice

Una matrice non ha proprietà specifiche, ma può essere indicizzata. Questa funzionalità è illustrata nell'ultimo esempio con l'espressione publicKeys[0], che ottiene il primo elemento della matrice publicKeys. Non esiste alcuna garanzia che l'output dell'interfaccia della riga di comando venga ordinato, quindi evitare di usare l'indicizzazione, a meno che non si sia certi dell'ordine o non sia importante quale elemento si ottiene. Per accedere alle proprietà degli elementi in una matrice, eseguire una delle due operazioni seguenti: appiattimento o filtro. Questa sezione illustra la procedura per rendere flat una matrice.

Per rendere flat una matrice è necessario usare l'operatore [] di JMESPath. Tutte le espressioni dopo l'operatore [] vengono applicate a ogni elemento nella matrice corrente. Se [] viene visualizzato all'inizio della query, il risultato dei comandi dell'interfaccia della riga di comando viene reso flat. I risultati di az vm list possono essere esaminati con questa funzionalità. La query seguente ottiene il nome, il sistema operativo e il nome dell'amministratore per ogni macchina virtuale in un gruppo di risorse:

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"
  }
]

È possibile rendere flat qualsiasi matrice, non solo il risultato principale restituito dal comando. Nell'ultima sezione l'espressione osProfile.linuxConfiguration.ssh.publicKeys[0].keyData è stata usata per ottenere la chiave pubblica SSH per l'accesso. Per ottenere ogni chiave pubblica SSH, l'espressione può essere scritta come osProfile.linuxConfiguration.ssh.publicKeys[].keyData. Questa espressione di query rende flat la matrice osProfile.linuxConfiguration.ssh.publicKeys e quindi esegue l'espressione keyData in ogni elemento:

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"
  ]
}

Filtrare le matrici con espressioni booleane

L'altra operazione usata per ottenere dati da una matrice è l'applicazione di filtri. L'applicazione di filtri viene eseguita con l'operatore [?...] di JMESPath. Questo operatore accetta un predicato come contenuto. Un predicato è qualsiasi istruzione (incluse le proprietà booleane) che possono essere valutate in true o false. Le espressioni in cui il predicato restituisce true vengono incluse nell'output.

La prima query illustra come elencare i nomi di tutte le sottoscrizioni di Azure connesse all'account la cui isDefault proprietà è true. La seconda e la terza query mostrano due modi diversi per elencare tutte le sottoscrizioni la cui isDefault proprietà è 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 offre gli operatori di confronto e logici standard, che includono <, <=, >, >=, == e !=. JMESPath supporta anche operatori logici e (&&) oppure (||), ma non (!). Le espressioni possono essere raggruppate entro parentesi, consentendo di creare espressioni del predicato più complesse. Per dettagli completi sui predicati e sulle operazioni logiche, vedere la specifica di JMESPath.

Nell'ultima sezione è stata appiattita una matrice per ottenere l'elenco completo di tutte le macchine virtuali in un gruppo di risorse. Con l'uso dei filtri, questo output può essere limitato solo alle macchine virtuali 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

È anche possibile filtrare i valori numerici, ad esempio le dimensioni del disco del sistema operativo. Nell'esempio seguente viene illustrato come filtrare l'elenco di macchine virtuali per visualizzare quelle con dimensioni del disco maggiori o uguali a 50 GB.

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

Per le matrici di grandi dimensioni, potrebbe risultare più veloce applicare il filtro prima di selezionare i dati.

Importante

In JMESPath le stringhe sono sempre racchiuse tra virgolette singole (') o caratteri di escape (`). Se si usano le virgolette doppie come parte di una stringa in un predicato di filtro, si otterrà un output vuoto.

Funzioni JMESPath

JMESPath include anche funzioni predefinite che consentono query più complesse e di modificare l'output delle query. Questa sezione è incentrata sull'uso delle funzioni JMESPath per creare query mentre la sezione Modifica dell'output con funzioni illustra come usare le funzioni per modificare l'output.

Le espressioni vengono valutate prima di chiamare la funzione, quindi gli argomenti stessi possono essere espressioni JMESPath. Negli esempi seguenti viene illustrato questo concetto usando contains(string, substring), che verifica se una stringa contiene una sottostringa. Questo comando trova tutte le macchine virtuali che usano l'archiviazione SSD per il disco del sistema operativo:

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"
  }
]

Espressioni pipe

Analogamente a come | viene usato nella riga di comando, | è possibile usare nelle query JMESPath per applicare espressioni ai risultati intermedi delle query. È anche possibile usare | per suddividere query complesse in sottoespressioni più semplici. Per abbreviare la query dalla sezione precedente, usare | per applicare il filtro dopo l'appiattimento e la selezione dei dati.

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"
  }
]

Per l'elenco completo delle funzioni, vedere JMESPath specification - Built-in Functions (Specifica JMESPath - Funzioni predefinite).

Modifica dell'output con le funzioni

Le funzioni JMESPath hanno anche un'altra finalità, ovvero eseguire operazioni sui risultati di una query. Qualsiasi funzione che restituisce un valore nonbooleano modifica il risultato di un'espressione. È ad esempio possibile ordinare i dati in base al valore di una proprietà con sort_by(array, &sort_expression). JMESPath usa un operatore speciale, &, per espressioni che devono essere valutate successivamente come parte di una funzione. L'esempio seguente mostra come ordinare un elenco di VM in base a dimensioni del disco del sistema operativo:

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

Per l'elenco completo delle funzioni, vedere JMESPath specification - Built-in Functions (Specifica JMESPath - Funzioni predefinite).

Formattazione dei risultati delle query

L'interfaccia della riga di comando di Azure usa JSON come formato di output predefinito, ma i diversi formati di output possono essere più adatti a una query a seconda dello scopo e dei risultati. Le query vengono sempre eseguite sull'output JSON e quindi formattate.

Questa sezione passerà alla tsv formattazione e table ad alcuni casi d'uso per ogni formato. Per altre informazioni sui formati di output, vedere Formati di output per i comandi dell'interfaccia della riga di comando di Azure.

Formato TSV dell'output

Il tsv formato di output restituisce valori separati da tabulazione e nuova riga senza formattazione aggiuntiva, chiavi o altri simboli. Questo formato è utile quando l'output viene archiviato in un parametro e usato in un altro comando.

Un caso d'uso per tsv la formattazione è costituito dalle query che recuperano un valore da un comando dell'interfaccia della riga di comando, ad esempio un ID risorsa di Azure o un nome di risorsa, e archiviano il valore in una variabile di ambiente locale. Per impostazione predefinita, i risultati vengono restituiti in formato JSON, che può essere un problema quando si gestiscono stringhe JSON racchiuse tra " caratteri. Le virgolette potrebbero non essere interpretate dalla shell se l'output del comando viene assegnato direttamente alla variabile di ambiente. Questo problema viene visualizzato nell'esempio seguente che assegna un risultato di query a una variabile di ambiente:

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

"azureuser"

Usare tsv la formattazione, come illustrato nella query seguente, per evitare di racchiudere i valori restituiti con informazioni sul tipo:

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

azureuser

Formato dell'output della tabella

Il formato table stampa l'output come tabella ASCII, facilitando la lettura e l'analisi. Non tutti i campi sono inclusi nella tabella, quindi questo formato viene usato meglio come panoramica dei dati ricercabile dall'utente. I campi non inclusi nella tabella possono comunque essere filtrati come parte di una query.

Nota

Determinate chiavi vengono escluse tramite filtro e non vengono stampate nella visualizzazione della tabella. Si tratta delle chiavi id, type e etag. Per visualizzare questi valori è possibile modificare il nome della chiave in un hash a selezione multipla.

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

È possibile usare una query precedente per illustrare questo concetto. La query originale ha restituito un oggetto JSON contenente il nome, il sistema operativo e il nome dell'amministratore per ogni macchina virtuale nel gruppo di risorse:

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"
  }
]

In combinazione con il --output table formato di output, i nomi delle colonne corrispondono al displayKey valore dell'hash a selezione multipla, semplificando lo skiming delle informazioni:

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

Passaggi successivi

Per altre informazioni sulle query JMESPath, vedere Esercitazione su JMESPath.

Per altre informazioni sugli altri concetti dell'interfaccia della riga di comando di Azure indicati in questo articolo, vedere: