Saiba mais sobre 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 (Cmd) do Windows. No entanto, há diferenças de script subtil. Nesta etapa do tutorial, saiba como criar sua primeira Conta de Armazenamento do Azure e formatar valores de parâmetro para os três ambientes.

Pré-requisitos

  • Você completou os pré-requisitos para preparar seu ambiente.
  • Você tem acesso a um grupo de recursos com contributor ou permissões superiores 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 é escrita e testada em Bash usando o Azure Cloud Shell. Uma das primeiras coisas a lembrar ao copiar a sintaxe da CLI do Azure é verificar os caracteres de continuação de linha para o ambiente escolhido, pois eles não são intercambiáveis.

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

Gorjeta

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

Compreender 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 utilização Bash PowerShell Cmd
Criar variável variableName=varValue $variableName="varValue" definir variableName=varValue
Usar variável como valor de parâmetro nomevariável $variableName %variableName%
Usar variável no --query parâmetro '$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: eco $varResourceGroup
  • PowerShell: eco $varResourceGroup
  • Cmd: eco %varResourceGroup%

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

Saiba mais sobre como citar 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âmetros.

Valor da cadeia de caracteres CLI do Azure PowerShell Cmd
Texto 'texto' ou 'texto' 'texto' ou 'texto' "texto"
Número \'50\' ''50'' '50'
Boolean \'verdadeiro\' ''falso'' 'verdadeiro'
Date '2021-11-15' '2021-11-15' '2021-11-15'
JSON '{"key":"value"}' ou "{"key":"value"}" '{"chave":"valor"}' "{"chave":"valor"}"

Muitos parâmetros da CLI do Azure aceitam uma lista de valores separada por espaço. Isso impacta a citação.

  • Lista separada por espaços entre aspas: --parameterName firstValue secondValue
  • Lista separada por espaços entre 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 seu console ou use --debug conforme explicado em Depurar comandos de referência da CLI do Azure.

Crie uma conta de armazenamento para aplicar o que 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 seu 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, consulte Visão geral da conta de armazenamento para regras de nome de conta de armazenamento.

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

  • Continuação da linha
  • Uso 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"
}

Crie tags para praticar diferenças de cotação

Usando az storage account update, adicione tags para ajudá-lo a identificar sua conta de armazenamento e aprender sobre como cotar diferenças. Estes exemplos de script demonstram sintaxe específica do ambiente para o seguinte:

  • Valores que contêm espaços
  • Citação de espaços em branco
  • Escapando de caracteres especiais
  • Usando variáveis

O --tags parâmetro aceita uma lista separada por espaços de pares chave:valor. Substitua <msdocs-tutorial-rg-00000000> pelo nome do seu 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 tags anteriores enquanto trabalha nesta etapa do tutorial, use o comando az tag update definindo o --operation parâmetro 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

Compare scripts mais específicos do ambiente

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

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

Exemplo de um parâmetro que contém uma cadeia de caracteres JSON. Este script é fornecido para referência futura, pois não estamos trabalhando neste az rest 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 é fornecido 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 booleano 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

Parâmetro de utilização --debug

A CLI do Azure oferece um --debug parâmetro 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 os testes.

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

Este exemplo está correto no Bash e no PowerShell.

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

Veja o que a CLI do Azure está interpretando na Command arguments linha 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 os testes.

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

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

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

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

Comando Usar echo

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

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

{"key":"value"}

Resolução de Problemas

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

  • "Mau pedido... {algo} é inválido" pode ser causado por um espaço, aspas simples ou duplas, ou falta de aspas.

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

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

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

  • "Argumentos não reconhecidos" geralmente são causados 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.

Obtenha mais detalhes

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

Assunto Mais informações
Diferenças de script Citação de Bash
Citação do PowerShell
Citando problemas com o PowerShell
Dicas de linha de comando do Windows
Parâmetros Usar aspas nos parâmetros da CLI do Azure
Encontre mais exemplos de sintaxe de Bash, PowerShell e Cmd na saída do comando Query usando JMESPath

Passo Seguinte

Agora que você aprendeu como 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