成功使用 Azure CLI 的提示

發行項
03/05/2024

Azure CLI 是命令行工具，可讓您從許多殼層環境設定和管理 Azure 資源。選擇慣用的殼層環境並安裝 Azure CLI 之後，請使用本文來探索如何避免常見陷阱並成功使用 Azure CLI 的實用秘訣。

若要深入瞭解特定的 Azure CLI 命令，請參閱 Azure CLI 參考清單。

輸出格式設定

三種常見的輸出格式會與 Azure CLI 命令搭配使用：

格式 json 會將信息顯示為 JSON 字串。
- JSON 提供最完整的資訊。
- 此格式是預設值，但您可以使用 --output 參數來指定不同的選項。
- 使用 az config ，將全域預設格式變更為其中一個個人喜好設定，例如 az config set core.output=table。
- JSON 格式會保留雙引號，通常使其不適合編寫腳本。

格式 table 會將輸出呈現為可讀取的數據表。您可以指定資料表中顯示的值，並使用查詢來自定義輸出，如下所示：

# command
az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table

# output
Name    Os
------  ------------
myVMname   UbuntuServer

格式會 tsv 傳回製表符分隔和換行符分隔的值，而不需要額外的格式、索引鍵或其他符號。
- TSV 格式適用於簡潔的輸出和腳本用途。
- TSV 會去除 JSON 格式保留的雙引號。
- 若要指定 TSV 所需的格式，請使用 --query 參數。
```
export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids
```

如需這些和其他格式的詳細資訊，請參閱 Azure CLI 命令的輸出格式。

將值傳遞至另一個命令

如果使用的值一次以上，請將它指派給變數。變數可讓您多次使用值，或建立更一般腳本。此範例會將 az vm list 命令所找到的標識碼指派給變數。

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

如果值只使用一次，請考慮管線。（管線會將一個命令的輸出當做輸入傳遞至第二個命令。

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

針對多重值清單，請考慮下列選項：

如果您需要對結果有更多的控件，請使用「for」循環：

#!/usr/bin/env bash
for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
    echo stopping $vmList
    az vm stop --ids $vmList
    if [ $? -ne 0 ]; then
        echo "Failed to stop $vmList"
        exit 1
    fi
    echo $vmList stopped
done

或者，使用 xargs 和考慮使用 -P 旗標平行執行作業，以改善效能：

az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | xargs -I {} -P 10 az vm start --ids "{}"

最後，Azure CLI 內建支援以平行方式處理多個 --ids 命令，以達到 xargs 的相同效果。 @- 用來從管道取得值：

az vm list --resource-group MyResourceGroup --show-details \
  --query "[?powerState=='VM stopped'].id" \
  --output tsv | az vm start --ids @-

如需搭配 Azure CLI 使用 Bash 建構的詳細資訊，包括迴圈、case 語句 if.。然後。。否則，以及錯誤處理，請參閱瞭解如何搭配 Azure CLI 使用 Bash。

在參數中使用引號

當您使用 Azure CLI 命令時，請注意殼層如何使用引號和逸出字元。如果您支援不同殼層中使用的腳本，請瞭解它們的差異。

Bash。引用
PowerShell。關於引用規則
Windows 命令提示字元。操作說明：在 Windows 命令行中逸出字元、分隔符和引號

注意

由於 PowerShell 中的已知問題，因此會套用一些額外的逸出規則。如需詳細資訊，請參閱引用 PowerShell 的問題。

若要避免非預期的結果，以下是一些建議：

如果您提供包含空格符的參數，請以引弧括住它。
在Bash或PowerShell中，單引號和雙引號都會正確解譯。在 Windows 命令提示字元中，只有雙引號會正確解譯 -- 單引號會視為值的一部分。
如果您的命令只會在 Bash （或 Zsh）上執行，請使用單引號來保留 JSON 字串內的內容。提供內嵌 JSON 值時，需要單引號。例如，此 JSON 在 Bash 中是正確的： '{"key": "value"}'。
如果您的命令在 Windows 命令提示字元中執行，您必須使用雙引號。如果值包含雙引號，您必須將它逸出。上述 JSON 字串的對等專案為 "{\"key\": \"value\"}"
在 PowerShell 中，如果您的值是空字串，請使用 '""'。
在 Bash 或 PowerShell 中，如果您的值是空引號字串 ''，請使用 "''"。

