針對 Azure CLI 進行疑難解答

發行項
12/14/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)

如需 --debug JSON 格式範例，請參閱不同腳本語言之間的引用差異—JSON 字串。

常見的語法錯誤

雖然 Azure CLI 可以在 Bash、PowerShell 和 Windows Cmd 中執行，但腳本語言之間有語法差異。包含單引號、雙引號和逸出字元的 Azure CLI 腳本，通常必須在語言之間複製時修改。這項挑戰最常顯示在參數值中，特別是在指派給 --query 參數的值中。以下是一些常見的錯誤訊息：

“不正確的要求...{something} 無效“可能是因為空格、單引號或雙引號或缺少引號所造成。
當有額外的空格或引號時，就會看到「非預期的符號...」
「無效的 jmespath_type 值」錯誤通常源自於 --query 參數中不正確的引用。
當字串因串連或遺漏逸出字元而無法正確格式化時，會收到“變數參考無效”這樣的訊息。
「無法辨識的自變數」通常是由不正確的行接續字元或拼錯的參數名稱所造成。
當遺漏行接續字元時，會在一元運算符之後看到 “遺漏表達式”。

有數篇 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 字串教學。

錯誤：模板部署無效

當您嘗試在未提供該資源的位置建立 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 資源提供者和類型。

錯誤：錯誤的交握...憑證驗證失敗

如需有關如何解決此錯誤的資訊，請參閱使用代理伺服器時的工作。

透過代理伺服器工作

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

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

<Original cacert.pem>

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

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

服務主體

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

其他問題

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

另請參閱

成功使用 Azure CLI 的秘訣

共用方式為

針對 Azure CLI 進行疑難解答

錯誤類別

`--debug` 參數

常見的語法錯誤

錯誤：無效的值或不存在

錯誤：參數是預期的或必需的

錯誤：找不到資源

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

錯誤：模板部署無效

錯誤：找不到訂用帳戶

錯誤：錯誤的交握...憑證驗證失敗

透過代理伺服器工作

服務主體

其他問題

另請參閱

其他資源

共用方式為

針對 Azure CLI 進行疑難解答

錯誤類別

--debug 參數

常見的語法錯誤

錯誤：無效的值或不存在

錯誤：參數是預期的或必需的

錯誤：找不到資源

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

錯誤：模板部署無效

錯誤：找不到訂用帳戶

錯誤：錯誤的交握...憑證驗證失敗

透過代理伺服器工作

服務主體

其他問題

另請參閱

其他資源

`--debug` 參數