Utilizar e gerir extensões com a CLI do Azure

A CLI do Azure oferece a capacidade de carregar extensões. As extensões da CLI do Azure são caracterizadas como rodas Python que não são enviadas como parte da CLI, mas que são executadas como comandos da CLI. Com as extensões, obtém acesso a comandos experimentais e de pré-lançamento, juntamente com a capacidade de escrever as suas próprias interfaces da CLI. Este artigo descreve como gerir as extensões e responde a perguntas comuns sobre a utilização das mesmas.

Como localizar extensões

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

az extension list-available --output table

O site de documentação também aloja uma lista de extensões.

Como instalar extensões

Instalar extensões manualmente

Depois de encontrar uma extensão para instalar, utilize az extension add para obtê-la. Se a extensão estiver listada em az extension list-available, pode instalar a extensão pelo nome.

az extension add --name <extension-name>

Se a extensão for proveniente de um recurso externo ou se tiver uma ligação direta para a mesma, forneça o URL de origem ou o caminho local. A extensão tem de ser um ficheiro wheel compilado para Python.

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

Também pode criar um índice de extensão privada seguindo o formato em index.json e, em seguida, definir o URL do índice de extensões utilizado pela CLI do Azure para o mesmo a partir da versão 2.20.0. Depois disso, pode instalar a extensão por nome a partir do índice de extensão privada.

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

Quando a extensão estiver instalada, pode encontrá-la abaixo do valor da variável de shell $AZURE_EXTENSION_DIR. Se esta variável não estiver definida, então, por predefinição, o valor é $HOME/.azure/cliextensions, no Linux e macOS, e %USERPROFILE%\.azure\cliextensions no Windows.

Instalar extensões automaticamente

Quando executa um comando de extensão que não está instalado, a CLI do Azure consegue reconhecer o comando que executa e instalar automaticamente a extensão a partir da versão 2.10.0. Esta funcionalidade, denominada instalação dinâmica, está ativada por predefinição desde 2.12.0. Também pode ativá-lo através da configuração para versões suportadas anteriores.

az config set extension.use_dynamic_install=yes_prompt

Utilize o seguinte comando de configuração para ativar a instalação dinâmica sem um pedido.

az config set extension.use_dynamic_install=yes_without_prompt

Utilize o seguinte comando de configuração para desativar a funcionalidade de instalação dinâmica para reverter para o comportamento predefinido. O comando da extensão devolve um erro de comando não encontrado se a extensão não estiver instalada.

az config set extension.use_dynamic_install=no

Por predefinição, um comando de extensão que pede a instalação dinâmica continuará a ser executado após a instalação da extensão. Pode alterar o comportamento predefinido e fazer com que o comando saia sem uma nova execução ao definir a run_after_dynamic_install propriedade como no.

az config set extension.run_after_dynamic_install=no

Como atualizar extensões

Se instalar uma extensão por nome, atualize-a com az extension update.

az extension update --name <extension-name>

Caso contrário, uma extensão pode ser atualizada a partir da origem ao seguir as instruções apresentadas em Instalar as extensões.

Se não conseguir utilizar a CLI para resolver um nome de extensão, desinstale-o e tente reinstalar. A extensão também poderá ter sido integrada na CLI de base. Experimente 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 já não precisar de uma extensão, remova-a com o comando az extension remove.

az extension remove --name <extension-name>

Também pode remover uma extensão manualmente se a eliminar da localização onde foi instalada. A variável de shell $AZURE_EXTENSION_DIR define o local onde os módulos são instalados. Se esta variável não estiver definida, então, por predefinição, o valor é $HOME/.azure/cliextensions, no Linux e macOS, e %USERPROFILE%\.azure\cliextensions no Windows.

rm -rf $AZURE_EXTENSION_DIR/<extension-name>

FAQ

Seguem-se algumas respostas para outras perguntas comuns sobre extensões da CLI.

Que formatos de ficheiro são permitidos para instalação?

Atualmente, apenas pode instalar wheels Python compilados como extensões.

As extensões podem substituir comandos existentes?

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

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

A documentação e o controlo de versões de uma extensão mostram se está em pré-lançamento. É frequente a Microsoft lançar comandos de pré-visualização como extensões da CLI, com a opção de os mover mais tarde para a CLI principal. Quando os comandos são retirados das extensões, a extensão antiga deverá ser desinstalada.

As extensões podem depender umas das outras?

N.º Uma vez que a CLI não garante a ordem de carregamento, as dependências podem não ser cumpridas. Remover uma extensão não afeta outras pessoas.

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

N.º As extensões têm de ser atualizadas em separado, conforme descrito em Atualizar as extensões.

Como desenvolver a nossa própria extensão?

Consulte o repositório oficial para obter mais ajuda. Azure/azure-cli-extensions