使用 Azure CLI 的 @<file> 慣例從檔案載入，並略過殼層的解譯機制。

az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json

Bash 會評估導出變數中的雙引號。如果此行為不是您想要的，請逸出變數： "\$variable"。
某些 Azure CLI 命令會採用空格分隔值的清單。
- 如果索引鍵名稱或值包含空格，請包裝整個配對： "my key=my value"。例如：
```
az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"
```
- 當 CLI 參數指出它接受以空白分隔的清單時，預期有兩種格式之一：
  1. 未加上批注、以空格分隔的清單 --parameterName firstValue secondValue
  2. 引號空格分隔清單 --parameterName "firstValue" "secondValue"
  此範例是字串，其中包含一個空格。這不是以空白分隔的清單： --parameterName "firstValue secondValue"

PowerShell 有特殊字元，例如在 @。若要在PowerShell中執行 Azure CLI，請在特殊字元之前新增 ` 以逸出它。您也可以以單引號或雙引號 "/"括住值。

# The following three examples will work in PowerShell
--parameterName `@parameters.json
--parameterName '@parameters.json'
--parameterName "@parameters.json"

# This example will not work in PowerShell
--parameterName @parameters.json

當您搭配--query命令使用參數時，必須在殼層中逸出 JMESPath 的某些字元。

這三個命令在Bash中是正確的和對等的：

az version --query '"azure-cli"'
az version --query \"azure-cli\"
az version --query "\"azure-cli\""

以下是 Bash 中不正確命令的兩個範例：

# Wrong, as the dash needs to be quoted in a JMESPath query
az version --query azure-cli
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

# Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
az version --query "azure-cli"
az version: error: argument --query: invalid jmespath_type value: 'azure-cli'

如需 Bash、PowerShell 和 Cmd 之間的更多範例比較，請參閱查詢 Azure CLI 命令輸出

這五個命令在 PowerShell 中正常運作：

