Solución de problemas de la CLI de Azure

Artículo
12/11/2024

Categorías de error

La mayoría de los errores devueltos por la CLI de Azure se dividen en una de estas categorías:

Categoría de error	Causa general del error
Argumento no reconocido	Un parámetro está mal escrito o no existe.
argumento obligatorio que falta	No se especifica un parámetro necesario o solo se especifica uno de los dos "pares de parámetros". Un parámetro también puede estar mal escrito.
Argumento mutuamente excluyente	No se pueden especificar dos o más parámetros juntos.
valor de argumento no válido	El valor del parámetro no es válido. Este error suele deberse al uso incorrecto de comillas, un carácter de escape o un espaciado.
Solicitud incorrecta	Un código de estado HTTP de 400 devuelve este error. Busque un espacio que falte, un guión de parámetro que falte o una comilla simple o doble adicional o que falte. Este error también se produce cuando un valor de parámetro no contiene un valor permitido.
recurso no encontrado	No se puede encontrar un recurso de Azure al que se hace referencia en un valor de parámetro.
Autenticación	Error de autenticación de Microsoft Entra.

Parámetro `--debug`

Una de las mejores maneras de ver lo que la CLI de Azure está ejecutando para cada comando de referencia de la CLI de Azure es usar el parámetro --debug. Aquí tienes ejemplos de --debug para un comando fallido y uno exitoso:

# Error example: Create a resource group, but omit the quotes around the resource group name.
az group create --location eastus2 --name msdocs-rg-test --debug

Aquí tienes una parte de la salida de depuración. Observe la ubicación del registro y el argumento no reconocido.

cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-name', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.azclierror: unrecognized arguments: msdocs-rg-test
...

Compare el error --debug salida dada anteriormente con una ejecución correcta:

# Correct example: Because the resource group name contains special characters, enclose it in quotes
az group create --location eastus2 --name "msdocs-rg-test" --debug

Esta es una parte de la salida de depuración. Observe la ubicación del registro, la llamada API y el tiempo de ejecución.

cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-n', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/msdocs-rg-test?api-version=YYYY-MM-DD'
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': 'ba7ee6f4-2dcc-11ef-81ce-00155dadc5c8'
cli.azure.cli.core.sdk.policies:     'CommandName': 'group create'
cli.azure.cli.core.sdk.policies:     'ParameterSetName': '-l -n --debug'
cli.azure.cli.core.sdk.policies:     'User-Agent': 'AZURECLI/2.61.0 (RPM) azsdk-python-core/1.28.0 Python/3.9.19 (Linux-5.10.102.2-microsoft-standard-x86_64-with-glibc2.35) cloud-shell/1.0'
cli.azure.cli.core.sdk.policies:     'Authorization': '*****'
cli.azure.cli.core.sdk.policies: Request body:
cli.azure.cli.core.sdk.policies: {"location": "eastus2"}
urllib3.connectionpool: Starting new HTTPS connection (1): management.azure.com:443
urllib3.connectionpool: https://management.azure.com:443 "PUT /subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourcegroups/msdocs-rg-test?api-version=2022-09-01 HTTP/1.1" 201 226
cli.azure.cli.core.sdk.policies: Response status: 201
...
cli.azure.cli.core.sdk.policies:     'Date': 'Tue, 18 Jun 2024 23:44:41 GMT'
cli.azure.cli.core.sdk.policies: Response content:
cli.azure.cli.core.sdk.policies: {"id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-rg-test","name":"msdocs-rg-test","type":"Microsoft.Resources/resourceGroups","location":"eastus2","properties":{"provisioningState":"Succeeded"}}
...
cli.__main__: Command ran in 1.829 seconds (init: 0.111, invoke: 1.718)

Para obtener ejemplos de --debug para el formato JSON, consulte diferencias en las citas entre los lenguajes de scripting: cadenas JSON.

Errores comunes de sintaxis

Aunque la CLI de Azure se puede ejecutar en Bash, PowerShell y Windows Cmd, existen diferencias de sintaxis entre los lenguajes de scripting. Los scripts de la CLI de Azure que contienen comillas simples, comillas dobles y caracteres de escape normalmente se deben modificar cuando se copian entre idiomas. Este desafío se revela con más frecuencia en los valores de parámetro, especialmente en los valores asignados al parámetro --query. Estos son algunos mensajes de error comunes:

