Compartir a través de

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

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.

Prerrequisitos

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, considere cómo el lenguaje de scripting que está utilizando interpreta la sintaxis de comandos de la CLI de Azure.

Pasa espacios en los parámetros de la CLI de Azure

En la CLI de Azure, cuando necesitas 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 uso de comillas simples ('...') que contienen 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 secuencias de comandos de PowerShell, recibió el mensaje de error argument --query: invalid jmespath_type value: "[?creationTime >=...". 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:

/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 ampersand

Si tiene un escenario en el que necesita pasar un símbolo ampersand ('&') en un valor de parámetro, tenga en cuenta que PowerShell interpreta el símbolo. 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 el ampersand en el valor de un parámetro está causando un error, hay 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 acento grave ` antes del carácter especial para excluirlo. 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:

  • nombreParámetro @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"

Pasar 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 ver ejemplos de sintaxis JSON para Bash, PowerShell y Cmd.exe, consulte Quoting differences between scripting languages - JSON strings ( Diferencias entre 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 key o value contiene un espacio o un carácter especial, la sintaxis de Bash y PowerShell no siempre es la misma.

Para obtener ejemplos de sintaxis para Bash, PowerShell y Cmd, consulte Cree etiquetas para practicar las diferencias entre comillas en el tutorial 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 parada 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 que detiene el procesamiento, PowerShell trata los caracteres restantes de la línea como un 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 describe en Elección de la herramienta de 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. En concreto, la CLI de Azure no crea excepciones para que PowerShell las capture.

Una alternativa es usar la $? variable automática. Esta variable contiene el estado del comando más reciente. Si se produce un error en el comando anterior, $? tiene el valor de $False. Para obtener más información, consulte sobre_Variables_Automáticas.

En el ejemplo siguiente se muestra cómo puede funcionar esta variable automática 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 az comando porque falta el parámetro necesario --location . La instrucción condicional determina que $? es falso y escribe un error.

Si desea usar las palabras clave try y catch, puede usar throw para crear una excepción que el bloque try pueda capturar.

# 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 errores de terminación. En este ejemplo se establece la $ErrorActionPreference variable global en Stop para que PowerShell pueda controlar el error.

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

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

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

Habilitar la finalización de pestañas en PowerShell

El autocompletado de comandos, también conocidos como "finalizadores de la CLI de Azure", permite completar inputs para proporcionar pistas, facilitar el descubrimiento y agilizar el ingreso de datos. 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 autocompletado mediante tabulador está habilitado de manera predeterminada 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