Cómo consultar la salida de un comando de la CLI de Azure mediante una consulta JMESPath.

  • Artículo

La CLI de Azure utiliza el parámetro --query para ejecutar una consulta JMESPath sobre los resultados de determinados comandos. JMESPath es un lenguaje de consulta para JSON que ofrece la posibilidad de seleccionar y modificar datos de la salida de la CLI.

Todos los comandos de Interfaz de la línea de comandos de Azure admiten el parámetro --query. En este artículo se explica cómo usar las características de JMESPath y se proporcionan ejemplos de consultas. Obtenga más información sobre conceptos de JMESPath que le serán útiles para realizar consultas en la pestaña Conceptos. Para obtener ejemplos de consultas de JMESPath, consulte la pestaña Ejemplos.

La CLI de Azure usa consultas para seleccionar y modificar la salida de los comandos de la CLI de Azure. Las consultas se ejecutan en el lado cliente, en el objeto JSON que devuelve el comando de la CLI de Azure, antes de que ocurra cualquier formato de presentación.

Los caracteres de escape necesarios en las consultas difieren en función del entorno. Es recomendable ejecutar las consultas en Azure CloudShell o Cmd, ya que estos shells requieren menos caracteres de escape. Para asegurarse de que los ejemplos de consulta son sintácticamente correctos, seleccione la pestaña del shell que está usando.

Diccionario y lista de resultados de la CLI

Los resultados de los comandos de la CLI se tratan primero como JSON para las consultas, incluso cuando se utiliza un formato de salida distinto de JSON. Los resultados de CLI son una matriz JSON o un diccionario. Las matrices son secuencias de objetos que se pueden indexar y los diccionarios son objetos desordenados a los que se accede con claves.

Este es un ejemplo de una matriz:

[ 
  1,
  2,
  3
]

Este es un ejemplo de un diccionario:

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

Los comandos que puedendevolver más de un objeto devuelven una matriz y los comandos que siempre devuelven únicamente un solo objeto devuelven un diccionario.

Obtención de propiedades en un diccionario

Al trabajar con los resultados del diccionario, puede acceder a las propiedades del nivel superior con solo la clave. El carácter . (subexpresión) se utiliza para acceder a las propiedades de los diccionarios anidados. Antes de introducir las consultas, compruebe la salida no modificada del comando az vm show:

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

El comando genera un diccionario. Se ha omitido parte del contenido.

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

El siguiente comando obtiene las claves públicas SSH autorizadas para conectarse a la máquina virtual mediante la adición de una consulta:

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

Las cadenas de consulta distinguen mayúsculas de minúsculas. Por ejemplo, si en la consulta anterior se cambia el valor "osProfile" por "OsProfile", no se devuelve los resultados correctos.

Obtener varios valores

Para obtener más de una propiedad, coloque las expresiones entre corchetes y separadas por comas [ ] (una lista de selección múltiple). El siguiente comando obtiene el nombre de la VM, el usuario administrador y la clave SSH de una sola vez:

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

Estos valores se muestran en la matriz de resultados en el orden en que se proporcionaron en la consulta. Dado que el resultado es una matriz, no hay claves asociadas a los resultados. Para obtener un diccionario en lugar de una matriz, consulte la siguiente sección.

Cambio del nombre de las propiedades en una consulta

Para obtener un diccionario en lugar de una matriz al consultar valores múltiples, utilice el operador { } (hash de selección múltiple). El formato de un hash de selección múltiple es {displayName:JMESPathExpression, ...}. displayName es la cadena que se muestra en la salida y JMESPathExpression es la expresión JMESPath que se va a evaluar. Modifique el ejemplo de la última sección cambiando la lista de selección múltiple a un hash:

Nota:

Si decide usar un espacio en un nuevo nombre de columna, como VM name en lugar de VMName, las reglas de comillas cambian tanto en Bash como en PowerShell. Consulte Paso de espacios en parámetros de la CLI de Azure para obtener ejemplos.

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

