Considerações para executar a CLI do Azure em um ambiente do PowerShell

  • Artigo

A CLI do Azure é uma ferramenta para gerenciar recursos do Azure por meio de comandos de referência da CLI do Azure que são executados em um ambiente Bash e PowerShell. No entanto, há pequenas diferenças de sintaxe na formatação de parâmetros entre ambientes que podem resultar em resultados inesperados. O objetivo deste artigo é ajudá-lo a resolver erros de sintaxe da CLI do Azure ao trabalhar em um ambiente do PowerShell.

Este artigo compara as diferenças de sintaxe dos comandos da CLI do Azure executados nos seguintes ambientes:

  • Bash em execução em um sistema operacional Linux usando o Azure Cloud Shell.
  • PowerShell em execução em um sistema operacional Linux usando o Azure Cloud Shell.
  • Windows PowerShell em execução no Windows 11 usando o terminal do PowerShell 5.
  • PowerShell em execução em um Windows 11 usando o terminal do PowerShell 7.

Se você é novo na CLI, diferenciar entre uma ferramenta e um ambiente pode ser confuso. Como escolher a ferramenta de linha de comando certa fornece uma boa comparação.

Pré-requisitos

Este artigo destina-se a você ler e aprender. No entanto, se você quiser executar os exemplos, selecione a Prepare your environments guia para instalar os ambientes usados neste artigo.

Importante

Quando você tiver um script da CLI do Azure que está produzindo um erro, considere como o ambiente em que você está trabalhando está analisando a sintaxe do comando da CLI do Azure.

Passar espaços nos parâmetros da CLI do Azure

Na CLI do Azure, quando você precisa passar um valor de parâmetro contendo um espaço, há diferenças de cotação entre sistemas operacionais e ambientes. Neste exemplo, use az storage account list e renomeie colunas de saída com uma palavra contendo um espaço.

Neste exemplo, observe o wrapper de aspas simples ('...') com aspas duplas incorporadas ("..."). Este exemplo também funciona no PowerShell no Linux.

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

Se você quiser adicionar um filtro, a sintaxe será alterada. Observe como este exemplo encapsula o valor do --query parâmetro entre aspas duplas ("...") e usa um caractere de escape de barra invertida (\). Esse script não é executado no PowerShell.

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

Se você acabou de tentar executar a sintaxe de filtro em um ambiente do PowerShell, você recebeu a mensagem de argument --query: invalid jmespath_type value: "[?creationTime >=..."erro . No entanto, no Bash dentro de um ambiente Linux, sua saída é semelhante a esta:

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

Passar parâmetros em uma URL que contém uma cadeia de caracteres de consulta

Pontos de interrogação em URLs indicam o final da URL e o início de uma cadeia de caracteres de consulta. Aqui está um exemplo que abre a etapa 3 em Aprenda a usar a CLI do Azure:

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

Os ?view=azure-cli-2020-09-01-hybrid resultados na versão desejada do conteúdo de referência da CLI do Azure.

Quando você executa comandos da CLI do Azure em um ambiente do PowerShell, o PowerShell permite que pontos de interrogação façam parte de um nome de variável. Isso pode criar confusão nos valores de parâmetro da CLI do Azure.

Aqui está um exemplo do artigo Usar a API REST do Azure:

Observe como $containerRegistryName?api-version concatenas sem erro no 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

Passar parâmetros que contêm um caractere especial do PowerShell

Há caracteres especiais do PowerShell, como o símbolo At (@). Para executar a CLI do Azure no PowerShell, adicione um backtick ` antes do caractere especial para escapar dele. Você também pode colocar o valor entre aspas simples (') ou duplas (").

Os três exemplos a seguir funcionarão no PowerShell:

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

Este exemplo não funcionará no PowerShell:

  • parameterName @parameters.json

Passar parâmetros contendo JSON

Para argumentos complexos, como uma cadeia de caracteres JSON, a prática recomendada é usar a convenção da @<file> CLI do Azure para carregar de um arquivo para ignorar a interpretação do shell. Observe que o símbolo At (@) é um operador de splatting no PowerShell, portanto, ele deve ser citado.

Há bons exemplos no az ad app create que contêm conteúdo de arquivo JSON e exemplos de comando. Aqui está um snippet de código:

# Script for a Bash environment

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

Passar parâmetros contendo pares chave:valor

Alguns valores de parâmetro da CLI do Azure, como marcas de recurso do Azure, exigem pares chave:valor. Se o seu key ou value contém um espaço ou caractere especial, a sintaxe Bash e PowerShell nem sempre são as mesmas.

Consulte Criar marcas para praticar as diferenças de cotação no tutorial Aprenda a usar a CLI do Azure. Esta etapa do tutorial fornece exemplos para Bash, PowerShell e Cmd para os seguintes cenários de par chave:valor:

  • espaços
  • valores vazios
  • caracteres especiais
  • variáveis

Tratamento de erro para a CLI do Azure no PowerShell

É possível executar comandos da CLI do Azure no PowerShell, conforme descrito em Selecionar a ferramenta de linha de comando adequada do Azure. Nesse caso, verifique se você entendeu como funciona o tratamento de erro da CLI do Azure no PowerShell. A CLI do Azure não cria exceções de modo específico para o PowerShell detectar.

Uma alternativa é usar a variável $? automática. Essa variável contém o status do comando mais recente. Caso haja falha no comando anterior, $? terá o valor de $False. Para obter mais informações, confira about_Automatic_Variables.

O seguinte exemplo mostrará de que modo essa variável automática pode funcionar no tratamento de erro:

# Script for a PowerShell environment

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

Ocorre uma falha no comando az porque o parâmetro necessário --location está ausente. A instrução condicional identifica que $? é falsa e grava um erro.

Caso queira usar as palavras-chave try e catch, será possível usar throw a fim de criar uma exceção para o bloco try detectar:

# 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"

Por padrão, o PowerShell detecta somente os erros de encerramento. Este exemplo define a variável global $ErrorActionPreference para Stop, de modo que o PowerShell possa identificar o erro.

A instrução condicional testa a variável $? para conferir se houve falha no comando anterior. Em caso afirmativo, a palavra-chave throw cria uma exceção a ser detectada. O bloco catch pode ser usado para gravar uma mensagem de erro ou identificar o erro.

O exemplo restaura $ErrorActionPreference para o respectivo valor padrão.

Para obter mais informações sobre o tratamento de erro do PowerShell, confira Tudo o que você deseja saber sobre as exceções.

Habilitar o preenchimento de tabulação no PowerShell

Preenchimento de tabulação, também conhecido como "preenchedores da CLI do Azure" fornece preenchimento de entradas para fornecer dicas, habilitar a descoberta e acelerar a entrada de informações. Nomes de comando, nomes de grupo de comandos, parâmetros e determinados valores de parâmetro podem ser inseridos automaticamente na linha de comando pressionando a tecla Tab.

O recurso de preenchimento de tabulação está disponível por padrão no Azure Cloud Shell e na maioria das distribuições Linux. A partir da CLI do Azure versão 2.49, você pode habilitar o preenchimento de tabulação para a CLI do Azure no PowerShell. Siga estas etapas:

  1. Criar ou editar o perfil armazenado na variável $PROFILE. A maneira mais simples é executar notepad $PROFILE no PowerShell. Para obter mais informações, confira Como criar seu perfil e Perfis e política de execução.

  2. Adicione o seguinte código ao seu perfil do 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 exibir todas as opções disponíveis no menu, adicione Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete ao seu perfil do PowerShell.

Confira também