在 PowerShell 環境中執行 Azure CLI 的考慮

  • 發行項

Azure CLI 是一種工具，可透過在 Bash 和 PowerShell 環境中執行的 Azure CLI 參考命令來管理 Azure 資源。 不過，在可能導致非預期結果的環境中，參數格式設定有輕微的語法差異。 本文的目的是要協助您解決在PowerShell環境中運作時的 Azure CLI 語法錯誤。

本文會比較在下列環境中執行的 Azure CLI 命令語法差異：

如果您不熟悉 CLI，則工具和環境之間的區分可能會造成混淆。 如何選擇正確的命令行工具 可提供良好的比較。

必要條件

本文旨在讓您閱讀和學習。 不過，如果您想要執行範例，請選取索引 Prepare your environments 標籤以安裝本文中使用的環境。

重要

當您有產生錯誤的 Azure CLI 腳本時， 請考慮您所使用的環境如何剖析 Azure CLI 命令語法。

在 Azure CLI 參數中傳遞空格

在 Azure CLI 中，當您需要傳遞包含空間的參數值時，操作系統和環境之間會有差異。 在此範例中，使用 az storage account list 並將輸出數據行重新命名為包含空格的字組。

在此範例中，請注意具有內嵌雙引號 （） 的單引號 （'...'） 包裝函式。"..." 此範例也適用於Linux中的PowerShell。

az storage account list --query '[].{"SA Name":name, "Primary endpoint":primaryEndpoints.blob}' --output table

如果您想要新增篩選，語法會變更。 請注意這個範例如何以雙引號 （"..."） 包裝--query參數值，並使用反斜杠 （\） 逸出字元。 此腳本不會在PowerShell中執行。

 az storage account list --query "[?creationTime >='2024-02-01'].{\"SA Name\":name,\"Primary endpoint\":primaryEndpoints.blob}" --output table

如果您剛嘗試在 PowerShell 環境中執行篩選語法，您會收到錯誤訊息 argument --query: invalid jmespath_type value: "[?creationTime >=..."。 不過，在Linux環境中的Bash中，您的輸出如下所示：

SA Name           Primary Endpoint
-----------       -----------------
msdocssa00000000  https://msdocssa000000000.blob.core.windows.net/

在包含查詢字串的 URL 中傳遞參數

URL 中的問號表示 URL 的結尾和查詢字串的開頭。 以下是在瞭解如何使用 Azure CLI 中開啟步驟 3 的範例：

https://learn.microsoft.com/en-us/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

結果 ?view=azure-cli-2020-09-01-hybrid 會產生所需的 Azure CLI 參考內容版本。

當您在PowerShell環境中執行 Azure CLI 命令時，PowerShell 允許問號成為變數名稱的一部分。 這可能會在 Azure CLI 參數值中造成混淆。

以下是使用 Azure REST API 文章的範例：

請注意Bash中如何 $containerRegistryName?api-version 串連在一起，而不會發生錯誤。

# Script for a Bash environment

# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
subscriptionId="00000000-0000-0000-0000-000000000000"
resourceGroup="msdocs-app-rg$randomIdentifier"
containerRegistryName="msdocscr$randomIdentifier"

# prior to this GET example, the resource group and container registry were created in the article.

az rest --method get --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

傳遞包含PowerShell特殊字元的參數

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

下列三個範例將在 PowerShell 中運作：

  • parameterName '@parameters.json
  • parameterName '@parameters.json'
  • parameterName “@parameters.json”

此範例無法在PowerShell中運作：

  • parameterName @parameters.json

傳遞包含 JSON 的參數

對於 JSON 字串之類的複雜自變數，最佳做法是使用 Azure CLI 的 @<file> 慣例從檔案載入，以略過殼層解譯。 請注意， At （@） 符號是 PowerShell 中的展開運算符 ，因此應該加上引號。

az ad app create 中有一個很好的範例，其中包含 JSON 檔案內容和命令範例。 以下為程式碼片段：

# Script for a Bash environment

az ad app create --display-name myTestAppName \
    --is-fallback-public-client \
    --required-resource-accesses @manifest.json

傳遞包含索引鍵：值組的參數

某些 Azure CLI 參數值，例如 Azure 資源標籤，需要機碼：值組。 key如果您的 或 value 包含空格或特殊字元，Bash 和 PowerShell 語法不一定相同。

