Consideraciones para ejecutar la CLI de Azure en un entorno de PowerShell

  • Artículo

La CLI de Azure es una herramienta para administrar recursos de Azure mediante comandos de referencia de la CLI de Azure que se ejecutan en un entorno de Bash y PowerShell. Sin embargo, hay pequeñas diferencias de sintaxis en el formato de parámetros entre entornos que pueden dar lugar a resultados inesperados. El propósito de este artículo es ayudarle a resolver errores de sintaxis de la CLI de Azure al trabajar en un entorno de PowerShell.

En este artículo se comparan las diferencias de sintaxis de los comandos de la CLI de Azure ejecutados en los siguientes entornos:

  • Bash que se ejecuta en un sistema operativo Linux mediante Azure Cloud Shell.
  • PowerShell que se ejecuta en un sistema operativo Linux mediante Azure Cloud Shell.
  • Windows PowerShell que se ejecuta en Windows 11 mediante el terminal de PowerShell 5.
  • PowerShell que se ejecuta en windows 11 mediante el terminal de PowerShell 7.

Si no está familiarizado con la CLI, diferenciar entre una herramienta y un entorno podría resultar confuso. Cómo elegir la herramienta de línea de comandos adecuada proporciona una buena comparación.

Requisitos previos

Este artículo está pensado para leer y aprender. Sin embargo, si desea ejecutar los ejemplos, seleccione la Prepare your environments pestaña para instalar los entornos usados en este artículo.

Importante

Cuando tenga un script de la CLI de Azure que genere un error, tenga en cuenta cómo funciona el entorno en el que se analiza la sintaxis de comandos de la CLI de Azure.

Paso de espacios en parámetros de la CLI de Azure

En la CLI de Azure, cuando necesite pasar un valor de parámetro que contenga un espacio, hay diferencias entre los sistemas operativos y los entornos. En este ejemplo, use az storage account list y cambie el nombre de las columnas de salida con una palabra que contiene un espacio.

En este ejemplo, observe el contenedor de comillas simples ('...') con comillas dobles incrustadas ("..."). Este ejemplo también funciona en PowerShell en Linux.

az storage account list --query '[].{"SA Name":name, "Primary endpoint":primaryEndpoints.blob}' --output table

Si desea agregar un filtro, la sintaxis cambia. Observe cómo en este ejemplo se ajusta el valor del --query parámetro entre comillas dobles ("...") y se usa un carácter de escape de barra diagonal inversa (\). Este script no se ejecuta en PowerShell.

 az storage account list --query "[?creationTime >='2024-02-01'].{\"SA Name\":name,\"Primary endpoint\":primaryEndpoints.blob}" --output table

Si acaba de intentar ejecutar la sintaxis de filtro en un entorno de PowerShell, recibió el mensaje argument --query: invalid jmespath_type value: "[?creationTime >=..."de error . Sin embargo, en Bash dentro de un entorno de Linux, la salida es similar a esta:

SA Name           Primary Endpoint
-----------       -----------------
msdocssa00000000  https://msdocssa000000000.blob.core.windows.net/

Paso de parámetros en una dirección URL que contiene una cadena de consulta

Las marcas de interrogación en direcciones URL indican el final de la dirección URL y el principio de una cadena de consulta. Este es un ejemplo que abre el paso 3 en Learn para usar la CLI de Azure:

https://learn.microsoft.com/en-us/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

El ?view=azure-cli-2020-09-01-hybrid resultado es la versión deseada del contenido de referencia de la CLI de Azure.

Al ejecutar comandos de la CLI de Azure en un entorno de PowerShell, PowerShell permite que los signos de interrogación formen parte de un nombre de variable. Esto podría crear confusión en los valores de parámetros de la CLI de Azure.

Este es un ejemplo del artículo Uso de la API REST de Azure:

Observe cómo $containerRegistryName?api-version concatena juntos sin errores en Bash.

# Script for a Bash environment

# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
subscriptionId="00000000-0000-0000-0000-000000000000"
resourceGroup="msdocs-app-rg$randomIdentifier"
containerRegistryName="msdocscr$randomIdentifier"

# prior to this GET example, the resource group and container registry were created in the article.

az rest --method get --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

Pasar parámetros que contienen un carácter especial de PowerShell

