Compartilhar via

Considerações para executar a CLI do Azure em uma linguagem de script do PowerShell

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

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

  • 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ê não estiver familiarizado com a CLI, diferenciar entre uma ferramenta e uma linguagem de script pode ser confuso. Como escolher a ferramenta certa de linha de comando fornece uma boa comparação.

Pré-requisitos

Este artigo é destinado para você ler e aprender. No entanto, se você quiser executar os exemplos, selecione a Prepare your environments guia para instalar os idiomas de script usados neste artigo.

Importante

Quando você tiver um script da CLI do Azure que está produzindo um erro, considere como a linguagem de script em que você está trabalhando está analisando a sintaxe de 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 que contém um espaço, existem diferenças de citação entre sistemas operacionais e linguagens de scripts. Neste exemplo, use az storage account list e renomeie colunas de saída com uma palavra contendo um espaço.

Neste exemplo, observe o contorno de aspas simples ('...') com aspas duplas inseridas ("..."). 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 em 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ê apenas tentou executar a sintaxe de filtro em uma linguagem de script do PowerShell, recebeu uma mensagem argument --query: invalid jmespath_type value: "[?creationTime >=..."de erro. No entanto, no Bash em 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 no Learn para usar a CLI do Azure:

/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

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

Quando você executa comandos da CLI do Azure em uma linguagem de script do PowerShell, o PowerShell permite que os 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 concatena sem erro no 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

Passar parâmetros que contêm o símbolo de e comercial

Se você tiver um cenário em que precisa passar um e comercial em um valor de parâmetro, lembre-se de que o símbolo de e comercial (&) é interpretado pelo PowerShell. Você pode ver isso acontecer usando o --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

No entanto, se você usar esse mesmo teste para adicionar uma marca a um grupo de recursos, o escaramento no valor da marca não causará um erro.

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

Se você tiver um cenário em que o símbolo & em um valor de parâmetro está causando um erro, aqui estão algumas soluções:

# 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']

Passar parâmetros que contêm um símbolo at (@)

Há caracteres especiais do PowerShell, como o símbolo at (@) que é um operador de splatting 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

Aqui está outro exemplo no az ad app create comando: observe as aspas duplas ("...") em torno do nome do arquivo JSON necessário em uma linguagem de script do PowerShell.

# Script for a PowerShell scripting language

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

Passar parâmetros que contêm JSON

Para argumentos complexos como uma string JSON, a melhor prática é usar a convenção da CLI do @<file> Azure para carregar de um arquivo e evitar a interpretação do shell. Para obter exemplos de sintaxe JSON para Bash, PowerShell e Cmd.exe, consulte as diferenças entre linguagens de script – cadeias de caracteres JSON.

Passar parâmetros que contêm pares de chave e valor

Alguns valores de parâmetro da CLI do Azure, como tags de recurso do Azure, exigem pares chave:valor. Se o seu key ou value contiver um espaço ou caractere especial, a sintaxe Bash e PowerShell nem sempre serão iguais.

Para obter exemplos de sintaxe para Bash, PowerShell e Cmd, consulte Crie marcas para praticar as diferenças de aspas no tutorial Aprenda a usar o Azure CLI. Esta etapa do tutorial fornece exemplos para os seguintes cenários de par chave:valor:

  • Espaços
  • valores vazios
  • caracteres especiais
  • Variáveis

Símbolo de interrupção de análise

O símbolo de stop-parsing (--%), introduzido no PowerShell 3.0, orienta o PowerShell a não interpretar a entrada como comandos ou expressões do PowerShell. Quando o PowerShell encontra um símbolo de fim de análise, ele trata os caracteres restantes na linha como literais.

az --% vm create --name xxx

Tratamento de erros para a CLI do Azure no PowerShell

Você pode executar comandos da CLI do Azure no PowerShell, conforme descrito em Escolher a ferramenta de linha de comando certa do Azure. Se você fizer isso, certifique-se de entender o tratamento de erros da CLI do Azure no PowerShell. Em particular, a CLI do Azure não cria exceções para o PowerShell capturar.

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

O exemplo a seguir mostra como essa variável automática pode funcionar para tratamento de erros:

# Script for a PowerShell scripting language

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

O az comando falha porque está faltando o parâmetro necessário --location . A instrução condicional considera que $? é falsa e registra um erro.

Se você quiser usar as palavras-chave try e catch, poderá usar throw para criar uma exceção para o bloco try a ser capturado:

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

Por padrão, o PowerShell captura apenas erros de encerramento. Este exemplo define a $ErrorActionPreference variável global para Stop que o PowerShell possa lidar com o erro.

A instrução condicional testa a $? variável para ver se o comando anterior falhou. Nesse caso, a throw palavra-chave cria uma exceção a ser capturada. O catch bloco pode ser usado para gravar uma mensagem de erro ou manipular o erro.

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

Para obter mais informações sobre o tratamento de erros do PowerShell, consulte Tudo o que você queria saber sobre exceções.

Habilitar a conclusão automática com o uso da tecla Tab no PowerShell

O recurso de preenchimento automático, também conhecido como "completadores da CLI do Azure", permite completar entradas para fornecer dicas, habilitar a descoberta e acelerar a entrada. 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 completação por tab é habilitado por padrão no Azure Cloud Shell e na maioria das distribuições Linux. A partir da versão 2.49 da CLI do Azure, 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.

Consulte também

  • Last updated on