Důležité informace o spuštění Azure CLI ve skriptovacím jazyce PowerShellu

  • Článek

Azure CLI je nástroj pro správu prostředků Azure prostřednictvím referenčních příkazů Azure CLI, které běží v Bashu i skriptovacím jazyce PowerShellu. Mezi skriptovacími jazyky ale existují mírné rozdíly v syntaxi formátování parametrů, které můžou vést k neočekávaným výsledkům. Účelem tohoto článku je pomoct při řešení chyb syntaxe Azure CLI při práci ve skriptovacím jazyce PowerShellu.

Tento článek porovnává rozdíly syntaxe příkazů Azure CLI spuštěných v následujících skriptovacích jazycích:

  • Bash spuštěný v operačním systému Linux pomocí Azure Cloud Shellu
  • PowerShell spuštěný v operačním systému Linux pomocí Azure Cloud Shellu
  • Windows PowerShell spuštěný ve Windows 11 pomocí terminálu PowerShellu 5.
  • PowerShell spuštěný ve Windows 11 pomocí terminálu PowerShellu 7

Pokud s rozhraním příkazového řádku začínáte, může být rozdíl mezi nástrojem a skriptovacím jazykem matoucí. Volba správného nástroje příkazového řádku poskytuje dobré porovnání.

Požadavky

Tento článek je určený ke čtení a učení. Pokud ale chcete spustit příklady, vyberte Prepare your environments kartu pro instalaci skriptovacího jazyka použitého v tomto článku.

Důležité

Pokud máte skript Azure CLI, který vytváří chybu, zvažte, jak skriptovací jazyk, ve který pracujete, parsuje syntaxi příkazů Azure CLI.

Předání mezer v parametrech Azure CLI

Pokud v Azure CLI potřebujete předat hodnotu parametru obsahující mezeru, existují rozdíly v uvozování mezi operačními systémy a skriptovacími jazyky. V tomto příkladu použijte příkaz az storage account list a přejmenujte výstupní sloupce s slovem obsahujícím mezeru.

V tomto příkladu si všimněte obálky jednoduchých uvozovek ('...') s vloženými dvojitými uvozovkami ("..."). Tento příklad funguje také v PowerShellu v Linuxu.

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

Pokud chcete přidat filtr, syntaxe se změní. Všimněte si, jak tento příklad zabalí hodnotu parametru --query do dvojitých uvozovek ("...") a používá řídicí znak zpětného lomítka (\). Tento skript se nespustí v PowerShellu.

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

Pokud jste se právě pokusili spustit syntaxi filtru ve skriptovacím jazyce PowerShellu, zobrazila se chybová zpráva argument --query: invalid jmespath_type value: "[?creationTime >=...". V prostředí Bash v linuxovém prostředí je ale výstup podobný tomuto:

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

Předání parametrů v adrese URL obsahující řetězec dotazu

Otazníky v adresách URL označují konec adresy URL a začátek řetězce dotazu. Tady je příklad, který otevře krok 3 v části Learn pro použití Azure CLI:

https://video2.skills-academy.com/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

Výsledkem ?view=azure-cli-2020-09-01-hybrid je požadovaná verze referenčního obsahu Azure CLI.

Když spustíte příkazy Azure CLI ve skriptovacím jazyce PowerShellu, PowerShell umožňuje, aby otazníky byly součástí názvu proměnné. To může způsobit nejasnosti v hodnotách parametrů Azure CLI.

Tady je příklad z článku Použití rozhraní Azure REST API :

Všimněte si, jak $containerRegistryName?api-version zřetězí dohromady bez chyby v Bashu.

# 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

Předání parametrů obsahujících symbol ampersand

Pokud máte scénář, ve kterém potřebujete předat ampersand v hodnotě parametru, mějte na paměti, že powershell interpretuje symbol ampersand (&). K tomu dochází pomocí parametru --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

Pokud ale použijete stejný test k přidání značky do skupiny prostředků, ampersand v hodnotě značky nezpůsobí chybu.

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"
}

Pokud máte scénář, ve kterém ampersand v hodnotě parametru způsobuje chybu, tady jsou některá řešení:

# 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']

Předání parametrů obsahujících symbol at (@)

