Sugerencias para utilizar la CLI de Azure correctamente

Artículo
03/05/2024

La CLI de Azure es una herramienta de línea de comandos que permite configurar y administrar recursos de Azure desde muchos entornos de shell. Después de elegir el entorno de shell preferido e instalar la CLI de Azure, use este artículo para descubrir sugerencias útiles sobre cómo evitar problemas comunes y usar correctamente la CLI de Azure.

Para más información sobre los comandos específicos de la CLI de Azure, consulte la lista de referencia de la CLI de Azure.

Formato de salida

Con los comandos de la CLI de Azure habitualmente se usan tres formatos de salida:

El formato json muestra la información en forma de cadena JSON.
- JSON proporciona la información más completa.
- Este formato es el predeterminado, pero puede usar el parámetro --output para especificar otra opción.
- Cambie el formato predeterminado global a una de sus preferencias personales mediante az config, como az config set core.output=table.
- El formato JSON conserva las comillas dobles y, por lo general, no es adecuado para la creación de scripts.

El formato table presenta la salida en forma de tabla legible. Puede especificar qué valores aparecen en la tabla y usar consultas para personalizar la salida, como se muestra aquí:

# command
az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table

# output
Name    Os
------  ------------
myVMname   UbuntuServer

El formato tsv devuelve valores separados por tabulaciones y nueva línea sin formato adicional, claves ni otros símbolos.
- El formato TSV es útil para generar una salida es concisa y crear scripts.
- TSV quita las comillas dobles que el formato JSON conserva.
- Para especificar el formato que desea para TSV, use el parámetro --query.
```
export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids
```

Para más información sobre estos y otros formatos, consulte Formatos de salida para los comandos de la CLI de Azure.

Paso de valores a otro comando

Si el valor se usa más de una vez, asígnelo a una variable. Las variables permiten usar valores más de una vez o crear scripts más generales. En este ejemplo se asigna un identificador encontrado por el comando az vm list a una variable.

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

Si el valor se usa una sola vez, considere la posibilidad de canalizarlo. (Piping pasa la salida de un comando como entrada a un segundo comando).

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

En el caso de las listas con varios valores, tenga en cuenta las siguientes opciones:

Si necesita más controles en el resultado, use un bucle "for":

#!/usr/bin/env bash
for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
    echo stopping $vmList
    az vm stop --ids $vmList
    if [ $? -ne 0 ]; then
        echo "Failed to stop $vmList"
        exit 1
    fi
    echo $vmList stopped
done

Como alternativa, use xargs y considere la posibilidad de usar la marca -P para ejecutar las operaciones en paralelo para mejorar el rendimiento:

az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | xargs -I {} -P 10 az vm start --ids "{}"

Por último, la CLI de Azure incluye compatibilidad integrada para procesar comandos con varios --ids en paralelo para lograr el mismo efecto que xargs. @- se usa para obtener valores de la canalización:
```
az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-
```

Para más información sobre el uso de construcciones de Bash con la CLI de Azure, incluidos bucles, instrucciones case, if..then..else y control de errores, consulte Aprendizaje de Bash mediante la CLI de Azure.

Uso de comillas en parámetros

Cuando trabaje con comandos de la CLI de Azure, tenga en cuenta cómo usa el shell las comillas y los caracteres de escape. Si admite scripts usados en distintos shells, comprenda cómo difieren.

Bash. Comillas
PowerShell. Acerca de las reglas de las comillas
Símbolo del sistema de Windows. Procedimiento: Caracteres de escape, delimitadores y comillas en la línea de comandos de Windows

Nota

Debido a un problema conocido de PowerShell, se aplican algunas reglas de escape adicionales. Para más información, consulte Problemas de comillas con PowerShell.

Para evitar resultados imprevistos, estas son algunas sugerencias:

Si incluye un parámetro un valor que contiene espacios en blanco, debe encapsularlo entre comillas.
En Bash o PowerShell, tanto las comillas simples como las dobles se interpretan correctamente. En el símbolo del sistema de Windows, solo las comillas dobles se interpretan correctamente (las comillas simples se tratan como parte del valor).
Si el comando solo se va a ejecutar en Bash (o Zsh), use comillas simples para conservar el contenido de dentro de la cadena JSON. Las comillas simples son necesarias al proporcionar valores JSON insertados. Por ejemplo, este código JSON es correcto en Bash: '{"key": "value"}'.
Si el comando se ejecuta en un símbolo del sistema de Windows, debe usar comillas dobles. Si el valor contiene comillas dobles, debe agregarle caracteres de escape. El equivalente de la cadena JSON anterior es "{\"key\": \"value\"}"
En PowerShell, si el valor es una cadena vacía, use '""'.
En Bash o PowerShell, si el valor es una cadena vacía con comillas '', use "''".
Use la convención @<file> de la CLI de Azure para realizar la carga desde un archivo y omitir los mecanismos de interpretación del shell.
```
az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json
```
Bash evalúa las comillas dobles en las variables exportadas. Si este comportamiento no es el deseado, escape la variable: "\$variable".
Algunos comandos de la CLI de Azure toman una lista de valores separados por espacios.
- Si el nombre o el valor de la clave contienen espacios, encapsule todo el par: "my key=my value". Por ejemplo:
```
az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"
```
- Cuando un parámetro de la CLI indica que acepta una lista separada por espacios, se espera uno de los dos formatos:
  1. Lista separada por espacios sin comillas--parameterName firstValue secondValue
  2. Lista separada por espacios con comillas--parameterName "firstValue" "secondValue"
  Este ejemplo es una cadena con un espacio. No es una lista separada por espacios: --parameterName "firstValue secondValue"

