Sugerencias para usar correctamente la CLI de Azure

  • 5 minutos

En este módulo, ha aprendido a elegir un entorno, instalar la CLI de Azure, ejecutar comandos de la CLI de Azure de forma interactiva y crear un script de Bash . Vamos a seguir aprendiendo un paso más allá y nos centraremos en cómo usar la CLI de Azure correctamente. En esta unidad se enseña cómo funciona la CLI de Azure detrás de la línea de comandos y le ofrece sugerencias para solucionar problemas.

Sugerencia

Este módulo es un curso de nivel avanzado y esta unidad le lleva en profundidad a la CLI de Azure. Si no está familiarizado con la programación de línea de comandos, céntrese en los conceptos. Los detalles son más fáciles de entender a medida que obtiene experiencia. ¡No te dejes!

Descripción de las llamadas API de la CLI de Azure

Detrás de la interfaz gráfica de usuario del portal de Azure y la línea de comandos de la CLI de Azure se ejecutan las llamadas a la API. Puede exponer las llamadas APIde la CLI de Azure mediante el --debug parámetro . Esto es lo que sucede al crear un nuevo grupo de recursos:

az group create --location westus2 --name myResourceGroupName --debug

Esta es la salida del terminal de Azure Cloud Shell con algunas líneas omitidas para mayor brevedad. Observe esta salida importante:

  • Argumentos de comando: Es el lenguaje de scripting, no la CLI de Azure, que analiza los argumentos de comando (parámetros). Esta propiedad de salida es el primer lugar para buscar cuando un comando produce un error.
  • azlogging: Esta ruta de acceso es donde se almacena el archivo de registro.
  • Encabezados de solicitud: Estos encabezados son los valores de parámetro pasados por el comando PUT .
  • Contenido de respuesta: Esta salida es lo que se devuelve a la consola sin la salida completa --debug .
cli.knack.cli: Command arguments: ['group', 'create', '--location', 'westus2', '--name', 'myResourceGroupName', '--debug']
cli.knack.cli: __init__ debug log:
...
cli.knack.cli: Event: CommandInvoker.OnPreCommandTableCreate []
cli.azure.cli.core: Modules found from index for 'group': ['azure.cli.command_modules.resource']
cli.azure.cli.core: Loading command modules:
...
cli.azure.cli.core: Loaded 53 groups, 233 commands.
cli.azure.cli.core: Found a match in the command table.
cli.azure.cli.core: Raw command  : group create
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/2025-10-08.21-47-27.group_create.5217.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/myResourceGroupName?api-version=2022-09-01'
cli.azure.cli.core.sdk.policies: Request method: 'PUT'
cli.azure.cli.core.sdk.policies: Request headers:
cli.azure.cli.core.sdk.policies:     'Content-Type': 'application/json'
cli.azure.cli.core.sdk.policies:     'Content-Length': '23'
cli.azure.cli.core.sdk.policies:     'Accept': 'application/json'
cli.azure.cli.core.sdk.policies:     'x-ms-client-request-id': 'c79caddc-ed78-11ef-8a83-00155dbc433c'
cli.azure.cli.core.sdk.policies:     'CommandName': 'group create'
cli.azure.cli.core.sdk.policies:     'ParameterSetName': '--location --name --debug'
...
cli.azure.cli.core.sdk.policies: Response content:
...
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroupName",
  "location": "westus2",
  "managedBy": null,
  "name": "myResourceGroupName",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}
cli.knack.cli: Event: Cli.SuccessfulExecute []
cli.knack.cli: Event: Cli.PostExecute [<function AzCliLogging.deinit_cmd_metadata_logging at 0x7f98a6bc7820>]
az_command_data_logger: exit code: 0
...

Información clave de la salida de depuración

  • Análisis de comandos: El lenguaje de scripting (no la CLI de Azure) analiza los argumentos. Mire aquí primero al solucionar problemas.
  • Ubicación del archivo de registro: Busque registros detallados en la ruta que se muestra en azlogging para el análisis post-mortem.
  • Detalles de la API: Consulte la llamada a la API REST real que se realiza, incluido el método HTTP (PUT, GET, etc.).
  • Código de salida: Un valor de 0 indica que se ha realizado correctamente; los valores que no son ceros indican errores.

Algunos comandos de la CLI de Azure realizan varias acciones. Use --debug para ver que cada comando de la CLI de Azure se está ejecutando. Incluso más útil, use --debug para solucionar los problemas de por qué un script de la CLI de Azure genera resultados inesperados.

Solución de problemas con --debug

¿Cuántas veces ha pensado un desarrollador? "Esta tarea debe ser tan sencilla! "¿Por qué no funciona mi script?" Cuando obtenga resultados inesperados de los comandos de la CLI de Azure, ¡el parámetro --debug será su mejor aliado! Veamos un ejemplo de una empresa con 100 cuentas de Almacenamiento de Azure. Debe encontrar esas cuentas en las que está habilitado el acceso público de blobs.

# Bash script - INCORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == `true`].id"

Cuando un valor de parámetro no tiene el formato correcto para el lenguaje de scripting que analiza el valor, recibirá un invalid jmespath_type value error:

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == ].id', '--debug']
...
cli.azure.cli.core.azclierror: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'
az_command_data_logger: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'

