成功使用 Azure CLI 的提示

5 分钟

在本模块中，你学习了选择环境、安装 Azure CLI、以交互方式执行 Azure CLI 命令以及创建 Bash 脚本。让我们进一步了解一步，重点介绍如何成功使用 Azure CLI 。本单元介绍如何在命令行后面使用 Azure CLI ，并提供故障排除提示。

小窍门

本模块是一门高级课程，本单元将深入 介绍 Azure CLI。如果你不熟悉命令行编程，请专注于概念。在获得经验时，详细信息更易于理解。不要放弃！

了解 Azure CLI API 调用

在 Azure 门户的图形用户界面和 Azure CLI 的命令行背后执行的是 API 调用。可以使用参数公开 Azure CLI 的API 调用--debug。下面是创建新 资源组时会发生什么情况：

az group create --location westus2 --name myResourceGroupName --debug

以下是来自 Azure Cloud Shell 的终端输出，为简洁起见省略了部分行。请注意这一重要输出：

命令参数： 它是分析命令参数（参数）的脚本语言，而不是 Azure CLI。 此输出属性是命令导致错误时要查找的第一个位置。
azlogging： 此路径是日志文件的存储位置。
请求标头： 这些标头是 PUT 命令传递的参数值。
响应内容：此输出是返回到控制台的内容，不包含完整的 --debug 输出。

cli.knack.cli: Command arguments: ['group', 'create', '--location', 'westus2', '--name', 'myResourceGroupName', '--debug']
cli.knack.cli: __init__ debug log:
...
cli.knack.cli: Event: CommandInvoker.OnPreCommandTableCreate []
cli.azure.cli.core: Modules found from index for 'group': ['azure.cli.command_modules.resource']
cli.azure.cli.core: Loading command modules:
...
cli.azure.cli.core: Loaded 53 groups, 233 commands.
cli.azure.cli.core: Found a match in the command table.
cli.azure.cli.core: Raw command  : group create
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/2025-10-08.21-47-27.group_create.5217.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/myResourceGroupName?api-version=2022-09-01'
cli.azure.cli.core.sdk.policies: Request method: 'PUT'
cli.azure.cli.core.sdk.policies: Request headers:
cli.azure.cli.core.sdk.policies:     'Content-Type': 'application/json'
cli.azure.cli.core.sdk.policies:     'Content-Length': '23'
cli.azure.cli.core.sdk.policies:     'Accept': 'application/json'
cli.azure.cli.core.sdk.policies:     'x-ms-client-request-id': 'c79caddc-ed78-11ef-8a83-00155dbc433c'
cli.azure.cli.core.sdk.policies:     'CommandName': 'group create'
cli.azure.cli.core.sdk.policies:     'ParameterSetName': '--location --name --debug'
...
cli.azure.cli.core.sdk.policies: Response content:
...
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroupName",
  "location": "westus2",
  "managedBy": null,
  "name": "myResourceGroupName",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}
cli.knack.cli: Event: Cli.SuccessfulExecute []
cli.knack.cli: Event: Cli.PostExecute [<function AzCliLogging.deinit_cmd_metadata_logging at 0x7f98a6bc7820>]
az_command_data_logger: exit code: 0
...

来自调试输出的关键信息

命令分析：脚本语言（而不是 Azure CLI）分析参数。在进行故障排除时，请先查看此处。
日志文件位置： 在验尸分析中所示 azlogging 的路径中找到详细日志。
API 详细信息：查看正在进行的实际 REST API 调用，包括 HTTP 方法（PUTGET等）。
退出代码： 指示成功的值 0 ;非零值表示错误。

某些 Azure CLI 命令执行多个操作。用于 --debug 查看 Azure CLI 正在执行的每个命令。更有用的是，使用 --debug 来排查 Azure CLI 脚本产生意外结果的原因。

使用 --debug 进行故障排除

作为开发人员，你曾想过多少次，“这个任务应该如此简单！为什么我的脚本无法正常工作？从 Azure CLI 命令收到意外结果时， --debug 参数是你的朋友！让我们来看一个拥有 100 个 Azure 存储帐户的公司示例。需要查找启用了 Blob 公共访问 的帐户。

# Bash script - INCORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == `true`].id"

如果参数值的格式不符合用于分析该值的脚本语言的正确要求，则会收到“invalid jmespath_type value”错误：

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == ].id', '--debug']
...
cli.azure.cli.core.azclierror: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'
az_command_data_logger: argument --query: invalid jmespath_type value: '[?allowBlobPublicAccess == ].id'

查看 Bash 为 allowBlobPublicAccess 传递的变量值。事实上，价值在哪里？为什么它缺失？

