Compartir a través de

Consideraciones para ejecutar la CLI de Azure en un lenguaje de scripting de PowerShell

  • Artículo

La CLI de Azure es una herramienta para administrar recursos de Azure a través de comandos de referencia de la CLI de Azure que se ejecutan en un lenguaje de scripting de Bash y PowerShell. Sin embargo, hay pequeñas diferencias de sintaxis en el formato de parámetros entre los lenguajes de scripting 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 lenguaje de scripting de PowerShell.

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

  • 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 lenguaje de scripting puede 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 lenguajes de scripting 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 lenguaje de scripting 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, existen diferencias entre los sistemas operativos y los lenguajes de scripting. 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 lenguaje de scripting 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/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 lenguaje de scripting 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 scripting language

# 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 el símbolo de la amperada

Si tiene un escenario en el que necesita pasar una amperada en un valor de parámetro, tenga en cuenta que PowerShell interpreta el símbolo de la y comercial (&). Puede ver que esto sucede mediante el --debug parámetro :

az "a&b" --debug

# output
'a' is misspelled or not recognized by the system.
'b' is not recognized as an internal or external command

Sin embargo, si usa esta misma prueba para agregar una etiqueta a un grupo de recursos, el ampersand del valor de etiqueta no produce un error.

az group create --location eastus2 --name "msdocs-rg-test"
az group update --name "msdocs-rg-test" --tags "company name=Contoso & Sons"

# output
{
  "id": "/subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourceGroups/msdocs-rg-test",
  "location": "eastus2",
  "managedBy": null,
  "name": "msdocs-rg-test",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": {
    "company name": "Contoso & Sons"
  },
  "type": "Microsoft.Resources/resourceGroups"
}

Si tiene un escenario en el que ampersand en un valor de parámetro está causando un error, estas son algunas soluciones:

# When quoted by single quotes ('), double quotes (") are preserved by PowerShell and sent
# to Command Prompt, so that ampersand (&) is treated as a literal character
> az '"a&b"' --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") with backticks (`) as required by PowerShell
> az "`"a&b`"" --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") by repeating them
> az """a&b""" --debug
Command arguments: ['a&b', '--debug']

# With a whitespace in the argument, double quotes (") are preserved by PowerShell and
# sent to Command Prompt
> az "a&b " --debug
Command arguments: ['a&b ', '--debug']

# Use --% to stop PowerShell from parsing the argument
> az --% "a&b" --debug
Command arguments: ['a&b', '--debug']

Pasar parámetros que contienen un símbolo at (@)

Hay caracteres especiales de PowerShell, como el símbolo at (@), que es un operador de expansión en PowerShell. Agregue un verso ` antes del carácter especial para escaparlo. 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

Este es otro ejemplo del az ad app create comando: observe las comillas dobles ("...") alrededor del nombre de archivo JSON necesario en un lenguaje de scripting de PowerShell.

# Script for a PowerShell scripting language

az ad app create --display-name myTestAppName `
    --is-fallback-public-client `
    --required-resource-accesses "@manifest.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. Para obtener ejemplos de sintaxis JSON para Bash, PowerShell y Cmd.exe, consulte Diferencias entre los lenguajes de scripting: cadenas 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 key value contiene un espacio o un carácter especial, la sintaxis de Bash y PowerShell no siempre son las mismas.

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

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

Símbolo de detención del análisis

El símbolo de detención del análisis (--%), introducido en PowerShell 3.0, dirige PowerShell para evitar interpretar la entrada como comandos o expresiones de PowerShell. Cuando encuentra un símbolo de detención del análisis, PowerShell trata los caracteres restantes de la línea como literal.

az --% vm create --name xxx

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 scripting language

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 scripting language

$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