Examine el valor de la variable que Bash está pasando para allowBlobPublicAccess. De hecho, ¿dónde está el valor? ¿Por qué falta?

Recuerde que es el entorno (también denominado "lenguaje de scripting") que analiza los valores de las variables de la CLI de Azure . Cada lenguaje de scripting, e incluso versiones del mismo lenguaje de scripting, pueden generar resultados diferentes. Esta es la manera correcta de pasar un valor de parámetro booleano en Bash:

# Bash script - CORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == \`true\`].id" --debug

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == `true`].id', '--debug']
...
[
  "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-rg-00000000/providers/Microsoft.Storage/storageAccounts/msdocssa00000000"
]

Sugerencia

La diferencia clave es escapar las comillas invertidas con ``true`` para que Bash no las interprete como sustitución de comandos.

Comprenda el concepto importante de --debug y está en su camino para usar CLI de Azure correctamente en su entorno preferido.

Diferencias de sintaxis del lenguaje de scripting

Como acabamos de hablar de --debug, el siguiente paso es tener en cuenta lo que causa la mayoría de los errores de scripting. Es necesario modificar un script escrito en Bash para ejecutarse correctamente en PowerShell o cmd.exe si el script contiene una de estas construcciones:

  • Caracteres de continuación de línea
  • variables
  • Identificadores aleatorios
  • Ofertas
  • Construcciones del lenguaje de programación

Estos son algunos ejemplos:

Sintaxis Bash PowerShell cmd.exe
Caracteres de continuación de línea Barra diagonal inversa (\) Acento grave (`) Intercalación (^)
Nomenclatura de variables variableName=varValue $variableName="varValue" set variableName=varValue
Número como cadena \50'' `50` `50`
Boolean como cadena \true'' `false` 'true'
Id. aleatorio let "randomIdentifier=$RANDOM*$RANDOM" $randomIdentifier = (New-Guid).ToString().Substring(0,8) set randomIdentifier=%RANDOM%
Bucle until, , while, for for, foreach, while, , do-while, do-until for
Escribir en la consola echo Write-Host (preferido) o echo echo

Errores comunes

Esta tabla de ejemplo no es todo incluido. Lo que es importante comprender al recibir un error de la CLI de Azure es tener en cuenta primero que podría haber un problema de sintaxis para su entorno. Pruebe esta posibilidad copiando y pegando el script en otro lenguaje de scripting, como Azure Cloud Shell. Use --debug en ambos entornos y observe las diferencias en la command arguments propiedad de la salida.

Importante

Al copiar bloques de código de los artículos de Microsoft , tenga en cuenta que la mayoría de la documentación de la CLI de Azure en Microsoft se escribe para Bash y se prueba en Azure Cloud Shell.

Más formas de obtener ayuda

Uso de az find

Realice un recorrido rápido por los comandos de la CLI de Azure siguiendo estos ejemplos:

Encontrar los comandos más populares relacionados con la palabra blob:

az find blob

Mostrar los comandos más populares para un grupo de comandos de la CLI de Azure , como az storage:

az find "az storage"

Mostrar los parámetros y subcomandos más populares para un comando de la CLI de Azure :

az find "az storage account create"

Uso de --help

Si ya conoce el nombre del comando que quiere, el argumento --help para ese comando proporciona información más detallada sobre el comando y una lista de los subcomandos disponibles para un grupo de comandos. Siguiendo con nuestros ejemplos de Azure Storage , aquí se muestra cómo puede obtener una lista de los subgrupos y comandos para administrar el servicio de blobs de una cuenta de almacenamiento:

az storage account blob-service-properties --help

Sugerencia

Use --help con cualquier comando o subcomando para obtener información detallada de uso sin salir del terminal.

Índices de documentación de A a Z

Para buscar ejemplos de comandos de referencia de la CLI de Azure , use uno de varios índices A a Z:

  • Índice de referencia: Proporciona una lista A a Z de todos los grupos de referencia. Expanda la barra de navegación izquierda para los subgrupos.

  • Lista de artículos conceptuales de la CLI de Azure: proporciona una lista A a Z de guías de inicio rápido, guías de procedimientos, tutoriales y módulos de aprendizaje que explican cómo usar comandos de referencia de la CLI de Azure en escenarios reales. La lista de artículos agrupa los artículos por grupo de comandos de CLI de Azure, como az account, luego az acr, etc. Use Ctrl+F en Windows (Cmd+F en macOS) para saltar rápidamente al grupo de comandos de su elección.

  • Scripts de ejemplo de la CLI de Azure: El índice tiene tres pestañas:

Uso de Copilot

Tanto Azure Portal como Microsoft Edge ofrecen experiencias de Copilot que devuelven información sobre los comandos de referencia de la CLI de Azure , ejemplos y artículos publicados. Copilot también proporciona vínculos a preguntas relacionadas de Stack Overflow . Cuando tienes un trabajo difícil de realizar con varios pasos de secuencias de comandos, Copilot es útil para reunir varias fuentes de información para responder a tu pregunta.

Nota:

GitHub Copilot también puede ayudarle a escribir scripts de la CLI de Azure directamente en el editor de código, lo que proporciona sugerencias y finalización de código inteligente.