Compartir a través de

Cómo consultar la salida de los comandos de la CLI de Azure mediante una consulta JMESPath

La CLI de Azure usa el --query parámetro para ejecutar una consulta JMESPath en los resultados de los comandos. JMESPath es un lenguaje de consulta para JSON, lo que le permite seleccionar y modificar datos de la salida de la CLI.

Todos los comandos de la CLI de Azure admiten el --query parámetro . En este artículo se explica cómo usar las características de JMESPath y se proporcionan ejemplos de consultas. Obtenga información sobre los conceptos de JMESPath que son útiles para consultar en la pestaña conceptos. Consulte ejemplos de consultas JMESPath en 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 del lado del cliente en el objeto JSON que devuelve el comando de la CLI de Azure, antes de aplicar cualquier formato de presentación.

Los caracteres de escape necesarios en las consultas difieren para distintos entornos. Se recomienda ejecutar consultas en Azure Cloud Shell o cmd porque 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.

Resultados de la CLI de diccionario y lista

Los resultados del comando de la CLI se tratan primero como JSON para las consultas, incluso cuando el formato de salida es algo distinto de JSON. Los resultados de la CLI son una matriz JSON o un diccionario. Las matrices son secuencias de objetos que se pueden indexar y los diccionarios son objetos sin ordenar 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 podrían devolver más de un objeto devuelven una matriz y los comandos que siempre devuelven un solo objeto devuelven un diccionario.

Obtener propiedades en un diccionario

Al trabajar con los resultados del diccionario, puede acceder a las propiedades desde el nivel superior con solo la clave. El . carácter (subexpresión) se usa para tener acceso a las propiedades de los diccionarios anidados. Antes de introducir consultas, eche un vistazo a la salida sin modificar del comando az vm show :

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

El comando genera un diccionario. Se ha omitido algún 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 comando siguiente obtiene las claves públicas SSH autorizadas para conectarse a la máquina virtual agregando 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, cambiar "osProfile" a "OsProfile" en la consulta anterior no devuelve los resultados correctos.

Obtención de varios valores

Para obtener más de una propiedad, coloque expresiones separadas por comas entre corchetes [ ] (una lista de selección múltiple). El siguiente comando obtiene el nombre de la máquina virtual, el usuario administrador y la clave SSH a la 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 enumeran en la matriz de resultados en el orden en que se les dio 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 sección siguiente.

Cambiar el nombre de las propiedades de una consulta

Para obtener un diccionario en lugar de una matriz al consultar varios valores, use 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"
}

Obtener 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 publicKeys matriz. No hay garantía de que la salida de la CLI esté ordenada, así que evite usar la indexación a menos que esté seguro del orden o no le importe cuál elemento consigas. Para acceder a las propiedades de los elementos de una matriz, realice una de estas dos operaciones: aplanamiento o filtrado. En esta sección se explica cómo aplanar una matriz.

La aplanación de una matriz se realiza con el [] operador 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 se pueden inspeccionar con esta característica. La consulta siguiente obtiene el nombre, el sistema operativo y el nombre del administrador de cada máquina virtual de un 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"
  }
]

Cualquier matriz se puede aplanar, no solo el resultado de nivel superior devuelto por el comando . En la última sección, la expresión osProfile.linuxConfiguration.ssh.publicKeys[0].keyData se usó para obtener la clave pública SSH para el inicio de sesión. Para obtener cada clave pública SSH, la expresión podría escribirse en su lugar como osProfile.linuxConfiguration.ssh.publicKeys[].keyData. Esta expresión de consulta aplana la osProfile.linuxConfiguration.ssh.publicKeys matriz y, a continuación, ejecuta la keyData expresión 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"
  ]
}

Filtrar matrices con expresiones booleanas

La otra operación que se usa para obtener datos de una matriz es el filtrado. El filtrado se realiza con el [?...] operador JMESPath. Este operador toma un predicado como su contenido. Un predicado es cualquier instrucción (incluidas las propiedades booleanas) que se pueden evaluar en true o false. Expresiones en las que el predicado se evalúa como true se incluyen en la salida.

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

En la última sección, has aplanado una matriz para obtener la lista completa de todas las máquinas virtuales de un grupo de recursos. Con el uso de filtros, esta salida solo se puede restringir 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 tamaño del disco del sistema operativo. En el ejemplo siguiente se muestra cómo filtrar la lista de máquinas virtuales para mostrar las que tienen un tamaño de disco mayor o igual que 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

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 están rodeadas de comillas simples (') o caracteres de escape (`). Si usa comillas dobles como parte de una cadena en un predicado de filtro, obtendrá una salida vacía.

Funciones de JMESPath

JMESPath también tiene funciones integradas que permiten consultas más complejas y para modificar la salida de la consulta. Esta sección se centra en el uso de funciones JMESPath para crear consultas mientras que la sección Manipulación de la salida con funciones muestra cómo usar funciones para modificar la salida.

Las expresiones se evalúan antes de llamar a la función, por lo que los propios argumentos pueden ser expresiones JMESPath. En los ejemplos siguientes se muestra este concepto mediante contains(string, substring), que comprueba si una cadena contiene una subcadena. Este comando busca todas las máquinas virtuales que usan almacenamiento SSD para su 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"
  }
]

Expresiones de tubería

De forma similar a cómo | se usa en la línea de comandos, | se puede usar en consultas JMESPath para aplicar expresiones a los resultados intermedios de la consulta. También podemos usar | para dividir 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 JMESPath: Funciones integradas para obtener la lista completa de funciones.

Manipulación de la salida con funciones

Las funciones JMESPath también tienen otro propósito, que es operar en los resultados de una consulta. Cualquier función que devuelve 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 usa un operador especial, &, para expresiones que se deben evaluar más adelante como parte de una función. En el ejemplo siguiente se muestra cómo ordenar una lista de máquinas virtuales por tamaño de 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 JMESPath: Funciones integradas para obtener la lista completa de funciones.

Aplicar formato a los resultados de la consulta

La CLI de Azure usa JSON como formato de salida predeterminado, pero los distintos formatos de salida pueden adaptarse mejor a una consulta en función de su propósito y resultados. Las consultas siempre se ejecutan primero en la JSON salida y luego se formatean.

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

Formato de salida TSV

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

Un caso de uso para tsv el formato es las consultas que recuperan un valor de un comando de la CLI, como un identificador de recurso de Azure o un nombre de recurso, y almacenan el valor 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 entre " caracteres. Es posible que el shell no interprete las comillas si la salida del comando se asigna directamente a la variable de entorno. Este problema se ve en el ejemplo siguiente que asigna un resultado de consulta a una variable de entorno:

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

"azureuser"

Utilice el formato tsv, como se muestra en la consulta siguiente, para evitar que los valores devueltos queden envueltos por 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 table formato imprime la salida como una tabla ASCII, lo que facilita la lectura y el examen. No todos los campos se incluyen en la tabla, por lo que este formato se usa mejor como información general que permite búsquedas humanas de los datos. Los campos que no están incluidos en la tabla se pueden filtrar como parte de una consulta.

Nota:

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

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

Podemos usar una consulta anterior para demostrar este concepto. La consulta original devolvió un objeto JSON que contiene el nombre, el sistema operativo y el nombre del administrador para cada máquina virtual 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"
  }
]

Cuando se combina con el formato de salida --output table, los nombres de las columnas se alinean con el valor displayKey del hash de selección múltiple, haciendo más fácil explorar la información.

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 más información sobre las consultas JMESPath, consulte Tutorial de JMESPath.

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