Hay caracteres especiales de PowerShell, como @. Para ejecutar la CLI de Azure en PowerShell, agregue ` antes del carácter especial para escaparlo. En su lugar, puede cerrar el valor entre comillas simples o dobles "/".

# The following three examples will work in PowerShell
--parameterName `@parameters.json
--parameterName '@parameters.json'
--parameterName "@parameters.json"

# This example will not work in PowerShell
--parameterName @parameters.json

Cuando se usa el parámetro --query con un comando, se deben agregar algunos caracteres de JMESPath en el shell.
- Bash
- PowerShell
- Cmd
Estos tres comandos son correctos y equivalentes en Bash:
```
az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""
```
Estos son dos ejemplos de comandos incorrectos en Bash:
```
# Wrong, as the dash needs to be quoted in a JMESPath query
az version --query azure-cli
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

# Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
az version --query "azure-cli"
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'
```
Para ver más comparaciones de ejemplo entre Bash, PowerShell y Cmd, consulte el artículo en que se indica cómo consultar la salida del comando de la CLI de Azure.
Estos cinco comandos funcionan correctamente en PowerShell:
```
az version --query '\"azure-cli\"'
az version --query "\`"azure-cli\`""
az version --query "\""azure-cli\"""
az --% version --query "\"azure-cli\""
az --% version --query \"azure-cli\"
```
Para ver más comparaciones de ejemplo entre Bash, PowerShell y Cmd, consulte el artículo en que se indica cómo consultar la salida del comando de la CLI de Azure.
Estos dos comandos funcionan correctamente en el símbolo del sistema de Windows:
```
az version --query "\"azure-cli\""
az version --query \"azure-cli\"
```
Para ver más comparaciones de ejemplo entre Bash, PowerShell y Cmd, consulte el artículo en que se indica cómo consultar la salida del comando de la CLI de Azure.

La mejor manera de solucionar un problema de comillas es ejecutar el comando con la marca --debug. Esta marca muestra los argumentos reales que recibe CLI de Azure en la sintaxis de Python.

# Correct
$ az '{"key":"value"}' --debug
Command arguments: ['{"key":"value"}', '--debug']

# Correct
$ az "{\"key\":\"value\"}" --debug
Command arguments: ['{"key":"value"}', '--debug']

# Wrong, as quotes and spaces are interpreted by Bash
$ az {"key": "value"} --debug
Command arguments: ['{key:', 'value}', '--debug']

# Wrong, as quotes are interpreted by Bash
$ az {"key":"value"} --debug
Command arguments: ['{key:value}', '--debug']

Uso de caracteres de guión en parámetros

Si el valor de un valor comienza por un guion, la CLI de Azure intenta analizarlo como si fuera un nombre de parámetro. Para analizarlo como valor, use = para concatenar el nombre y el valor del parámetro: --password="-VerySecret".

Operaciones asincrónicas

Las operaciones en Azure pueden tardar un tiempo considerable. Por ejemplo, la configuración de una máquina virtual en un centro de datos no es instantánea. La CLI de Azure espera hasta que el comando haya terminado para aceptar otros comandos. Por consiguiente, muchos comandos ofrecen un parámetro --no-wait como se muestra aquí:

az group delete --name MyResourceGroup --no-wait

Cuando elimina un grupo de recursos, también se quitan todos los recursos que le pertenecen. La eliminación de estos recursos puede tardar mucho tiempo. Al ejecutar el comando con el parámetro --no-wait, la consola acepta nuevos comandos sin interrumpir la eliminación.

Muchos comandos ofrecen una opción de espera, que pone en pausa la consola hasta que se cumpla alguna condición. En el ejemplo siguiente se usa el comando az vm wait para admitir la creación de recursos independientes en paralelo:

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

Una vez que se crean ambos identificadores, puede volver a usar la consola.

Uso detrás de un proxy