Obtención de propiedades en una matriz

Una matriz no tiene propiedades propias, pero se puede indexar. Esta característica se muestra en el último ejemplo con la expresión publicKeys[0], que obtiene el primer elemento de la matriz publicKeys. No existe garantía de que la salida de la CLI esté ordenada, así que evite utilizar la indexación a menos que esté seguro del orden o no le importe qué elemento vaya a obtener. Para acceder a las propiedades de los elementos de una matriz, se realiza una de las siguientes operaciones: simplificación o filtrado. En esta sección se explica cómo simplificar una matriz.

La simplificación de una matriz se realiza con el operador de JMESPath []. Todas las expresiones después del operador [] se aplican a cada elemento de la matriz actual. Si [] aparece al principio de la consulta, aplana el resultado del comando de la CLI. Los resultados de az vm list pueden inspeccionarse con esta característica. Para obtener el nombre, el sistema operativo y el nombre del administrador de cada VM de un grupo de recursos, use la siguiente consulta:

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

Se puede simplificar cualquier matriz, no solo el resultado de nivel superior devuelto por el comando. En la última sección, se utilizó la expresión osProfile.linuxConfiguration.ssh.publicKeys[0].keyData para obtener la clave pública SSH para iniciar sesión. Para obtener cada clave pública SSH, la expresión podría escribirse como osProfile.linuxConfiguration.ssh.publicKeys[].keyData. Esta expresión de consulta simplifica la matriz osProfile.linuxConfiguration.ssh.publicKeys y, después, se ejecuta la expresión keyData en cada 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"
  ]
}

Filtrado de matrices mediante expresiones booleanas

La otra operación utilizada para obtener datos de una matriz es el filtrado. El filtrado se realiza con el operador de JMESPath [?...]. Este operador toma un predicado como su contenido. Un predicado es cualquier declaración que se puede evaluar como true o false. Esto incluye a las propiedades booleanas. En la salida se incluyen las expresiones en las que el predicado se evalúa a true.

En la primera consulta se muestra cómo enumerar los nombres de todas las suscripciones de Azure conectadas a su cuenta cuya propiedad isDefault posea el valor true. En la segunda y la tercera consulta se muestran dos maneras diferentes de enumerar todas las suscripciones cuya propiedad isDefault posea el valor 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 ofrece la comparación estándar y los operadores lógicos. Estos incluyen <, <=, >, >=, == y !=. JMESPath también admite la lógica y (&&) o (||) y no (!). Las expresiones se pueden agrupar entre paréntesis, lo que permite expresiones de predicados más complejas. Para obtener todos los detalles sobre predicados y operaciones lógicas, consulte la especificación de JMESPath.

En la sección anterior, se simplificó una matriz para obtener una lista completa de todas las VM de un grupo de recursos. Mediante el uso de filtros, esta salida puede restringirse solo a las máquinas virtuales 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

También puede filtrar valores numéricos, como el valor del tamaño del disco del sistema operativo. En el siguiente ejemplo se muestra cómo filtrar la lista de VM para mostrarlas con un tamaño del disco de 50 GB o superior.

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

En el caso de matrices grandes, puede ser más rápido aplicar el filtro antes de seleccionar los datos.

Importante

