您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

使用 Azure CLI 的扩展Use extensions with Azure CLI

Azure CLI 提供用于加载扩展的功能。The Azure CLI offers the capability to load extensions. 扩展属于 Python wheel,它们未随附在 CLI 中,而是作为 CLI 命令运行。Extensions are Python wheels that aren't shipped as part of the CLI but run as CLI commands. 使用扩展可以访问试验性命令和预发行的命令,以及编写自己的 CLI 接口。With extensions, you gain access to experimental and pre-release commands along with the ability to write your own CLI interfaces. 本文介绍如何管理扩展,并解答有关其用法的常见问题。This article covers how to manage extensions and answers common questions about their use.

查找扩展Find extensions

若要查看 Microsoft 提供和维护的扩展,请使用 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

我们还在文档站点上提供了扩展列表We also host a list of extensions on the documentation site.

安装扩展Install extensions

找到要安装的扩展后,请使用 az extension add 获取它。Once you have found an extension to install, use az extension add to get it. 如果该扩展在 az extension list-available 中列出,可以按名称安装该扩展。If the extension is listed in az extension list-available, you can install the extension by name.

az extension add --name <extension-name>

如果此扩展来自外部资源,或者你有指向它的直接链接,则可以提供源 URL 或本地路径。If the extension is from an external resource or you have a direct link to it, provide the source URL or local path. 该扩展必须是已编译的 Python wheel 文件。The extension must be a compiled Python wheel file.

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

安装扩展后,可在 $AZURE_EXTENSION_DIR shell 变量的值下找到它。Once an extension is installed, it's found under the value of the $AZURE_EXTENSION_DIR shell variable. 如果此变量未设置,默认情况下在 Linux 和 macOS 上该值为 $HOME/.azure/cliextensions,在 Windows 上为 %USERPROFILE%\.azure\cliextensionsIf this variable is unset, by default the value is $HOME/.azure/cliextensions on Linux and macOS, and %USERPROFILE%\.azure\cliextensions on Windows.

更新扩展Update extensions

如果已按名称安装了扩展,可以使用 az extension update 更新该扩展。If an extension was installed by name, update it using az extension update.

az extension update --name <extension-name>

否则,可以按照安装扩展说明,从源更新扩展。Otherwise, an extension can be updated from source by following the Install extensions instructions.

如果扩展名称无法由 CLI 解析,请卸载该扩展,然后尝试重新安装。If an extension name can't be resolved by the CLI, uninstall it and attempt to reinstall. 该扩展也可能属于基本 CLI。The extension could also have become part of the base CLI. 请按照安装 Azure CLI 中的说明尝试更新 CLI,并查看扩展的命令是否已添加。Try updating the CLI as described in Install the Azure CLI and see if the extension's commands were added.

卸载扩展Uninstall extensions

如果不再需要某个扩展,请使用 az extension remove 将其卸载。If you no longer need an extension, remove it with az extension remove.

az extension remove --name <extension-name>

还可以通过从安装扩展的位置删除它来进行手动删除。You can also remove an extension manually by deleting it from the location where it was installed. $AZURE_EXTENSION_DIR shell 变量定义模块的安装位置。The $AZURE_EXTENSION_DIR shell variable defines where modules are installed. 如果此变量未设置,默认情况下在 Linux 和 macOS 上该值为 $HOME/.azure/cliextensions,在 Windows 上为 %USERPROFILE%\.azure\cliextensionsIf 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>

常见问题解答FAQ

以下是一些有关 CLI 扩展的其他常见问题的答案。Here are some answers to other common questions about CLI extensions.

安装允许哪些文件格式?What file formats are allowed for installation?

当前,只有编译的 Python wheel 才能作为扩展进行安装。Currently, only compiled Python wheels can be installed as extensions.

扩展是否可以替换现有命令?Can extensions replace existing commands?

是的。Yes. 扩展可以替换现有命令,但在运行已替换的命令之前,CLI 会发出一个警告。Extensions may replace existing commands, but before running a command that has been replaced the CLI will issue a warning.

如何判断扩展是否处于预发布阶段?How can I tell if an extension is in pre-release?

扩展的文档和版本将显示该扩展是否是预发行版。An extension's documentation and versioning will show if it's in pre-release. Microsoft 通常以 CLI 扩展的形式发布预览版命令,以后会提供相应的选项用于将这些命令移到主要 CLI 产品中。Microsoft often releases preview commands as CLI extensions, with the option of moving them into the main CLI product later. 将命令转出扩展后,应卸载旧扩展。When commands are moved out of extensions, the old extension should be uninstalled.

扩展是否可以彼此依赖?Can extensions depend upon each other?

不是。No. 由于 CLI 不能保证加载顺序,因此可能无法满足依赖关系方面的要求。Since the CLI doesn't guarantee a load order, dependencies might not be satisfied. 删除一个扩展不会影响其他任何扩展。Removing an extension won't affect any others.

扩展是否随 CLI 一起更新?Are extensions updated along with the CLI?

不是。No. 扩展必须单独更新,如更新扩展所述。Extensions must be updated separately, as described in Update extensions.