请记住，分析 Azure CLI 变量值的是环境（也称为“脚本语言”）。每个脚本语言 ，甚至同一脚本语言的版本都可以产生不同的结果。下面是在 Bash 中传递布尔参数值的正确方法：

# Bash script - CORRECT
resourceGroup="msdocs-rg-00000000"
az storage account list --resource-group $resourceGroup --query "[?allowBlobPublicAccess == \`true\`].id" --debug

cli.knack.cli: Command arguments: ['storage', 'account', 'list', '--resource-group', 'msdocs-rg-00000000', '--query', '[?allowBlobPublicAccess == `true`].id', '--debug']
...
[
  "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-rg-00000000/providers/Microsoft.Storage/storageAccounts/msdocssa00000000"
]

小窍门

关键区别在于使用真正的反引号转义 \true``，以便 Bash 不会将其解释为命令替换。

掌握重要概念 --debug，并在所选环境中成功使用 Azure CLI 。

脚本语言语法差异

当我们刚刚完成讨论 --debug时，下一步是了解导致大多数脚本错误的原因。如果脚本包含以下构造之一，则需要修改 Bash 编写的脚本才能在 PowerShell 中成功执行或 cmd.exe ：

续行符
变量
随机标识符
引号
编程语言构造

下面是一些示例：

语法	Bash	PowerShell	cmd.exe
行继续符	反斜杠 (`\`)	反引号 (`)	脱字号 (`^`)
变量命名	`variableName=varValue`	`$variableName="varValue"`	`set variableName=varValue`
数字作为字符串	`\`50''	`50`	`50`
布尔值作为字符串	`\`true``	`false`	`'true'`
随机 ID	`let "randomIdentifier=$RANDOM*$RANDOM"`	`$randomIdentifier = (New-Guid).ToString().Substring(0,8)`	`set randomIdentifier=%RANDOM%`
循环	`until`、`while`、`for`	`for`、`foreach`、`while`、`do-while`、`do-until`	`for`
写入控制台	`echo`	`Write-Host` （首选）或 `echo`	`echo`

常见陷阱

此示例表不是全面的。在收到 Azure CLI 错误时，请务必先考虑环境可能存在语法问题。通过将 脚本复制并粘贴到另一种脚本语言（例如 Azure Cloud Shell）来测试这种可能性。在两个环境中使用 --debug ，并记下 command arguments 输出属性的差异。

重要

从Microsoft文章复制代码块时，请注意，Microsoft中的大多数 Azure CLI 文档都是针对 Bash 编写的，并在 Azure Cloud Shell 中进行测试。

获取帮助的更多方法

使用 az find

通过以下示例快速了解 Azure CLI 命令：

查找与“blob”一词相关的最常用命令：

az find blob

显示 Azure CLI 命令组最常用的命令，例如 az storage：

az find "az storage"

显示 Azure CLI 命令的最常用参数和子命令：

az find "az storage account create"

使用 --help

如果你已经知道所需命令的名称，该命令的 --help 参数会提供有关该命令的更多详细信息；而对于命令组，它会提供可用子命令的列表。继续学习 Azure 存储 示例，下面介绍了如何获取用于管理 存储帐户 Blob 服务的子组和命令的列表：

az storage account blob-service-properties --help

小窍门

与 --help 任何命令或子命令一起使用，在不离开终端的情况下获取详细的使用情况信息。

A 到 Z 文档索引

若要查找 Azure CLI 参考命令的示例，请使用多个 A 到 Z 索引之一：

参考索引： 提供所有引用组的 A 到 Z 列表。展开左侧导航栏以显示子组。
Azure CLI 概念文章列表： 提供快速入门的 A 到 Z 列表、作指南、教程和学习模块，这些模块介绍如何在实际方案中使用 Azure CLI 参考命令。本文按 Azure CLI 命令组对文章进行分组，例如 az account，然后使用 az acrWindows 中的 Ctrl+F （macOS 中的 Cmd+F ）快速跳转到所选命令组。
Azure CLI 示例脚本： 索引有三个选项卡：
- 按主题区域列出： 查找 Azure 服务的示例。
- 按引用组列出： 查找参考命令组的示例。
- Azure CLI 示例 GitHub 存储库： 在 Azure CLI 示例 GitHub 存储库中找到示例。

使用 Copilot

Azure 门户和 Microsoft Edge 都提供 Copilot 体验，这些体验返回有关 Azure CLI 参考命令、示例和已发布的文章的信息。 Copilot 还提供指向相关 Stack Overflow 问题的链接。当你需要完成一个涉及多个脚本步骤的复杂任务时，Copilot 能帮助汇集多种信息来源来回答你的问题。

注释

GitHub Copilot 还可以帮助你直接在代码编辑器中编写 Azure CLI 脚本，并提供智能代码完成和建议。

反馈

此页面是否有帮助？