"solicitud incorrecta ... {algo} no es válido" puede deberse a un espacio, comillas simples o dobles o a la falta de una comilla.
"Error de token inesperado..." aparece cuando hay un espacio extra o una comilla de más.
"El valor 'jmespath_type' inválido" suele ser un error que proviene de una comilla incorrecta en el parámetro --query.
"Referencia de variable no es válida" se recibe cuando una cadena no tiene el formato correcto a menudo debido a la concatenación o a un carácter de escape que falta.
"argumentos no reconocidos" suele deberse a un carácter de continuación de línea incorrecto o a un nombre de parámetro mal escrito.
"Expresión que falta después del operador unario" se ve cuando falta un carácter de continuación de línea.

Hay varios artículos de la CLI de Azure dedicados a explicar los errores de sintaxis y proporcionar ejemplos de trabajo:

Citando diferencias entre los lenguajes de scripting
Tutorial de diferencias de sintaxis en Bash, PowerShell y Cmd
Busque muchos ejemplos de parámetros de --query en salida de comandos de la CLI de Azure mediante una consulta JMESPath
Cómo usar la CLI de Azure en un script de Bash
Consideraciones para ejecutar la CLI de Azure en un lenguaje de scripting de PowerShell

Propina

Si no puede resolver un error de comando, intente usar otro lenguaje de scripting. La mayoría de la documentación de la CLI de Azure se escribe y prueba en Azure Cloud Shell (ACS) con un lenguaje de scripting de Bash. Si puede obtener un ejemplo de artículo para ejecutar en ACS Bash, pero no se ejecutará en Windows PowerShell, revise el uso de comillas simples y dobles y caracteres de escape.

Error: Valor no válido o no existe

Estos errores a menudo se producen al intentar usar un valor de variable que contiene un formato incorrecto. La salida predeterminada de la CLI de Azure es JSON, por lo que si intenta almacenar un identificador para un recurso de Azure en una variable, debe especificar --output tsv. Este es un ejemplo:

# Get a subscription that contains a name or phrase
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id")
echo $subscriptionID

# output as JSON
[ "00000000-0000-0000-0000-000000000000" ]

# Try to set your subscription to the new ID
az account set --subscription $subscriptionID

# error output
The subscription of '"00000000-0000-0000-0000-000000000000"' doesn't exist in cloud 'AzureCloud'.

Ahora use el tipo de salida tsv.

# Get the active subscription
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id" --output tsv)
echo $subscriptionID

# output as TSV
00000000-0000-0000-0000-000000000000

# Successfully set your subscription to the new ID
az account set --subscription $subscriptionID

Error: Se esperan o requieren argumentos

Recibe este error cuando falta un parámetro necesario en un comando de la CLI de Azure o hay un error tipográfico que hace que la CLI de Azure analice incorrectamente el comando de referencia. Al trabajar con un script, también recibirá este error cuando se cumplen una o varias condiciones:

Falta un carácter de continuación de línea o es incorrecto.
Existe un espacio final en el lado derecho de un carácter de continuación de línea al trabajar en el lenguaje de scripting de PowerShell. En este momento, de expansión no se admite con comandos de la CLI de Azure.
Un nombre de variable contiene un carácter especial, como un guión (-).

Error: Recurso no encontrado

Cuando la CLI de Azure no encuentra el nombre del recurso o el identificador pasados en un valor de parámetro, suele deberse a uno de estos motivos:

El nombre o el identificador del recurso se escriben incorrectamente.
El nombre del recurso contiene caracteres especiales y no está rodeado de comillas simples o dobles.
El valor que se pasa a una variable tiene espacios iniciales o finales no vistos.
El recurso existe, pero está en una suscripción diferente.

Error: No se pudo analizar la cadena como JSON

Hay diferencias en la manera de citar entre Bash, PowerShell en Linux y PowerShell en Windows. Además, diferentes versiones de PowerShell pueden generar resultados diferentes. En el caso de parámetros complejos, como una cadena JSON, el procedimiento recomendado es usar la convención de @<file> de la CLI de Azure para omitir la interpretación de un shell. Para obtener más información, consulte uno de estos artículos:

