你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

排查 Azure CLI 故障

项目
12/11/2024

错误类别

Azure CLI 返回的大多数错误属于以下类别之一：

错误类别	常规错误原因
无法识别的参数	参数拼写错误或不存在。
缺少必需参数	未指定必需参数，或只指定两个“参数对”中的一个。参数也可能拼写错误。
互斥参数	不能一起指定两个或多个参数。
参数值无效	参数值无效。此错误通常是由于引用、转义字符或间距所致。
请求错误	HTTP 状态代码 400 返回此错误。检查是否缺少空格、缺少参数短划线，或存在多余或缺少的单引号或双引号。当参数值不包含允许的值时，也会发生此错误。
资源未找到	找不到参数值中引用的 Azure 资源。
认证	Microsoft Entra 身份验证失败。

`--debug` 参数

查看 Azure CLI 执行每个引用命令的最佳方法之一是使用 --debug 参数。下面是失败和成功命令 --debug 的示例：

# Error example: Create a resource group, but omit the quotes around the resource group name.
az group create --location eastus2 --name msdocs-rg-test --debug

下面是调试输出的一部分。请注意日志位置和无法识别的参数。

cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-name', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.azclierror: unrecognized arguments: msdocs-rg-test
...

将上面给出的错误 --debug 输出与成功的执行进行比较：

# Correct example: Because the resource group name contains special characters, enclose it in quotes
az group create --location eastus2 --name "msdocs-rg-test" --debug

下面是调试输出的一部分。请注意日志位置、API 调用和运行时。

cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-n', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/msdocs-rg-test?api-version=YYYY-MM-DD'
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': 'ba7ee6f4-2dcc-11ef-81ce-00155dadc5c8'
cli.azure.cli.core.sdk.policies:     'CommandName': 'group create'
cli.azure.cli.core.sdk.policies:     'ParameterSetName': '-l -n --debug'
cli.azure.cli.core.sdk.policies:     'User-Agent': 'AZURECLI/2.61.0 (RPM) azsdk-python-core/1.28.0 Python/3.9.19 (Linux-5.10.102.2-microsoft-standard-x86_64-with-glibc2.35) cloud-shell/1.0'
cli.azure.cli.core.sdk.policies:     'Authorization': '*****'
cli.azure.cli.core.sdk.policies: Request body:
cli.azure.cli.core.sdk.policies: {"location": "eastus2"}
urllib3.connectionpool: Starting new HTTPS connection (1): management.azure.com:443
urllib3.connectionpool: https://management.azure.com:443 "PUT /subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourcegroups/msdocs-rg-test?api-version=2022-09-01 HTTP/1.1" 201 226
cli.azure.cli.core.sdk.policies: Response status: 201
...
cli.azure.cli.core.sdk.policies:     'Date': 'Tue, 18 Jun 2024 23:44:41 GMT'
cli.azure.cli.core.sdk.policies: Response content:
cli.azure.cli.core.sdk.policies: {"id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-rg-test","name":"msdocs-rg-test","type":"Microsoft.Resources/resourceGroups","location":"eastus2","properties":{"provisioningState":"Succeeded"}}
...
cli.__main__: Command ran in 1.829 seconds (init: 0.111, invoke: 1.718)

有关 JSON 格式 --debug 的示例，请参阅引用脚本语言之间的差异 - JSON 字符串。

常见语法错误

尽管 Azure CLI 可以在 Bash、PowerShell 和 Windows Cmd 中运行，但脚本语言之间存在语法差异。在语言之间复制时，通常必须修改包含单引号、双引号和转义字符的 Azure CLI 脚本。此挑战最常显示在参数值中，尤其是在分配给 --query 参数的值中。下面是一些常见的错误消息：

“错误的请求...{something} 无效“可能是由空格、单引号或双引号或缺少引号引起的。
“意外的令牌..."，如果有多余的空格或引号时，会出现。
“无效jmespath_type值”错误通常来自 --query 参数中的错误引用。
收到“变量引用无效”消息通常是因为字符串没有正确格式化，这可能是由于串联操作或缺少转义字符所致。
“无法识别的参数”通常是由错误的行延续字符或拼写错误的参数名称引起的。
当缺少行延续字符时，将看到“一元运算符后缺少表达式。

有几个 Azure CLI 文章专用于解释语法错误并提供工作示例：

脚本语言之间引用格式差异
Bash、PowerShell 和 Cmd 教程中的语法差异
在如何查询 Azure CLI 命令输出中使用 JMESPath 查询，找到许多 --query 参数示例。
如何在 Bash 脚本语言中使用 Azure CLI
在 PowerShell 脚本语言中运行 Azure CLI 的注意事项

提示

如果无法解决命令错误，请尝试使用不同的脚本语言。 大多数 Azure CLI 文档都是使用 Bash 脚本语言在 Azure Cloud Shell（ACS）中编写和测试的。 如果您能够在 ACS Bash 中运行一个示例脚本，但无法在 Windows PowerShell 中执行，请检查您对单引号和双引号及转义字符的使用。