Si usa la CLI de Azure a través de un servidor proxy que usa certificados autofirmados, la biblioteca de solicitudes de Python usada por la CLI de Azure puede producir el siguiente error: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Para solucionar este error, establezca la variable de entorno REQUESTS_CA_BUNDLE en la ruta de acceso del archivo de certificado de la agrupación de la entidad de certificación en formato PEM.

SO	Agrupación de la entidad de certificación predeterminada
Windows de 32 bits	`C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Windows 64 bits	`C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Linux Ubuntu y Debian	`/opt/az/lib/python<version>/site-packages/certifi/cacert.pem`
Linux CentOS, RHEL y SUSE	`/usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem`
macOS	`/usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem`

Anexe el certificado del servidor proxy al archivo de certificado de la agrupación de la entidad de certificación o copie el contenido en otro archivo de certificado. Luego, establezca REQUESTS_CA_BUNDLE en la nueva ubicación del archivo. Este es un ejemplo:

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

Algunos servidores proxy requieren autenticación. El formato de las variables de entorno HTTP_PROXY o HTTPS_PROXY debe incluir la autenticación; por ejemplo, HTTPS_PROXY="https://username:password@proxy-server:port". Para más información, consulte Configuración de servidores proxy para las bibliotecas de Azure.

Ejecución simultánea

Si ejecuta comandos de la CLI de Azure simultáneamente en la misma máquina, se pueden producir conflictos de escritura si varios comandos de la CLI de Azure escriben en la misma caché de tokens de MSAL.

Para evitar posibles errores, puede aislar la carpeta de configuración de la CLI de Azure para cada script estableciendo la variable de entorno AZURE_CONFIG_DIR para cada script en un directorio independiente. Los comandos de la CLI de Azure en ese script guardan la configuración y la caché de tokens en la ubicación configurada en lugar de la carpeta predeterminada ~/.azure.

export AZURE_CONFIG_DIR=/my/config/dir

$env:AZURE_CONFIG_DIR='D:\my\config\dir'

set AZURE_CONFIG_DIR=D:\my\config\dir

Parámetros de actualización genéricos

Los grupos de comandos de la CLI de Azure suelen ofrecer un comando update. Por ejemplo, Azure Virtual Machines incluye el comandoaz vm update. La mayoría de los comandos de actualización ofrecen los tres parámetros genéricos: --add, --set y --remove.

Los parámetros --set y --add toman una lista de pares clave-valor separados por espacios: key1=value1 key2=value2. Para ver qué propiedades puede actualizar, use el comando show, por ejemplo, az vm show.

az vm show --resource-group VMResources --name virtual-machine-01

Para simplificar el comando, considere la posibilidad de usar una cadena JSON. Por ejemplo, para conectar un nuevo disco de datos a una máquina virtual, use el siguiente valor:

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

Comandos de recursos genéricos (az resource)

Es posible que un servicio con el que quiera trabajar no sea compatible con la CLI de Azure. Para trabajar con estos recursos puede usar los comandos az resource.

Si solo necesita comandos create o update, use az deployment group create. Para ver ejemplos en funcionamiento, consulte Plantillas de inicio rápido de Azure.

Comandos de la API REST (az rest)

Si los parámetros de actualización genéricos y az resource no cubren sus necesidades, puede usar el comando az rest para llamar a la API REST. El comando se autentica de forma automática con las credenciales de inicio de sesión y establece el encabezado Content-Type: application/json. Para más información, consulte Referencia de la API REST de Azure.

Este ejemplo trabaja con Microsoft Graph API. Para actualizar los identificadores URI de redireccionamiento de una aplicación, llame a la API REST de Actualizar aplicación, como en este código:

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

Al usar --uri-parameters para solicitudes con forma de OData, asegúrese de agregar un carácter de escape a $ en los diferentes entornos: en Bash, use $ como \$ y, en PowerShell, use $ como `$

Ejemplos de script

Estos son ejemplos para usar variables y recorrer en bucle una lista al trabajar con Azure Virtual Machines. Para ver ejemplos en profundidad sobre el uso de construcciones de Bash con la CLI de Azure, incluidos bucles, instrucciones case, if..then..else y control de errores, consulte Aprendizaje de Bash mediante la CLI de Azure.

Use estos scripts para guardar los identificadores en variables:

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids # CLI stops all VMs in parallel

Use estos scripts para recorrer en bucle una lista:

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
foreach ($vm_id in $vm_ids) {
    Write-Output "Stopping $vm_id"
    az vm stop --ids $vm_id
}

Consulte también

Configuración de la CLI de Azure
Aprendizaje de Bash con la CLI de Azure
Resultados de los comandos de consulta de la CLI de Azure
Uso de variables en comandos de la CLI de Azure
Buscar muestras y artículos publicados de la CLI de Azure