排查 Azure CLI 故障

错误类别

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.exe）中运行，但脚本语言之间存在语法差异。 包含单引号、双引号和转义字符的 Azure CLI 脚本通常需要在语言之间复制时进行修改。 此挑战通常显示在参数值中，尤其是在分配给--query参数的值中。 下面是一些常见的错误消息：

• 错误的请求...{something} 无效：此错误可能是由空格、单引号或双引号或缺少引号引起的。

• 意外的标记...：当存在额外的空格或引号时，会导致此错误。

• 无效的 jmespath_type 值：此错误通常由于参数中引用不正确而产生。

• 变量引用无效：如果字符串格式不正确，通常是由于串联或缺少转义字符，则会收到此错误。

• 无法识别的参数：此错误通常是由错误的行继续符或拼写错误的参数名称引起的。

• 一元运算符后缺少表达式：缺少行继续符时，会出现此错误。

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

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

多重身份验证疑难解答 （MFA）

交互式登录失败

如果在运行创建、修改或删除资源的 Azure CLI 命令时遇到错误，则可能是由需要多重身份验证（MFA）的Microsoft Entra ID 条件访问策略引起的。

这些错误通常在策略要求 MFA 时发生，但在登录期间不会强制实施。

策略不允许资源

使用时，可能会看到以下错误之一：

• Azure CLI 版本 2.75.0 或更高版本

Due to a configuration change made by your administrator, or because you moved to a new location,
you must enroll in multi-factor authentication. Interactive authentication is needed.

或者：

Resource was disallowed by policy. Reasons: MFA is required. See error details for policy resource
IDs. RequestDisallowedByPolicy Message: Resource policy resource IDs was disallowed by policy.
Reasons: MFA is required.

或者：

Unauthorized. RequestDisallowedByPolicy. Resource was disallowed by policy. Reasons: MFA is
required. See error details for policy resource IDs. MFA is required. Users must authenticate with
multi-factor authentication to create or update resources.

升级到以下版本或更高版本以接收更详细的错误消息和策略详细信息：

• Azure CLI 2.76.0 或更高版本

Azure CLI 2.76.0+ 中出现以下错误，其中条件访问需要 MFA 才能执行特定作。

Run the command below to authenticate interactively; additional arguments may be added as needed:
az logout 
az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>"

(RequestDisallowedByPolicy) Resource was disallowed by policy. Policy identifiers. Users must use
MFA for Create/Update operations. Users must authenticate with multi-factor authentication to create
or update resources. Users must use MFA for Create operation. Users must authenticate with
multi-factor authentication to create or update resources. Users must use MFA for Create/Update
operations. Users must authenticate with multi-factor authentication to create or update resources.
Users must use MFA for Create operation. Users must authenticate with multi-factor authentication to
create or update resources.

解决方法选项

• 要求 Azure 管理员在登录时强制实施 MFA。 这样，会话就可以满足条件访问要求，而无需执行其他步骤。

• 如果无法在登录时执行 MFA，请使用 --claims-challenge 参数以交互方式进行身份验证：

  az logout
  az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>"
  

有关详细信息，请参阅 规划 Azure 和其他管理门户的强制多重身份验证

导入 win32file 时 DLL 加载失败

尝试使用 Azure CLI 时可能会遇到以下错误：

DLL load failed while importing win32file: The specified module could not be found.
The command failed with an unexpected error. Here is the traceback:
DLL load failed while importing win32file: The specified module could not be found.
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/__main__.py", line 13, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/telemetry.py", line 19, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/telemetry/__init__.py", line 9, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\portalocker/__init__.py", line 4, in <module>
  File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\portalocker/portalocker.py", line 11, in <module>
ImportError: DLL load failed while importing win32file: The specified module could not be found.
PS C:\Users\dsevilla>

由于安装已损坏，可能会出现此问题。 解决此问题：

1. 卸载 Azure CLI。
2. 使用首选安装方法重新安装 Azure CLI。

有关详细信息，请参阅 GitHub 问题 #32045。

错误：值无效或不存在

尝试使用包含不正确格式的变量值时，通常会发生这些错误。 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 脚本语言时，行续符号的右侧存在尾随空格。 PowerShell splatting 仅支持数组，不支持哈希表与 Azure CLI 命令一起使用。
• 变量名称包含特殊字符，如短划线（-）。

错误：找不到资源

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

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

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

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

有关 Bash、PowerShell 和 cmd.exeJSON 语法示例，请参阅 脚本语言之间的引用差异 - 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 资源提供程序和类型。

错误：错误的握手过程导致SSL证书验证失败

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

通过代理工作

如果通过使用自签名证书的代理服务器使用 Azure CLI，Python 请求 Azure CLI 使用的库 可能会导致以下错误：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 的提示