Hay caracteres especiales de PowerShell, como el símbolo At (@). Para ejecutar la CLI de Azure en PowerShell, agregue una barra ` trasera antes del carácter especial para escaparla. También puede incluir el valor entre comillas simples (') o dobles (").

Los tres ejemplos siguientes funcionarán en PowerShell:

  • parameterName '@parameters.json
  • parameterName '@parameters.json'
  • parameterName "@parameters.json"

Este ejemplo no funcionará en PowerShell:

  • parameterName @parameters.json

Paso de parámetros que contienen JSON

Para argumentos complejos como una cadena JSON, el procedimiento recomendado es usar la convención de la CLI de @<file> Azure para cargar desde un archivo para omitir la interpretación del shell. Tenga en cuenta que el símbolo At (@) es un operador de expansión en PowerShell, por lo que se debe citar.

Hay buenos ejemplos en az ad app create que contienen tanto el contenido del archivo JSON como los ejemplos de comandos. Este es un fragmento de código:

# Script for a Bash environment

az ad app create --display-name myTestAppName \
    --is-fallback-public-client \
    --required-resource-accesses @manifest.json

Pasar parámetros que contienen pares clave:valor

Algunos valores de parámetros de la CLI de Azure, como etiquetas de recursos de Azure, requieren pares clave:valor. Si o keyvalue contiene un espacio o un carácter especial, la sintaxis de Bash y PowerShell no siempre son las mismas.

Consulte Creación de etiquetas para practicar las diferencias entre comillas en el tutorial Learn to use the Azure CLI (Aprenda a usar la CLI de Azure). En este paso del tutorial se proporcionan ejemplos de Bash, PowerShell y Cmd para los siguientes escenarios de pares clave:valor:

  • espacios
  • valores vacíos
  • caracteres especiales
  • variables

Control de errores de la CLI de Azure en PowerShell

Puede ejecutar comandos de la CLI de Azure en PowerShell, como se indica en Selección de la herramienta de la línea de comandos de Azure adecuada. Si lo hace, asegúrese de que comprende el control de errores de la CLI de Azure en PowerShell. Más concretamente, la CLI de Azure no crea excepciones para que PowerShell las detecte.

Una alternativa consiste en usar la variable automática $?. Esta variable contiene el estado del comando más reciente. Si se produce un error en el comando anterior, $? tendrá el valor $False. Para obtener más información, vea about_Automatic_Variables.

En el ejemplo siguiente se muestra cómo esta variable automática puede funcionar para el control de errores:

# Script for a PowerShell environment

az group create --name MyResourceGroup
if ($? -eq $false) {
    Write-Error "Error creating resource group."
}

Se produce un error en el comando az porque falta el parámetro --location necesario. La instrucción condicional encuentra que $? es false y escribe un error.

Si desea usar las palabras clave try y catch, puede usar throw para crear una excepción para que el bloque try la detecte:

# Script for a PowerShell environment

$ErrorActionPreference = "Stop"
try {
    az group create --name MyResourceGroup
    if ($? -eq $false) {
        throw 'Group create failed.'
    }
}
catch {
    Write-Error "Error creating the resource group."
}
$ErrorActionPreference = "Continue"

De forma predeterminada, PowerShell detecta solo los errores de terminación. En este ejemplo se establece la variable global $ErrorActionPreference en Stop para que PowerShell pueda controlar el error.

La instrucción condicional prueba la variable $? para ver si se ha producido un error en el comando anterior. Si es así, la palabra clave throw crea una excepción para detectar. El bloque catch se puede usar para escribir un mensaje de error o controlar este.

En el ejemplo se restaura $ErrorActionPreference a su valor predeterminado.

Para más información sobre el control de errores de PowerShell, consulte Todo lo que quiso saber sobre las excepciones.

Habilitar la finalización de pestañas en PowerShell

La finalización de pestañas, también conocido como "Finalizadores de la Interfaz de la línea de comandos de Azure", proporciona completado en las entradas para proporcionar pistas, permitir el descubrimiento y acelerar la entrada de entradas. Los nombres de comandos, grupos de comandos, parámetros y determinados valores de parámetros pueden insertarse automáticamente en la línea de comandos pulsando la tecla Tabulador.

El tabulador está activado por defecto en Azure Cloud Shell y en la mayoría de las distribuciones de Linux. A partir de la versión 2.49 de la Interfaz de la línea de comandos de Azure, puede habilitar la finalización de pestañas para Azure CLI en PowerShell. Siga estos pasos:

  1. Crear o editar el perfil almacenado en la variable $PROFILE. La manera más sencilla es ejecutar notepad $PROFILE en PowerShell. Para obtener más información, vea Cómo crear el perfil y Los perfiles y la directiva de ejecución.

  2. Agregue el siguiente código a su perfil PowerShell:

    Register-ArgumentCompleter -Native -CommandName az -ScriptBlock {
    param($commandName, $wordToComplete, $cursorPosition)
    $completion_file = New-TemporaryFile
    $env:ARGCOMPLETE_USE_TEMPFILES = 1
    $env:_ARGCOMPLETE_STDOUT_FILENAME = $completion_file
    $env:COMP_LINE = $wordToComplete
    $env:COMP_POINT = $cursorPosition
    $env:_ARGCOMPLETE = 1
    $env:_ARGCOMPLETE_SUPPRESS_SPACE = 0
    $env:_ARGCOMPLETE_IFS = "`n"
    $env:_ARGCOMPLETE_SHELL = 'powershell'
    az 2>&1 | Out-Null
    Get-Content $completion_file | Sort-Object | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
    }
    Remove-Item $completion_file, Env:\_ARGCOMPLETE_STDOUT_FILENAME, Env:\ARGCOMPLETE_USE_TEMPFILES, Env:\COMP_LINE, Env:\COMP_POINT, Env:\_ARGCOMPLETE, Env:\_ARGCOMPLETE_SUPPRESS_SPACE, Env:\_ARGCOMPLETE_IFS, Env:\_ARGCOMPLETE_SHELL
}

  3. Para mostrar todas las opciones disponibles en el menú, agregue Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete al perfil de PowerShell.

Consulte también