错误：值无效或不存在

尝试使用包含不正确格式的变量值时，通常会发生这些错误。 Azure CLI 的默认输出为 JSON，因此，如果要在变量中存储 Azure 资源的 ID，则必须指定 --output tsv。下面是一个示例：

# Get a subscription that contains a name or phrase
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id")
echo $subscriptionID

# output as JSON
[ "00000000-0000-0000-0000-000000000000" ]

# Try to set your subscription to the new ID
az account set --subscription $subscriptionID

# error output
The subscription of '"00000000-0000-0000-0000-000000000000"' doesn't exist in cloud 'AzureCloud'.

现在使用 tsv 输出类型。

# Get the active subscription
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id" --output tsv)
echo $subscriptionID

# output as TSV
00000000-0000-0000-0000-000000000000

# Successfully set your subscription to the new ID
az account set --subscription $subscriptionID

错误：参数是预期的或必需的

当 Azure CLI 命令缺少必需的参数或 出现拼写错误导致 Azure CLI 错误分析引用命令时，会收到此错误。使用脚本时，当一个或多个条件为 true 时，也会收到此错误：

行延续字符缺失或不正确。
在使用 PowerShell 脚本语言时，行续符号的右侧存在尾随空格。目前，Azure CLI 命令不支持展开。
变量名称包含特殊字符，如短划线（-）。

错误：找不到资源

当 Azure CLI 找不到在参数值中传递的资源名称或 ID 时，通常是由于以下原因之一：

资源名称或 ID 拼写错误。
资源名称包含特殊字符，不会用单引号或双引号括起来。
传递给变量的值具有看不见的前导或尾随空格。
资源存在，但位于不同的订阅中。

错误：无法将字符串分析为 JSON

不同操作系统中的 Bash、Linux 中的 PowerShell 和 Windows 中的 PowerShell 在引用方式上存在差异。此外，不同版本的 PowerShell 可能会产生不同的结果。对于复杂参数（如 JSON 字符串），最佳做法是使用 Azure CLI 的 @<file> 约定绕过 shell 的解释。有关详细信息，请参阅以下文章之一：

有关 Bash、PowerShell 和 Cmd.exe的 JSON 语法示例，请参阅引用脚本语言之间的差异 - JSON 字符串教程。

错误：模板部署无效

尝试在不提供该资源的某个位置创建 Azure 资源时，会收到类似于以下消息的错误：“容量限制的以下 SKU 失败：myDesiredSkuName”当前在“mySpecifiedLocation”位置不可用。

下面是无法在 westus 位置创建的 VM 的完整错误示例：

{"error":{"code":"InvalidTemplateDeployment","message":"The template deployment 'vm_deploy_<32 character ID>'
is not valid according to the validation procedure. The tracking id is '<36 character ID>'.
See inner errors for details.","details":[{"code":"SkuNotAvailable","message":"The requested VM size for resource
'Following SKUs have failed for Capacity Restrictions: Standard_DS1_v2' is currently not available
in location 'westus'. Please try another size or deploy to a different location
or different zone. See https://aka.ms/azureskunotavailable for details."}]}}

解决方案是更改请求的 Azure 资源的属性，或尝试其他位置。

错误：找不到订阅

如果您没有错误地输入订阅名称或 ID，那么当资源提供程序未在活动订阅中注册时，会发生此错误。例如，如果要执行 az storage account create，则必须注册 Microsoft.Storage 提供程序。若要注册资源提供程序，请参阅 Azure 资源提供程序和类型。

错误：握手错误...证书验证失败

有关如何解决此错误的信息，请参阅代理后面的工作。

通过代理工作

如果通过使用自签名证书的代理服务器使用 Azure CLI，Python 请求 Azure CLI 使用的库可能会导致以下错误：SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)。若要解决此错误，请将环境变量 REQUESTS_CA_BUNDLE 设置为 PEM 格式的 CA 捆绑证书文件的路径。

操作系统	默认CA包
Windows 32 位	`C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Windows 64 位	`C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem`
Ubuntu/Debian Linux	`/opt/az/lib/python<version>/site-packages/certifi/cacert.pem`
CentOS Stream/RHEL/SUSE Linux	`/usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem`
macOS	Intel 模型：`/usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem` 硅模型：`/opt/homebrew/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem`

将代理服务器的证书追加到 CA 捆绑证书文件，或将内容复制到另一个证书文件。然后将 REQUESTS_CA_BUNDLE 设置为新文件位置。下面是一个示例：

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

某些代理需要身份验证。 HTTP_PROXY 或 HTTPS_PROXY 环境变量的格式应包括身份验证，例如 HTTPS_PROXY="https://username:password@proxy-server:port"。有关详细信息，请参阅如何为用于 Python 的 Azure SDK配置代理。

服务主体

有关服务主体故障排除的信息，请参阅使用服务主体教程中的清理和故障排除。

其他问题

如果遇到本文中未列出的 Azure CLI 的产品问题，请在 GitHub上提交问题。

另请参阅

成功使用 Azure CLI 的提示

通过