共用方式為

使用 PowerShell 腳本語言執行 Azure CLI 的考慮

  • 發行項

Azure CLI 是一種工具，可透過 Azure CLI 參考命令來管理 Azure 資源，以 Bash 和 PowerShell 腳本語言執行。 不過，腳本語言之間的參數格式設定稍有語法差異，可能會導致非預期的結果。 本文的目的是協助您解決使用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/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 scripting language

# 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

傳遞包含連字元符號的參數

如果您有一個案例，您必須在參數值中傳遞 ampersand，請注意 PowerShell 會解譯 ampersand （&） 符號。 您可以使用 參數來看到這種情況：--debug

az "a&b" --debug

# output
'a' is misspelled or not recognized by the system.
'b' is not recognized as an internal or external command

不過，如果您使用這個相同的測試將標籤新增至資源群組，標籤值中的 ampersand 不會造成錯誤。

az group create --location eastus2 --name "msdocs-rg-test"
az group update --name "msdocs-rg-test" --tags "company name=Contoso & Sons"

# output
{
  "id": "/subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourceGroups/msdocs-rg-test",
  "location": "eastus2",
  "managedBy": null,
  "name": "msdocs-rg-test",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": {
    "company name": "Contoso & Sons"
  },
  "type": "Microsoft.Resources/resourceGroups"
}

如果您有一個案例，其中參數值中的 ampersand 造成錯誤，以下是一些解決方案：

# When quoted by single quotes ('), double quotes (") are preserved by PowerShell and sent
# to Command Prompt, so that ampersand (&) is treated as a literal character
> az '"a&b"' --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") with backticks (`) as required by PowerShell
> az "`"a&b`"" --debug
Command arguments: ['a&b', '--debug']

# Escape double quotes (") by repeating them
> az """a&b""" --debug
Command arguments: ['a&b', '--debug']

# With a whitespace in the argument, double quotes (") are preserved by PowerShell and
# sent to Command Prompt
> az "a&b " --debug
Command arguments: ['a&b ', '--debug']

# Use --% to stop PowerShell from parsing the argument
> az --% "a&b" --debug
Command arguments: ['a&b', '--debug']

傳遞包含 at （@） 符號的參數

PowerShell 有特殊字元，例如在 PowerShell 中為 splatting 運算子的 at （@） 符號。 在特殊字元之前新增反引號 ` 以逸出它。 您也可以以單引號或'雙"引號括住值。

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

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

此範例無法在PowerShell中運作：

  • parameterName @parameters.json

以下是命令的另 az ad app create 一個範例：請注意 PowerShell 腳本語言中所需的 JSON 檔名雙引號 （"..."）。

# Script for a PowerShell scripting language

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

傳遞包含 JSON 的參數

對於 JSON 字串之類的複雜自變數，最佳做法是使用 Azure CLI 的 @<file> 慣例從檔案載入，以略過殼層解譯。 如需Bash、PowerShell和 Cmd.exe的 JSON 語法範例，請參閱 引用腳本語言 - JSON 字串之間的差異。

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

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

如需Bash、PowerShell和 Cmd 的語法範例，請參閱建立標籤以練習學習使用 Azure CLI 教學課程中的差異。 本教學課程步驟提供下列索引鍵：值組案例的範例：

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

停止剖析符號

PowerShell 3.0 中引進的停止剖析符號會--%指示 PowerShell 不要將輸入解譯為 PowerShell 命令或表示式。 當遇到停止剖析符號時，PowerShell 會將行中的其餘字元視為常值。

az --% vm create --name xxx

PowerShell 中的 Azure CLI 錯誤處理

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

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

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

# Script for a PowerShell scripting language

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 scripting language

$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配置檔。

另請參閱