En JMESPath, las cadenas siempre deben aparecer entre comillas simples (') o caracteres de escape (`). Si utiliza comillas dobles como parte de una cadena en un predicado de filtro, obtendrá una salida vacía.

Funciones JMESPath

El lenguaje JMESPath también posee funciones integradas que permiten realizar consultas más complejas y modificar la salida de las consultas. Esta sección se centra en el uso de funciones JMESPath para crear consultas, mientras que la sección Manipulación de la salida mediante funciones muestra cómo usar funciones para modificar la salida.

Como las expresiones se evalúan antes de llamar a la función, los propios argumentos pueden ser expresiones JMESPath. En los siguientes ejemplos se demuestra este concepto mediante el uso del argumento contains(string, substring), que comprueba si las cadenas contienen substrings. El siguiente comando le permite buscar todas las VM que utilicen un disco de sistema operativo con tecnología de almacenamiento SSD:

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

Expresiones de canalización

El carácter | puede usarse para aplicar expresiones a los resultados de consulta intermedios en las consultas JMESPath, de una forma similar a como se haría en la línea de comandos. También podemos usar | para dividir las consultas complejas en subexpresiones más sencillas. Para acortar la consulta de la sección anterior, use | para aplicar el filtro después de aplanar y seleccionar datos.

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

Consulte la especificación de JMESPath - Funciones integradas para ver la lista completa de funciones.

Manipulación de la salida mediante funciones

Las funciones JMESPath también tienen otro propósito, que es trabajar sobre los resultados de una consulta. Cualquier función que devuelva un valor no booleano cambia el resultado de una expresión. Por ejemplo, puede ordenar los datos por un valor de propiedad con sort_by(array, &sort_expression). JMESPath utiliza un operador especial, &, para expresiones que deben evaluarse posteriormente como parte de una función. En el ejemplo siguiente se muestra cómo ordenar una lista de máquinas virtuales por el tamaño 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

Consulte la especificación de JMESPath - Funciones integradas para ver la lista completa de funciones.

Aplicación de formato a los resultados de la consulta

Aunque la CLI de Azure usa el formato JSON como formato de salida predeterminado, otros formatos de salida podrían adaptarse mejor a una consulta en función de su propósito y resultados. Las consultas siempre se ejecutan primero en la salida JSON y, después, se les aplica un formato.

En esta sección se repasarán los formatos tsv y table, junto con algunos casos de uso para cada formato. Para obtener más información sobre los formatos de salida, consulte el artículo Formatos de salida para los comandos de la CLI de Azure.

Formato de salida TSV

El formato de salida tsv devuelve valores separados por tabulaciones y nueva línea sin formato adicional, claves ni otros símbolos. Este formato es útil cuando la salida se almacena en un parámetro y se usa en otro comando.

Un caso de uso para el formato tsv es el de las consultas que recuperan un valor a partir de un comando de la CLI, como puede ser un id. de recurso o un nombre de recurso de Azure, y lo almacenan en una variable de entorno local. De forma predeterminada, los resultados se devuelven en formato JSON, lo que puede ser un problema al tratar con cadenas JSON que se incluyen en caracteres ". Si la salida del comando se asigna directamente a la variable de entorno, es posible que el intérprete shell no pueda interpretar las comillas. Este problema se puede ver en el siguiente ejemplo, en el que asigna el resultado de una consulta a una variable de entorno:

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

"azureuser"

Use el formato tsv como se muestra en la siguiente consulta para evitar que los valores devueltos aparezcan rodeados de información de tipo:

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

azureuser

Formato de salida de tabla

El formato table imprime la salida como una tabla ASCII, lo que facilita la lectura y la búsqueda. En la tabla no se incluyen todos los campos, así que este formato es más adecuado si se usa a modo de información general de los datos en la que el usuario puede realizar búsquedas. Los campos que no se incluyen en la tabla se pueden obtener mediante un filtro incluido en una consulta.

Nota

Determinadas claves se filtran y no se imprimen en la vista de tabla. Estas claves son id, type y etag. Para ver estos valores, puede cambiar el nombre de la clave en un hash de selección múltiple.

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

Para demostrar este concepto, podemos usar una consulta anterior. La consulta original devolvió un objeto JSON que contiene el nombre, el sistema operativo y el nombre del administrador de cada VM del grupo de recursos:

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

Si esta cadena se combina con el formato de salida --output table, los nombres de columna coincidirán con el valor displayKey del hash de selección múltiple y consultar la información será más sencillo:

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

Pasos siguientes

Para obtener más información sobre las consultas de JMESPath, consulte Tutorial de JMESPath.

Para obtener más información sobre los otros conceptos de la CLI de Azure mencionados en este artículo, consulte los siguientes artículos: