Conheça as diferenças de sintaxe da CLI do Azure em Bash, PowerShell e Cmd

  • Artigo

Os comandos da CLI do Azure podem ser executados em ambientes Bash, PowerShell e shell de comando do Windows (Cmd). No entanto, há diferenças de script de subtile. Nesta etapa do tutorial, saiba como criar sua primeira Conta de Armazenamento do Azure e formatar valores de parâmetro para todos os três ambientes.

Pré-requisitos

  • Você concluiu os pré-requisitos para preparar seu ambiente.
  • Você tem acesso a um grupo de recursos com permissões contributor ou mais altas em um nível de grupo de recursos.

Esteja ciente dos caracteres de continuação de linha

A maioria da documentação da CLI do Azure é gravada e testada no Bash usando o Azure Cloud Shell. Uma das primeiras coisas a lembrar ao copiar a sintaxe da CLI do Azure é verificar se os caracteres de continuação de linha para o ambiente escolhido não são intercambiáveis.

Ambiente Caractere de continuação de linha
Bash Barra invertida (\)
PowerShell Backtick (`)
Cmd Carrot (^)

Dica

O botão Copiar no canto superior direito dos blocos de código da CLI do Azure remove a barra invertida (\) e o caractere de acento grave (`) por design. Se você quiser copiar um bloco de código formatado, use o teclado ou o mouse para selecionar e copiar o exemplo.

Entender as diferenças de sintaxe ao usar variáveis

A sintaxe para usar variáveis varia ligeiramente entre ambientes. Aqui está uma comparação:

Caso de uso Bash PowerShell Cmd
Criar variável variableName=varValue $variableName="varValue" set variableName=varValue
Usar variável como valor de parâmetro variableName $variableName %variableName%
Usar variável no parâmetro --query '$variableName' '$variableName' '$variableName'

Há várias maneiras diferentes de retornar informações variáveis para a tela do console, mas echo funciona na maioria das circunstâncias. Aqui está uma comparação:

  • Bash: echo $varResourceGroup
  • PowerShell: echo $varResourceGroup
  • Cmd: echo %varResourceGroup%

Na etapa três, Preencher variáveis para uso em scripts, você trabalha com exemplos aprofundados de sintaxe variável.

Saiba mais sobre as diferenças entre ambientes

Cada parâmetro da CLI do Azure é uma cadeia de caracteres. No entanto, cada ambiente tem suas próprias regras para lidar com aspas simples e duplas, espaços e valores de parâmetro.

Valor da cadeia de caracteres CLI do Azure PowerShell Cmd
Texto 'texto' ou "texto" 'texto' ou "texto" "texto"
Número \`50\` ``50`` `50`
Booliano \`true\` ``false`` 'true'
Data '2021-11-15' '2021-11-15' '2021-11-15'
JSON '{"key":"value"}' or "{"key":"value"}" '{"key":"value"}' "{"key":"value"}"

Muitos parâmetros da CLI do Azure aceitam uma lista de valores separada por espaço. Isso afeta aspas.

  • Lista separada por espaço sem aspas: --parameterName firstValue secondValue
  • Lista separada por espaço com aspas: --parameterName "firstValue" "secondValue"
  • Valores que contêm um espaço: --parameterName "value1a value1b" "value2a value2b" "value3"

Se você não tiver certeza de como sua cadeia de caracteres será avaliada pelo seu ambiente, retorne o valor de uma cadeia de caracteres para o console ou use --debug conforme explicado nos Comandos de referência de depuração da CLI do Azure.

Criar uma conta de armazenamento para aplicar o que você aprendeu

O restante desta etapa do tutorial demonstra as regras de citação nos comandos da CLI do Azure e usa o grupo de recursos criado em Preparar seu ambiente para a CLI do Azure. Substitua <msdocs-tutorial-rg-00000000> pelo nome do grupo de recursos.

Crie uma conta de armazenamento do Azure para usar neste tutorial. Este exemplo atribui uma ID aleatória ao nome da conta de armazenamento, mas se você quiser usar um nome diferente, confira a Visão geral da conta de armazenamento para as regras de nome da conta de armazenamento.

Este próximo exemplo de script demonstra a sintaxe específica do ambiente para o seguinte:

  • Continuação de linha
  • Uso de variável
  • Identificadores aleatórios
  • Comando echo
# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
location=eastus
resourceGroup="<msdocs-tutorial-rg-00000000>"
storageAccount="msdocssa$randomIdentifier"

# Create a storage account.
echo "Creating storage account $storageAccount in resource group $resourceGroup"
az storage account create --name $storageAccount \
                          --resource-group $resourceGroup \
                          --location $location \
                          --sku Standard_RAGRS \
                          --kind StorageV2 \
                          --output json

A CLI do Azure retorna mais de 100 linhas de JSON como saída quando uma nova conta de armazenamento é criada. A saída do dicionário JSON a seguir tem campos omitidos para brevidade.

{
"accessTier": "Hot",
"allowBlobPublicAccess": false,
"creationTime": "yyyy-mm-ddT19:14:26.962501+00:00",
"enableHttpsTrafficOnly": true,
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ msdocs-tutorial-rg-00000000/providers/Microsoft.Storage/storageAccounts/msdocssa00000000",
"keyCreationTime": {
  "key1": "yyyy-mm-ddT19:14:27.103127+00:00",
  "key2": "yyyy-mm-ddT19:14:27.103127+00:00"
},
"kind": "StorageV2",
"location": "eastus",
"name": "msdocssa00000000",
"primaryEndpoints": {
  "blob": "https://msdocssa00000000.blob.core.windows.net/"
},
"primaryLocation": "eastus",
"provisioningState": "Succeeded",
"resourceGroup": "msdocs-tutorial-rg-00000000",
"sku": {
  "name": "Standard_RAGRS",
  "tier": "Standard"
},
"statusOfPrimary": "available",
"statusOfSecondary": "available",
"tags": {},
"type": "Microsoft.Storage/storageAccounts"
}

Criar marcas para praticar as diferenças entre aspas

Usando az storage account update, adicione marcas para ajudar você a identificar sua conta de armazenamento e saiba mais sobre os diferentes usos de aspas. Esses exemplos de script demonstram a sintaxe específica do ambiente para o seguinte:

  • Valores que contêm espaços
  • Citando espaços em branco
  • Caracteres especiais de escape
  • Usando variáveis

O parâmetro --tags aceita uma lista separada por espaço de pares chave:valor. Substitua <msdocs-tutorial-rg-00000000> pelo nome do grupo de recursos e <msdocssa00000000> pelo nome da sua conta de armazenamento do Azure.

# Create new tags. This syntax works with or without quotes around each key-value pair.
az storage account update --name <msdocssa00000000> \
                          --resource-group <msdocs-tutorial-rg-00000000> \
                          --tags Team=t1 Environment=e1

# Create new tags containing spaces. You must use quotes.
az storage account update --name <msdocssa00000000> \
                          --resource-group <msdocs-tutorial-rg-00000000> \
                          --tags "Floor number=f1" "Cost center=cc1"

# Create a new tag with an empty value.
az storage account update --name <msdocssa00000000> \
                          --resource-group <msdocs-tutorial-rg-00000000> \
                          --tags "Department="''""

# Create a new tag containing special characters resulting in "Path": "$G:\\myPath".
az storage account update --name <msdocssa00000000> \
                          --resource-group <msdocs-tutorial-rg-00000000> \
                          --tags "Path=\$G:\myPath"

# Create a tag from a variable.
newTag="tag1=tag value with spaces"
az storage account update --name <msdocssa00000000> \
                          --resource-group <msdocs-tutorial-rg-00000000> \
                          --tags "$newTag"

Se você não quiser substituir as marcas anteriores enquanto trabalha nesta etapa do tutorial, use o comando az tag update definindo o parâmetro --operation como merge.

# Get the resource ID of your storage account.
saID=$(az resource show --resource-group <msdocs-tutorial-rg-00000000> \
                        --name <msdocssa00000000> \
                        --resource-type Microsoft.Storage/storageAccounts \
                        --query "id" \
                        --output tsv)

echo My storage account ID is $saID

# Append new tags.
az tag update --resource-id $saID \
              --operation merge \
              --tags <tagName>=<tagValue>

# Get a list of all tags.
az tag list --resource-id $saID

Comparar scripts mais específicos do ambiente

Dê uma olhada mais profunda nessas diferenças de script. Estes exemplos demonstram diferenças entre aspas para o seguinte:

  • Passar uma cadeia de caracteres JSON como um valor de parâmetro
  • Filtrar resultados com o parâmetro --query
    • Números
    • Valores boolianos
    • Datas

Exemplo de um parâmetro que contém uma cadeia de caracteres JSON. Este script é dado para referência futura, pois não estamos trabalhando com az rest neste tutorial.

az rest --method patch \
        --url https://management.azure.com/subscriptions/<mySubscriptionID>/resourceGroups/<myResourceGroup>/providers/Microsoft.HybridCompute/machines/<machineName>?api-version=yyyy-mm-dd-preview \
        --resource https://management.azure.com/ \
        --headers Content-Type=application/json \
        --body '{"properties": {"agentUpgrade": {"enableAutomaticUpgrade": false}}}'

Exemplo de filtragem para um valor numérico. A menos que você tenha uma VM em sua assinatura atual, este exemplo será dado para referência futura.

az vm list --resource-group <myResourceGroup> \
           --query "[?storageProfile.osDisk.diskSizeGb >=\`50\`].{Name:name, admin:osProfile.adminUsername, DiskSize:storageProfile.osDisk.diskSizeGb}" \
           --output table

Exemplo de filtragem de um valor booliano usando a conta de armazenamento criada neste tutorial.

az storage account list --resource-group <msdocs-tutorial-rg-00000000> \
    --query "[?allowBlobPublicAccess == \`true\`].id"

Exemplos de filtragem de uma data usando a conta de armazenamento criada neste tutorial.

# include time
az storage account list --resource-group <msdocs-tutorial-rg-00000000> \
    --query "[?creationTime >='2021-11-15T19:14:27.103127+00:00'].{saName:name, saID: id, sku: sku.name}"

# exclude time
az storage account list --resource-group <msdocs-tutorial-rg-00000000> \
    --query "[?creationTime >='2021-11-15'].{saName:name, saID: id, sku: sku.name}"

# subtract days and use a variable
saDate=$(date +%F -d "-30days")
az storage account list --resource-group <msdocs-tutorial-rg-00000000> \
    --query "[?creationTime >='$saDate'].{saName:name, saID: id, sku: sku.name}"

Depurar comandos de referência da CLI do Azure

Usar parâmetro --debug

A CLI do Azure oferece um parâmetro --debug que pode ser usado com qualquer comando. A saída de depuração é extensa, mas fornece mais informações sobre erros de execução. Use o comando Bash clear para remover a saída do console entre testes.

Esses exemplos revelam os argumentos reais recebidos pela CLI do Azure na sintaxe do Python.

Este exemplo está correto no Bash e no PowerShell.

az '{"key":"value"}' --debug

Veja o que a CLI do Azure está interpretando na linha Command arguments da saída.

Command arguments: ['{"key":"value"}', '--debug']

Este segundo exemplo também está correto. Use o comando Bash clear para remover a saída do console entre testes.

clear
az "{\"key\":\"value\"}" --debug

Command arguments: ['{"key":"value"}', '--debug']

Esses dois exemplos seguintes estão incorretos, pois aspas e espaços são interpretados pelo Bash.

Formato incorreto Problema Saída do console
az {"key":"value"} --debug Aspas simples ausentes ou caracteres de escape Argumentos de comando: ['{key:value}', '--debug']
az {"key": "value"} --debug Aspas simples ausentes ou caracteres de escape e contém espaço extra Argumentos de comando: ['{key:', 'value}', '--debug']

Usar o comando echo

Embora --debug informe exatamente o que a CLI do Azure está interpretando, uma segunda opção é retornar o valor de uma expressão ao console. Esse método é útil ao verificar os resultados de --query que são abordados detalhadamente em Variáveis de população para uso em scripts.

strExpression='{"key":"value"}'
echo $strExpression

{"key":"value"}

Solução de problemas

Aqui estão erros comuns quando uma sintaxe de comando de referência da CLI do Azure não é escrita corretamente:

  • "Solicitação incorreta... {something} é inválido" pode ser causado por um espaço, uma aspa única ou dupla ou falta de uma aspa.

  • "Token inesperado..." é visto quando há um espaço extra ou aspas.

  • O erro "Valor de jmespath_type inválido" geralmente vem de aspas incorretas no parâmetro --query.

  • "A referência de variável não é válida" é recebida quando uma cadeia de caracteres não é formatada corretamente com frequência devido à concatenação ou a um caractere de escape ausente.

  • "Argumentos não reconhecidos" geralmente é causado por um caractere de continuação de linha incorreto.

  • "Expressão ausente após operador unário" é visto quando um caractere de continuação de linha está ausente.

Obter mais detalhes

Deseja obter mais detalhes sobre um dos assuntos abordados nesta etapa do tutorial? Use os links nesta tabela para saber mais.

Assunto Saiba mais
Diferenças de script Aspas no Bash
Aspas no PowerShell
Problemas no uso de aspas com o PowerShell
Dicas de linha de comando do Windows
Parâmetros Usar aspas em parâmetros na CLI do Azure
Encontre mais exemplos de sintaxe de Bash, PowerShell e Cmd na saída do comando Query usando JMESPath

Próxima Etapa

Agora que você aprendeu a escrever a sintaxe da CLI do Azure para Bash, PowerShell e Cmd, prossiga para a próxima etapa para saber como extrair valores para uma variável.

Preencher variáveis para uso em scripts