Usar e gerenciar extensões com a CLI do Azure

A CLI do Azure oferece a capacidade de carregar extensões. As extensões para a CLI do Azure são caracterizadas como wheels do Python que não são enviadas como parte da CLI, mas executadas como comandos da CLI. Com as extensões, você recebe acesso a comandos experimentais e de pré-lançamento, juntamente com a capacidade de escrever suas próprias interfaces de CLI. Este artigo aborda como gerenciar extensões e responde a perguntas comuns sobre seu uso.

Como localizar extensões

Para ver as extensões da CLI do Azure fornecidas e mantidas pela Microsoft, use o comando az extension list-available.

az extension list-available --output table

Também hospedamos uma lista de extensões no site de documentação.

Como instalar extensões

Instalar extensões manualmente

Depois de encontrar uma extensão para instalar, use az extension add para obtê-la. Se a extensão estiver listada em az extension list-available, é possível instalar a extensão pelo nome.

az extension add --name <extension-name>

Se a extensão for de um recurso externo ou se você tiver um link direto para ela, forneça a URL de origem ou o caminho local. A extensão deve ser um arquivo wheel Python compilado.

az extension add --source <URL-or-path>

Você também pode criar um índice de extensão particular seguindo o formato em index.jsone depois definir a URL do índice de extensão usada pela CLI do Azure da versão 2.20.0 em diante. Depois disso, é possível instalar a extensão por nome do índice de extensão particular.

az config set extension.index_url=<URL>
az extension add --name <extension-name>

Depois de instalada, a extensão pode ser encontrada no valor da variável do shell $AZURE_EXTENSION_DIR. Se essa variável tiver sua definição removida, por padrão, o valor é $HOME/.azure/cliextensions no Linux e macOS e %USERPROFILE%\.azure\cliextensions no Windows.

Instalar extensões automaticamente

Quando você executa um comando de extensão que não está instalado, a CLI do Azure pode reconhecer o comando executado e instalar automaticamente a extensão para você da versão 2.10.0 em diante. Esse recurso, conhecido como instalação dinâmica, é habilitado por padrão desde a versão 2.12.0. Você também pode habilitá-lo por meio da configuração de versões anteriores com suporte.

az config set extension.use_dynamic_install=yes_prompt

Use o comando de configuração a seguir para habilitar a instalação dinâmica sem um prompt.

az config set extension.use_dynamic_install=yes_without_prompt

Use o comando de configuração a seguir para desligar o recurso de instalação dinâmica e reverter para o comportamento padrão. O comando de extensão retornará um erro de comando não encontrado se a extensão não estiver instalada.

az config set extension.use_dynamic_install=no

Por padrão, um comando de extensão que solicita a instalação dinâmica continuará sendo executado depois que a extensão for instalada. Definindo a propriedade run_after_dynamic_install como no, você pode alterar o comportamento padrão e fazer o comando sair sem executar novamente.

az config set extension.run_after_dynamic_install=no

Como atualizar extensões

Se uma extensão tiver sido instalada pelo nome, atualize-a usando az extension update.

az extension update --name <extension-name>

Caso contrário, uma extensão poderá ser atualizada a partir da origem seguindo as instruções em Instalar extensões.

Se você não puder usar a CLI para resolver um nome de extensão, desinstale-a e tente reinstalá-la. A extensão também pode ter se tornado parte da CLI base. Tente atualizar a CLI conforme descrito em Instalar a CLI do Azure e verifique se os comandos da extensão foram adicionados.

Como desinstalar extensões

Se você já não precisar de uma extensão, remova-a com az extension remove.

az extension remove --name <extension-name>

Também é possível remover uma extensão manualmente, excluindo-a do local onde foi instalada. A variável do shell $AZURE_EXTENSION_DIR define onde os módulos são instalados. Se essa variável tiver sua definição removida, por padrão, o valor é $HOME/.azure/cliextensions no Linux e macOS e %USERPROFILE%\.azure\cliextensions no Windows.

rm -rf $AZURE_EXTENSION_DIR/<extension-name>

Perguntas frequentes

Aqui estão algumas respostas para outras perguntas comuns sobre extensões da CLI.

Quais formatos de arquivo são permitidos para instalação?

Atualmente, apenas wheels compilados do Python podem ser instalados como extensões.

As extensões podem substituir os comandos existentes?

Sim. As extensões podem substituir os comandos existentes, mas antes de executar um comando que foi substituído, a CLI emite um aviso.

Como posso saber se uma extensão está em pré-lançamento?

A documentação e o controle de versão de uma extensão mostram se ela está em pré-lançamento. Geralmente, a Microsoft lança comandos de visualização como extensões da CLI, com a opção de movê-los para o produto principal da CLI posteriormente. Quando os comandos são removidos das extensões, a extensão antiga deve ser desinstalada.

As extensões podem depender umas das outras?

Não. Como a CLI não garante uma ordem de carga, as dependências não poderão ser atendidas. Remover uma extensão não afetará outras extensões.

As extensões são atualizadas juntamente com a CLI?

Não. As extensões devem ser atualizadas separadamente, conforme descrito em Atualizar extensões.

Como desenvolver sua própria extensão?

Confira o repositório oficial para receber mais ajuda. Azure/azure-cli-extensions