Para ver ejemplos de sintaxis JSON para Bash, PowerShell y Cmd.exe, consulte el tutorial sobre las diferencias en la cita entre lenguajes de scripting - cadenas JSON .

Error: InvalidTemplateDeployment

Al intentar crear un recurso de Azure en una ubicación que no ofrezca ese recurso, recibirá un error similar al de este mensaje: "Se han producido errores en las SKU siguientes para las restricciones de capacidad: myDesiredSkuName" no está disponible actualmente en la ubicación "mySpecifiedLocation".

Este es un ejemplo de error completo para una máquina virtual que no se puede crear en la ubicación de westus:

{"error":{"code":"InvalidTemplateDeployment","message":"The template deployment 'vm_deploy_<32 character ID>'
is not valid according to the validation procedure. The tracking id is '<36 character ID>'.
See inner errors for details.","details":[{"code":"SkuNotAvailable","message":"The requested VM size for resource
'Following SKUs have failed for Capacity Restrictions: Standard_DS1_v2' is currently not available
in location 'westus'. Please try another size or deploy to a different location
or different zone. See https://aka.ms/azureskunotavailable for details."}]}}

La solución consiste en cambiar una propiedad del recurso de Azure solicitado o probar otra ubicación.

Error: No se encontró la suscripción

Suponiendo que no ha escrito incorrectamente un nombre o identificador de suscripción, este error se produce cuando un proveedor de recursos no está registrado en la suscripción activa. Por ejemplo, si desea ejecutar az storage account create, el proveedor de Microsoft.Storage debe registrarse. Para registrar un proveedor de recursos, consulte tipos y proveedores de recursos de Azure.

Error: Error de saludo... fallo en la verificación del certificado

Consulte Work behind a proxy para obtener información sobre cómo resolver este error.

Trabajar 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 podría 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 del archivo de certificado de CA en formato PEM.

Sistema operativo	Paquete predeterminado de autoridad de certificación
Windows de 32 bits	`C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Windows de 64 bits	`C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Ubuntu/Debian Linux	`/opt/az/lib/python<version>/site-packages/certifi/cacert.pem`
CentOS Stream/RHEL/SUSE Linux	`/usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem`
macOS	Modelos Intel: `/usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem` Modelos de silicio: `/opt/homebrew/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem`

Anexe el certificado del servidor proxy al archivo de certificado de agrupación de CA o copie el contenido en otro archivo de certificado. A continuación, 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 de HTTP_PROXY o HTTPS_PROXY debe incluir la autenticación, como HTTPS_PROXY="https://username:password@proxy-server:port". Para más detalles, consulte Cómo configurar proxies para el Azure SDK para Python.

Principales del servicio

Para obtener información sobre la solución de problemas de los Service Principals, consulte Limpieza y Solución de Problemas en el tutorial Trabajar con Service Principals.

Otros problemas

Si experimenta un problema de producto con la CLI de Azure que no aparece en este artículo, archivo un problema en GitHub.

Consulte también

sugerencias de para usar correctamente la CLI de Azure

Compartir a través de

Solución de problemas de la CLI de Azure

Categorías de error

Parámetro `--debug`

Errores comunes de sintaxis

Error: Valor no válido o no existe

Error: Se esperan o requieren argumentos

Error: Recurso no encontrado

Error: No se pudo analizar la cadena como JSON

Error: InvalidTemplateDeployment

Error: No se encontró la suscripción

Error: Error de saludo... fallo en la verificación del certificado

Trabajar detrás de un proxy

Principales del servicio

Otros problemas

Consulte también

Recursos adicionales

Compartir a través de

Solución de problemas de la CLI de Azure

Categorías de error

Parámetro --debug

Errores comunes de sintaxis

Error: Valor no válido o no existe

Error: Se esperan o requieren argumentos

Error: Recurso no encontrado

Error: No se pudo analizar la cadena como JSON

Error: InvalidTemplateDeployment

Error: No se encontró la suscripción

Error: Error de saludo... fallo en la verificación del certificado

Trabajar detrás de un proxy

Principales del servicio

Otros problemas

Consulte también

Recursos adicionales

Parámetro `--debug`