請參閱建立標籤以練習學習使用 Azure CLI 教學課程中的差異。 本教學課程步驟提供Bash、PowerShell和 Cmd 的範例，適用於下列機碼：值組案例：

  • 空間
  • 空白值
  • 特殊字元
  • variables

PowerShell 中的 Azure CLI 錯誤處理

您可以在 PowerShell 中執行 Azure CLI 命令，如選擇正確的 Azure 命令行工具中所述。 如果您這麼做，請務必瞭解 PowerShell 中的 Azure CLI 錯誤處理。 特別是，Azure CLI 不會為 PowerShell 建立例外狀況來攔截。

替代方法是使用 $? 自動變數。 此變數包含最新命令的狀態。 如果上一個命令失敗， $? 則具有的值 $False。 如需詳細資訊，請參閱 about_Automatic_Variables。

下列範例示範這個自動變數如何運作以處理錯誤：

# Script for a PowerShell environment

az group create --name MyResourceGroup
if ($? -eq $false) {
    Write-Error "Error creating resource group."
}

az命令失敗，因為缺少必要的--location參數。 條件語句會尋找為 $? false 並寫入錯誤。

如果您想要使用 try 和 catch 關鍵詞，您可以使用 throw 來建立區塊的 try 例外狀況來攔截：

# Script for a PowerShell environment

$ErrorActionPreference = "Stop"
try {
    az group create --name MyResourceGroup
    if ($? -eq $false) {
        throw 'Group create failed.'
    }
}
catch {
    Write-Error "Error creating the resource group."
}
$ErrorActionPreference = "Continue"

根據預設，PowerShell 只會攔截終止錯誤。 這個範例會將 $ErrorActionPreference 全域變數設定為 Stop ，讓 PowerShell 可以處理錯誤。

條件語句會測試 $? 變數，以查看先前的命令是否失敗。 如果是， throw 關鍵詞會建立要攔截的例外狀況。 區塊 catch 可用來寫入錯誤訊息或處理錯誤。

此範例會 $ErrorActionPreference 還原至其預設值。

如需 PowerShell 錯誤處理的詳細資訊，請參閱 您想要瞭解例外狀況的所有專案。

在 PowerShell 中啟用 Tab 鍵自動完成

Tab 鍵自動完成，也稱為「Azure CLI 完成項」，可在輸入上完成以提供提示、啟用探索並加速輸入輸入。 按下 Tab 鍵，即可自動將命令名稱、命令組名、參數和特定參數值插入命令行。

預設會在 Azure Cloud Shell 和大部分 Linux 發行版中啟用 Tab 鍵自動完成。 從 Azure CLI 2.49 版開始，您可以在 PowerShell 中啟用 Azure CLI 的索引標籤完成。 執行下列步驟:

  1. 建立或編輯儲存在變數 $PROFILE中的配置檔。 最簡單的方式是在PowerShell中執行 notepad $PROFILE 。 如需詳細資訊，請參閱如何建立設定檔和設定檔與執行原則。

  2. 將下列程式代碼新增至 PowerShell 設定檔：

    Register-ArgumentCompleter -Native -CommandName az -ScriptBlock {
    param($commandName, $wordToComplete, $cursorPosition)
    $completion_file = New-TemporaryFile
    $env:ARGCOMPLETE_USE_TEMPFILES = 1
    $env:_ARGCOMPLETE_STDOUT_FILENAME = $completion_file
    $env:COMP_LINE = $wordToComplete
    $env:COMP_POINT = $cursorPosition
    $env:_ARGCOMPLETE = 1
    $env:_ARGCOMPLETE_SUPPRESS_SPACE = 0
    $env:_ARGCOMPLETE_IFS = "`n"
    $env:_ARGCOMPLETE_SHELL = 'powershell'
    az 2>&1 | Out-Null
    Get-Content $completion_file | Sort-Object | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
    }
    Remove-Item $completion_file, Env:\_ARGCOMPLETE_STDOUT_FILENAME, Env:\ARGCOMPLETE_USE_TEMPFILES, Env:\COMP_LINE, Env:\COMP_POINT, Env:\_ARGCOMPLETE, Env:\_ARGCOMPLETE_SUPPRESS_SPACE, Env:\_ARGCOMPLETE_IFS, Env:\_ARGCOMPLETE_SHELL
}

  3. 若要在功能表中顯示所有可用的選項，請將 新增 Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete 至您的PowerShell配置檔。

另請參閱