Como usar a extensão de alias da CLI do Azure

A extensão de alias permite que os usuários definam comandos personalizados para a CLI do Azure usando comandos existentes. Os aliases ajudam a manter seu fluxo de trabalho simples, permitindo atalhos. O mecanismo de modelo Jinja2 alimenta aliases da CLI do Azure e oferece processamento avançado de argumentos.

Instalar a extensão de alias

A versão mínima da CLI do Azure necessária para usar a extensão de alias é 2.0.28. Para verificar sua versão da CLI, execute az --version. Se você precisar atualizar sua instalação, siga as instruções em Instalar a CLI do Azure.

Instale a extensão de alias com o comando az extension add .

az extension add --name alias

Verifique a instalação da extensão com az extension list. Se a extensão de alias for instalada corretamente, ela aparecerá na saída do comando.

az extension list --output table --query '[].{Name:name}'

Name
------
alias

Manter a extensão do pseudônimo up-to-date

A extensão de alias está em desenvolvimento ativo e novas versões são lançadas regularmente. No entanto, novas versões não são instaladas quando você atualiza a CLI. Instale as atualizações da extensão com az extension update.

az extension update --name alias

Gerenciar aliases para a CLI do Azure

A extensão de alias permite que você crie e gerencie aliases para outros comandos da CLI. Para exibir todos os comandos disponíveis e detalhes do parâmetro, execute o comando alias com --help.

az alias --help

Criar comandos de alias simples

Um uso de aliases é para reduzir os grupos de comandos ou nomes de comando existentes. Por exemplo, você pode abreviar o grupo de comandos group para rg e o comando list para ls.

az alias create --name rg --command group
az alias create --name ls --command list

Agora você pode usar esses aliases recém-definidos em qualquer lugar em que suas definições se apliquem.

az rg list
az rg ls
az vm ls

Não inclua az como parte do comando alias.

Os aliases também podem ser atalhos para comandos completos. O próximo exemplo lista os grupos de recursos disponíveis e seus locais na saída da tabela:

az alias create --name ls-groups --command "group list --query '[].{Name:name, Location:location}' --output table"

Agora ls-groups pode ser executado como qualquer outro comando da CLI.

az ls-groups

Criar um comando de alias com argumentos

Você também pode adicionar argumentos posicionais a um comando de alias, incluindo-os como {{ arg_name }} no nome do alias. O espaço em branco dentro das chaves é necessário.

az alias create --name "alias_name {{ arg1 }} {{ arg2 }} ..." --command "invoke_including_args"

O alias de exemplo a seguir mostra como usar argumentos posicionais para obter o endereço IP público de uma VM.

az alias create \
    --name "get-vm-ip {{ resourceGroup }} {{ vmName }}" \
    --command "vm list-ip-addresses --resource-group {{ resourceGroup }} --name {{ vmName }}
        --query [0].virtualMachine.network.publicIpAddresses[0].ipAddress"

Ao executar esse comando, você dá valores aos argumentos posicionais.

az get-vm-ip MyResourceGroup MyVM

Você também pode usar as variáveis de ambiente em comandos com alias, que são avaliados em tempo de execução. O próximo exemplo adiciona o alias create-rg, que cria um grupo de recursos em eastus e adiciona uma tag owner. Essa tag recebe o valor da variável de ambiente local USER.

az alias create \
    --name "create-rg {{ groupName }}" \
    --command "group create --name {{ groupName }} --location eastus --tags owner=\$USER"

Para registrar variáveis de ambiente dentro do comando alias, você deve escapar do sinal de dólar ($).

Processar argumentos usando modelos Jinja2

Jinja2 executa a substituição de argumento na extensão de alias. Os modelos Jinja2 permitem manipular os argumentos.

Com modelos Jinja2, você pode escrever aliases que levam diferentes tipos de argumentos do que o comando subjacente. Por exemplo, você pode fazer um alias que usa uma URL de armazenamento. Em seguida, essa URL é analisada para passar os nomes da conta e do contêiner para o comando de armazenamento.

az alias create \
    --name 'storage-ls {{ url }}' \
    --command "storage blob list
        --account-name {{ url.replace('https://', '').split('.')[0] }}
        --container-name {{ url.replace('https://', '').split('/')[1] }}"

Para saber mais sobre o mecanismo de modelo Jinja2, consulte a documentação do Jinja2.

Arquivo de configuração do Alias

Outra maneira de criar e modificar aliases é alterar o arquivo de configuração de alias. As definições de comando do Alias são gravadas em um arquivo de configuração, localizado em $AZURE_CONFIG_DIR/alias. O valor AZURE_CONFIG_DIR padrão é $HOME/.azure no macOS e no Linux e %USERPROFILE%\.azure no Windows. O Arquivo de configuração de alias é escrito no formato de Arquivo de configuração INI. O formato para comandos de alias é:

[alias_name]
command = invoked_commands

Para aliases que têm argumentos posicionais, o formato para comandos de alias é:

[alias_name {{ arg1 }} {{ arg2 }} ...]
command = invoked_commands_including_args

Criar um comando de alias com argumentos por meio do arquivo de configuração de alias

O exemplo a seguir mostra um alias para um comando com argumentos. Esse comando obtém o endereço IP público de uma VM. Os comandos aliased devem estar em uma única linha e usar todos os argumentos no nome do alias.

[get-vm-ip {{ resourceGroup }} {{ vmName }}]
command = vm list-ip-addresses --resource-group {{ resourceGroup }} --name {{ vmName }} --query [0].virtualMachine.network.publicIpAddresses[0].ipAddress

Desinstalar a extensão de alias

Para desinstalar a extensão, use o comando az extension remove .

az extension remove --name alias

Se você desinstalou devido a um bug ou outro problema com a extensão, registre um problema no GitHub para que possamos fornecer uma correção.