Existují speciální znaky PowerShellu, například symbol at (@), což je operátor splatting v PowerShellu. Přidání zpětného znaméčka ` před speciální znak, který ho unikne. Hodnotu můžete také uzavřít do jednoduchých (') nebo dvojitých (") uvozovek.

V PowerShellu budou fungovat následující tři příklady:

  • parameterName '@parameters.json
  • parameterName '@parameters.json'
  • parameterName "@parameters.json"

Tento příklad nebude v PowerShellu fungovat:

  • parameterName @parameters.json

Tady je další příklad příkazu az ad app create : Všimněte si dvojitých uvozovek ("...") kolem názvu souboru JSON potřebného ve skriptovacím jazyce PowerShellu.

# Script for a PowerShell scripting language

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

Předání parametrů obsahujících JSON

U složitých argumentů, jako je řetězec JSON, je osvědčeným postupem použít konvenci Azure CLI @<file> k načtení ze souboru a obejít interpretaci prostředí. Příklady syntaxe JSON pro Bash, PowerShell a Cmd.exe najdete v uvozování rozdílů mezi skriptovacími jazyky – řetězce JSON.

Předání parametrů obsahujících páry klíč:hodnota

Některé hodnoty parametrů Azure CLI, jako jsou značky prostředků Azure, vyžadují páry klíč:hodnota. Pokud máte key mezeru nebo value speciální znak, syntaxe Bash a PowerShellu nejsou vždy stejné.

Příklady syntaxe pro Bash, PowerShell a Cmd najdete v tématu Vytvoření značek pro procvičování rozdílů v uvozování v kurzech Learn pro použití Azure CLI . Tento krok kurzu obsahuje příklady pro následující scénáře páru klíč:hodnota:

  • mezery
  • prázdné hodnoty
  • speciální znaky
  • proměnné

Symbol zastavení analýzy

Symbol zastavení analýzy (--%) zavedený v PowerShellu 3.0 přesměruje PowerShell, aby nepřekládaly vstup jako příkazy nebo výrazy PowerShellu. Když narazí na symbol zastavení analýzy, PowerShell považuje zbývající znaky na řádku za literál.

az --% vm create --name xxx

Zpracování chyb pro Azure CLI v PowerShellu

Příkazy Azure CLI můžete spouštět v PowerShellu, jak je popsáno v části Volba správného nástroje příkazového řádku Azure. Pokud ano, ujistěte se, že rozumíte zpracování chyb Azure CLI v PowerShellu. Konkrétně Azure CLI nevytáčí výjimky, které powershell zachytí.

Alternativou je použití $? automatické proměnné. Tato proměnná obsahuje stav posledního příkazu. Pokud předchozí příkaz selže, $? má hodnotu $False. Další informace najdete v tématu about_Automatic_Variables.

Následující příklad ukazuje, jak tato automatická proměnná může fungovat pro zpracování chyb:

# Script for a PowerShell scripting language

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

Příkaz az selže, protože chybí požadovaný --location parametr. Podmíněný příkaz najde hodnotu $? false a zapíše chybu.

Pokud chcete použít klíčová try slova a catch klíčová slova, můžete vytvořit throw výjimku pro try blok, který se má zachytit:

# 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 ve výchozím nastavení zachytává jenom ukončující chyby. Tento příklad nastaví globální proměnnou $ErrorActionPreference tak Stop , aby PowerShell mohl chybu zpracovat.

Podmíněný příkaz otestuje proměnnou $? a zjistí, jestli předchozí příkaz selhal. Pokud ano, throw klíčové slovo vytvoří výjimku, která se má zachytit. Blok catch lze použít k zápisu chybové zprávy nebo zpracování chyby.

Příklad se $ErrorActionPreference obnoví na výchozí hodnotu.

Další informace o zpracování chyb PowerShellu najdete v tématu Vše, co jste chtěli vědět o výjimkách.

Povolení dokončování tabulátoru v PowerShellu

Dokončování tabulátoru, označované také jako dokončené rozhraní příkazového řádku Azure, poskytuje dokončování vstupů, které poskytují rady, umožňují zjišťování a urychlují zadávání vstupu. Názvy příkazů, názvy skupin příkazů, parametry a určité hodnoty parametrů lze automaticky vložit do příkazového řádku stisknutím klávesy Tab .

Dokončování tabulátoru je ve výchozím nastavení povolené ve službě Azure Cloud Shell a ve většině linuxových distribucí. Počínaje Azure CLI verze 2.49 můžete povolit dokončování tabulátoru pro Azure CLI v PowerShellu. Postupujte následovně:

  1. Vytvořte nebo upravte profil uložený v proměnné $PROFILE. Nejjednodušší způsob je spustit notepad $PROFILE v PowerShellu. Další informace najdete v tématu Vytvoření profilu a profilů a zásad spouštění.

  2. Do profilu PowerShellu přidejte následující kód:

    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. Pokud chcete zobrazit všechny dostupné možnosti v nabídce, přidejte Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete ho do profilu PowerShellu.

Viz také