針對 Azure CLI 進行疑難解答

發行項
06/29/2024

錯誤類別

Azure CLI 傳回的大部分錯誤都屬於下列其中一個類別：

錯誤類別	一般錯誤原因
無法辨識的自變數	參數拼錯或不存在。
遺漏必要的自變數	未指定必要的參數，或只指定兩個「參陣列」的其中一個。參數也可能拼錯。
互斥自變數	無法同時指定兩個或多個參數。
無效的自變數值	參數值無效。此錯誤通常是因為引號、逸出字元或間距所造成。
錯誤要求	HTTP 狀態代碼 400 會傳回此錯誤。檢查遺漏的空間、遺漏的參數破折號，或額外或遺漏單引號或雙引號。當參數值不包含允許的值時，也會發生此錯誤。
找不到資源	找不到參數值中所參考的 Azure 資源。
驗證	Microsoft Entra 驗證失敗。

參數`--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 檔都是使用 Bash 腳本語言在 Azure Cloud Shell （ACS）中撰寫和測試。 如果您可以取得在 ACS Bash 中執行的文章範例，但它不會在 Windows PowerShell 中執行、檢閱您使用單引號和雙引號，以及逸出字元。

錯誤：無效的值或不存在

嘗試使用包含不正確格式的變數值時，通常會發生這些錯誤。 Azure CLI 的預設輸出是 JSON，因此，如果您嘗試將 Azure 資源的識別碼儲存在變數中，您必須指定 --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 錯誤剖析參考命令時，您會收到此錯誤。使用文稿時，當一或多個條件成立時，您也會收到此錯誤：

行接續字元遺失或不正確。
使用 PowerShell 腳本語言時，行接續字元右側有尾端空格。目前， Azure CLI 命令不支持展開。
變數名稱包含特殊字元，例如破折號（-）。

錯誤：找不到資源

當 Azure CLI 找不到傳入參數值的資源名稱或識別碼時，通常是因為下列其中一個原因：

資源名稱或標識碼拼字不正確。
資源名稱包含特殊字元，且不會以單引號或雙引號括住。
傳遞至變數的值具有看不見的前置或尾端空格。
資源存在，但位於不同的訂用帳戶中。

錯誤：無法將字串剖析為 JSON

Bash、Linux 中的 PowerShell 和 Windows 中的 PowerShell 之間有差異。此外，不同版本的PowerShell可能會產生不同的結果。對於複雜的參數，例如 JSON 字串，最佳做法是使用 Azure CLI 的 @<file> 慣例來略過殼層解譯。如需詳細資訊，請參閱下列其中一篇文章：

如需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 資源的屬性，或嘗試不同的位置。

錯誤：SSLError「錯誤的交握...憑證驗證失敗「（Proxy 封鎖連線）

如果您透過使用自我簽署憑證的 Proxy 伺服器使用 Azure CLI，Azure CLI 所使用的 Python 要求連結庫可能會導致下列錯誤： SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)。若要解決此錯誤，請將環境變數 REQUESTS_CA_BUNDLE 設定為 PEM 格式的 CA 套件組合憑證檔案路徑。

OS	默認證書頒發機構單位套件組合
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	`/usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem`

將 Proxy 伺服器的憑證附加至 CA 配套憑證檔案，或將內容複製到另一個憑證檔案。然後將設定 REQUESTS_CA_BUNDLE 為新的檔案位置。以下是範例：

<Original cacert.pem>

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

某些 Proxy 需要驗證。或環境變數的格式HTTP_PROXY應該包含驗證，例如 HTTPS_PROXY="https://username:password@proxy-server:port"。HTTPS_PROXY 如需詳細資訊，請參閱如何設定適用於 Python 的 Azure SDK Proxy。

錯誤：找不到訂用帳戶

假設您未正確輸入訂用帳戶名稱或標識符，則當使用中訂用帳戶中未註冊資源提供者時，就會發生此錯誤。例如，如果您想要執行 az storage account create， Microsoft.Storage 則必須註冊提供者。若要註冊資源提供者，請參閱 Azure 資源提供者和類型。

服務主體

如需針對服務主體進行疑難解答的資訊，請參閱使用服務主體教學課程中的清除和疑難解答。

其他問題

如果您遇到本文未列出的 Azure CLI 產品問題，請在 GitHub 上提出問題。

另請參閱

成功使用 Azure CLI 的秘訣

共用方式為

針對 Azure CLI 進行疑難解答

錯誤類別

參數`--debug`

常見的語法錯誤

錯誤：無效的值或不存在

錯誤：必須是或必要自變數

錯誤：找不到資源

錯誤：無法將字串剖析為 JSON

錯誤：InvalidTemplateDeployment

錯誤：SSLError「錯誤的交握...憑證驗證失敗「（Proxy 封鎖連線）

錯誤：找不到訂用帳戶

服務主體

其他問題

另請參閱

意見反應

其他資源

共用方式為

針對 Azure CLI 進行疑難解答

錯誤類別

參數--debug

常見的語法錯誤

錯誤：無效的值或不存在

錯誤：必須是或必要自變數

錯誤：找不到資源

錯誤：無法將字串剖析為 JSON

錯誤：InvalidTemplateDeployment

錯誤：SSLError「錯誤的交握...憑證驗證失敗「（Proxy 封鎖連線）

錯誤：找不到訂用帳戶

服務主體

其他問題

另請參閱

意見反應

其他資源

參數`--debug`