Utilizar extensões com a CLI do AzureUse extensions with Azure CLI

A CLI do Azure oferece a capacidade de carregar extensões.The Azure CLI offers the capability to load extensions. As extensões são pacotes formatados (wheels) para Python que não são fornecidas como parte da CLI, mas são executadas como comandos da CLI.Extensions are Python wheels that aren't shipped as part of the CLI but run as CLI commands. As extensões dão-lhe acesso a comandos experimentais e de pré-lançamento, bem como a capacidade de escrever suas próprias interfaces CLI.With extensions, you gain access to experimental and pre-release commands along with the ability to write your own CLI interfaces. Este artigo descreve como gerir as extensões e responde a perguntas comuns sobre a utilização das mesmas.This article covers how to manage extensions and answers common questions about their use.

Localizar as extensõesFind extensions

Para ver as extensões fornecidas e mantidas pela Microsoft, utilize o comando az extension list-available.To see the extensions provided and maintained by Microsoft, use the az extension list-available command.

az extension list-available --output table

O site de documentação também aloja uma lista de extensões.We also host a list of extensions on the documentation site.

Instalar as extensõesInstall extensions

Depois de encontrar uma extensão para instalar, utilize az extension add para obtê-la.Once you have found an extension to install, use az extension add to get it. Se a extensão estiver listada em az extension list-available, pode instalar a extensão pelo nome.If the extension is listed in az extension list-available, you can install the extension by name.

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.If the extension is from an external resource or you have a direct link to it, provide the source URL or local path. A extensão tem de ser um ficheiro wheel compilado para Python.The extension must be a compiled Python wheel file.

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

Quando a extensão estiver instalada, pode encontrá-la abaixo do valor da variável de shell $AZURE_EXTENSION_DIR.Once an extension is installed, it's found under the value of the $AZURE_EXTENSION_DIR shell variable. 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.If this variable is unset, by default the value is $HOME/.azure/cliextensions on Linux and macOS, and %USERPROFILE%\.azure\cliextensions on Windows.

Atualizar as extensõesUpdate extensions

Se uma determinada extensão foi instalada com base no nome, atualize-a com o comando az extension update.If an extension was installed by name, update it using 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.Otherwise, an extension can be updated from source by following the Install extensions instructions.

Se a CLI não conseguir resolver um nome de extensão, desinstale-a e tente instalá-la novamente.If an extension name can't be resolved by the CLI, uninstall it and attempt to reinstall. A extensão também poderá ter sido integrada na CLI de base.The extension could also have become part of the base CLI. Experimente atualizar a CLI, conforme descrito em Instalar a CLI do Azure, e verifique se os comandos da extensão foram adicionados.Try updating the CLI as described in Install the Azure CLI and see if the extension's commands were added.

Desinstalar as extensõesUninstall extensions

Se já não precisar de uma extensão, remova-a com o comando az extension remove.If you no longer need an extension, remove it with 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.You can also remove an extension manually by deleting it from the location where it was installed. A variável de shell $AZURE_EXTENSION_DIR define o local onde os módulos são instalados.The $AZURE_EXTENSION_DIR shell variable defines where modules are installed. 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.If this variable is unset, by default the value is $HOME/.azure/cliextensions on Linux and macOS, and %USERPROFILE%\.azure\cliextensions on Windows.

rm -rf $AZURE_EXTENSION_DIR/<extension-name>

FAQFAQ

Seguem-se algumas respostas para outras perguntas comuns sobre extensões da CLI.Here are some answers to other common questions about CLI extensions.

Que formatos de ficheiro são permitidos para instalação?What file formats are allowed for installation?

Atualmente, apenas pode instalar wheels Python compilados como extensões.Currently, only compiled Python wheels can be installed as extensions.

As extensões podem substituir comandos existentes?Can extensions replace existing commands?

Sim.Yes. As extensões podem substituir comandos existentes, mas, antes de executar um comando que tenha sido substituído, a CLI emite um aviso.Extensions may replace existing commands, but before running a command that has been replaced the CLI will issue a warning.

Como posso saber se uma extensão está na versão de pré-lançamento?How can I tell if an extension is in pre-release?

A documentação e o controlo de versões de uma extensão indicam se esta se encontra em fase de pré-lançamento.An extension's documentation and versioning will show if it's in pre-release. É 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.Microsoft often releases preview commands as CLI extensions, with the option of moving them into the main CLI product later. Quando os comandos são retirados das extensões, a extensão antiga deverá ser desinstalada.When commands are moved out of extensions, the old extension should be uninstalled.

As extensões podem depender umas das outras?Can extensions depend upon each other?

Não.No. Uma vez que a CLI não garante a ordem de carregamento, as dependências podem não ser cumpridas.Since the CLI doesn't guarantee a load order, dependencies might not be satisfied. A remoção de uma extensão não afeta as restantes.Removing an extension won't affect any others.

As extensões são atualizadas juntamente com a CLI?Are extensions updated along with the CLI?

Não.No. As extensões têm de ser atualizadas em separado, conforme descrito em Atualizar as extensões.Extensions must be updated separately, as described in Update extensions.

Como desenvolver a nossa própria extensão?How to develop our own extension?

Por favor, consulte o repositório oficial para mais ajuda.Please refer to the official repository for more help. Extensões Azure/azure-cliAzure/azure-cli-extensions