排查 Azure CLI 问题

错误类别

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

参数--debug

查看每个 Azure CLI 引用命令执行的 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 教程中的语法差异
• 使用 JMESPath 查询在操作方法查询 Azure CLI 命令输出中查找许多--query参数示例
• 如何在 Bash 脚本语言中使用 Azure CLI
• 使用 PowerShell 脚本语言运行 Azure CLI 的注意事项

错误：值无效或不存在

尝试使用包含不正确格式的变量值时，通常会发生这些错误。 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 字符串 教程。

错误：InvalidTemplateDeployment

尝试在不提供该资源的某个位置创建 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，则 Azure CLI 使用的 Python 请求库可能会导致以下错误： SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",) 若要解决此错误，请将环境变量 REQUESTS_CA_BUNDLE 设置为采用 PEM 格式的 CA 捆绑证书文件的路径。

将代理服务器的证书追加到 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 的提示