az version --query '\"azure-cli\"'
az version --query "\`"azure-cli\`""
az version --query "\""azure-cli\"""
az --% version --query "\"azure-cli\""
az --% version --query \"azure-cli\"

如需 Bash、PowerShell 和 Cmd 之間的更多範例比較，請參閱查詢 Azure CLI 命令輸出

這兩個命令在 Windows 命令提示字元中正常運作：

az version --query "\"azure-cli\""
az version --query \"azure-cli\"

如需 Bash、PowerShell 和 Cmd 之間的更多範例比較，請參閱查詢 Azure CLI 命令輸出

對引用問題進行疑難解答的最佳方式是使用 --debug 旗標執行命令。此旗標會顯示 Azure CLI 在 Python 語法中收到的實際自變數。

# Correct
$ az '{"key":"value"}' --debug
Command arguments: ['{"key":"value"}', '--debug']

# Correct
$ az "{\"key\":\"value\"}" --debug
Command arguments: ['{"key":"value"}', '--debug']

# Wrong, as quotes and spaces are interpreted by Bash
$ az {"key": "value"} --debug
Command arguments: ['{key:', 'value}', '--debug']

# Wrong, as quotes are interpreted by Bash
$ az {"key":"value"} --debug
Command arguments: ['{key:value}', '--debug']

在參數中使用連字元字元

如果參數的值以連字元開頭，Azure CLI 會嘗試將它剖析為參數名稱。若要將它剖析為值，請使用 = 來串連參數名稱和值： --password="-VerySecret"。

非同步作業

Azure 中的作業可能需要相當長的時間。例如，在數據中心設定虛擬機並非瞬間完成。 Azure CLI 會等候命令完成以接受其他命令。因此，許多命令都會提供 --no-wait 參數，如下所示：

az group delete --name MyResourceGroup --no-wait

當您刪除資源群組時，也會移除屬於它的所有資源。拿掉這些資源可能需要很長的時間。當您使用 --no-wait 參數執行命令時，主控台會接受新的命令，而不會中斷移除。

許多命令都提供等候選項，暫停控制台，直到符合某些條件為止。下列範例使用 az vm wait 命令來支援平行建立獨立資源：

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

建立這兩個標識符之後，您就可以再次使用控制台。

在 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/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 如需詳細資訊，請參閱如何設定 Azure 連結庫的 Proxy。

並行執行

如果您在相同的計算機上同時執行 Azure CLI 命令，如果多個 Azure CLI 命令寫入相同的 MSAL 令牌快取，就可能發生寫入衝突。

若要避免潛在的失敗，您可以將每個腳本的環境變數 AZURE_CONFIG_DIR 設定為個別目錄，以隔離每個腳本的 Azure CLI 組態資料夾。該文稿中的 Azure CLI 命令會將設定和令牌快取儲存到設定的位置，而不是預設 ~/.azure 資料夾。

export AZURE_CONFIG_DIR=/my/config/dir

$env:AZURE_CONFIG_DIR='D:\my\config\dir'

set AZURE_CONFIG_DIR=D:\my\config\dir

泛型更新參數

Azure CLI 命令群組通常具有更新命令。例如，Azure 虛擬機器包含 az vm update 命令。大部分的更新命令都提供三個泛型參數： --add、 --set和 --remove。

--set和 --add 參數會採用以空格分隔索引鍵/值組的清單：key1=value1 key2=value2。若要查看您可以更新的屬性，請使用 show 命令，例如 az vm show。

az vm show --resource-group VMResources --name virtual-machine-01

若要簡化命令，請考慮使用 JSON 字串。例如，若要將新的數據磁碟連結至虛擬機，請使用下列值：

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

泛型資源命令（az resource）

您想要使用的服務可能沒有 Azure CLI 支援。您可以使用 az resource 命令來處理這些資源。

如果您只需要建立或更新命令，請使用 az deployment group create。如需運作範例，請參閱 Azure 快速入門範本。

REST API 命令（az rest）

如果泛型更新參數和 az resource 不符合您的需求，您可以使用 az rest 命令來呼叫 REST API。命令會自動使用登入認證進行驗證，並設定標頭 Content-Type: application/json。如需詳細資訊，請參閱 Azure REST API 參考。

此範例適用於 Microsoft Graph API。若要更新應用程式的重新導向 URI，請呼叫更新應用程式 REST API，如下列程式代碼所示：

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

使用 --uri-parameters OData 形式的要求時，請務必在不同的環境中逸 $ 出：在 Bash中，逸 $ 出為 \$ 和， PowerShell逸 $ 出為 `$

腳本範例

以下是使用 Azure 虛擬機器時，使用變數並迴圈查看清單的範例。如需搭配 Azure CLI 使用 Bash 建構的深入範例，包括迴圈、case 語句 if.。然後。。否則，以及錯誤處理，請參閱瞭解如何搭配 Azure CLI 使用 Bash。

使用這些文稿將識別元儲存至變數：

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
az vm stop --ids $vm_ids # CLI stops all VMs in parallel

使用這些腳本來循環檢視清單：

Bash
PowerShell

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

$vm_ids=(az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv)
foreach ($vm_id in $vm_ids) {
    Write-Output "Stopping $vm_id"
    az vm stop --ids $vm_id
}

成功使用 Azure CLI 的提示

輸出格式設定

將值傳遞至另一個命令

在參數中使用引號

在參數中使用連字元字元

非同步作業

在 Proxy 後方工作

並行執行

泛型更新參數

泛型資源命令（az resource）

REST API 命令（az rest）

腳本範例

另請參閱

其他資源

成功使用 Azure CLI 的 提示

輸出格式設定

將值傳遞至另一個命令

在參數中使用引號

在參數中使用連字元字元

非同步作業

在 Proxy 後方工作

並行執行

泛型更新參數

泛型資源命令 （az resource）

REST API 命令 （az rest）

腳本範例

另請參閱

其他資源

成功使用 Azure CLI 的提示

泛型資源命令（az resource）

REST API 命令（az rest）