Dela via

Överväganden för att köra Azure CLI på ett PowerShell-skriptspråk

  • Artikel

Azure CLI är ett verktyg för att hantera Azure-resurser via Azure CLI-referenskommandon som körs på både ett Bash- och PowerShell-skriptspråk. Det finns dock små syntaxskillnader i parameterformatering mellan skriptspråk som kan resultera i oväntade resultat. Syftet med den här artikeln är att hjälpa dig att lösa Azure CLI-syntaxfel när du arbetar på ett PowerShell-skriptspråk.

I den här artikeln jämförs syntaxskillnaderna mellan Azure CLI-kommandon som körs på följande skriptspråk:

  • Bash körs i ett Linux-operativsystem med Hjälp av Azure Cloud Shell.
  • PowerShell körs i ett Linux-operativsystem med Azure Cloud Shell.
  • Windows PowerShell körs i Windows 11 med PowerShell 5-terminalen.
  • PowerShell körs i en Windows 11 med PowerShell 7-terminalen.

Om du inte har använt CLI tidigare kan det vara förvirrande att skilja mellan ett verktyg och ett skriptspråk. Att välja rätt kommandoradsverktyg ger en bra jämförelse.

Förutsättningar

Den här artikeln är avsedd för dig att läsa och lära dig. Men om du vill köra exemplen väljer du fliken Prepare your environments för att installera skriptspråken som används i den här artikeln.

Viktigt!

När du har ett Azure CLI-skript som skapar ett fel bör du fundera på hur skriptspråket du arbetar i parsar Azure CLI-kommandosyntaxen.

Skicka blanksteg i Azure CLI-parametrar

När du i Azure CLI behöver skicka ett parametervärde som innehåller ett blanksteg, finns det skillnader mellan operativsystem och skriptspråk. I det här exemplet använder du az storage account list och byter namn på utdatakolumner med ett ord som innehåller ett blanksteg.

I det här exemplet bör du lägga märke till den enkla offertomslutningen ('...') med inbäddade dubbla citattecken ("..."). Det här exemplet fungerar också i PowerShell i Linux.

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

Om du vill lägga till ett filter ändras syntaxen. Observera hur det här exemplet omsluter --query parametervärdet med dubbla citattecken ("...") och använder ett omvänt snedstreck (\) escape-tecken. Det här skriptet körs inte i PowerShell.

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

Om du bara försökte köra filtersyntaxen på ett PowerShell-skriptspråk fick du felmeddelandet argument --query: invalid jmespath_type value: "[?creationTime >=...". Men i Bash i en Linux-miljö liknar dina utdata följande:

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

Skicka parametrar i en URL som innehåller en frågesträng

Frågetecken i URL:er anger slutet på URL:en och början av en frågesträng. Här är ett exempel som öppnar steg 3 i Learn för att använda Azure CLI:

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

Resultatet ?view=azure-cli-2020-09-01-hybrid blir den önskade versionen av Azure CLI-referensinnehållet.

När du kör Azure CLI-kommandon på ett PowerShell-skriptspråk tillåter PowerShell att frågetecken ingår i ett variabelnamn. Detta kan skapa förvirring i Azure CLI-parametervärden.

Här är ett exempel från artikeln Använd Azure REST API :

Observera hur $containerRegistryName?api-version sammanfogar utan fel i Bash.

# 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

Skicka parametrar som innehåller et-symbolen

Om du har ett scenario där du behöver skicka ett et-värde i ett parametervärde bör du vara medveten om att symbolen etand (&) tolkas av PowerShell. Du kan se detta hända med hjälp av parametern --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

Men om du använder samma test för att lägga till en tagg i en resursgrupp orsakar et-värdet i taggvärdet inget fel.

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

Om du har ett scenario där et-värdet i ett parametervärde orsakar ett fel, finns följande lösningar:

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

Skicka parametrar som innehåller en symbol vid (@)

Det finns specialtecken i PowerShell, till exempel symbolen på (@) som är en splattingoperator i PowerShell. Lägg till en backtick ` före specialtecknet för att undvika den. Du kan också omsluta värdet i enkla (') eller dubbla (") citattecken.

Följande tre exempel fungerar i PowerShell:

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

Det här exemplet fungerar inte i PowerShell:

  • parameterName @parameters.json

Här är ett annat exempel i az ad app create kommandot: Lägg märke till de dubbla citattecken ("...") runt det JSON-filnamn som behövs i ett PowerShell-skriptspråk.

# Script for a PowerShell scripting language

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

Skicka parametrar som innehåller JSON

För komplexa argument som en JSON-sträng är det bästa sättet att använda Azure CLI:s @<file> konvention för att läsa in från en fil för att kringgå gränssnittets tolkning. JSON-syntaxexempel för Bash, PowerShell och Cmd.exe finns i Citera skillnader mellan skriptspråk – JSON-strängar.

Skicka parametrar som innehåller nyckel:värdepar

Vissa Azure CLI-parametervärden, till exempel Azure-resurstaggar, kräver nyckel:värde-par. Om ditt key eller value innehåller ett blanksteg eller specialtecken är Bash- och PowerShell-syntaxen inte alltid desamma.

Syntaxexempel för Bash, PowerShell och Cmd finns i Skapa taggar för att öva på att citera skillnader i självstudiekursen Lär dig att använda Azure CLI . Det här självstudiesteget innehåller exempel på följande key:value-parscenarier:

  • Utrymmen
  • tomma värden
  • Specialtecken
  • variabler

Stoppparsningssymbol

Stoppparsningssymbolen (--%), som introducerades i PowerShell 3.0, instruerar PowerShell att avstå från att tolka indata som PowerShell-kommandon eller -uttryck. När den stöter på en stoppparsningssymbol behandlar PowerShell de återstående tecknen på raden som en literal.

az --% vm create --name xxx

Felhantering för Azure CLI i PowerShell

Du kan köra Azure CLI-kommandon i PowerShell enligt beskrivningen i Välj rätt Azure-kommandoradsverktyg. Om du gör det bör du vara säker på att du förstår Azure CLI-felhanteringen i PowerShell. I synnerhet skapar Inte Azure CLI undantag för PowerShell att fånga.

Ett alternativ är att använda den $? automatiska variabeln. Den här variabeln innehåller status för det senaste kommandot. Om föregående kommando misslyckas $? har värdet $False. Mer information finns i about_Automatic_Variables.

I följande exempel visas hur den här automatiska variabeln kan fungera för felhantering:

# Script for a PowerShell scripting language

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

Kommandot az misslyckas eftersom den saknar den obligatoriska --location parametern. Villkorssatsen finner att det $? är falskt och skriver ett fel.

Om du vill använda nyckelorden try och catch kan du använda throw för att skapa ett undantag för blocket try att fånga:

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

Som standard fångar PowerShell endast avslutande fel. I det här exemplet anges den $ErrorActionPreference globala variabeln till så att Stop PowerShell kan hantera felet.

Villkorssatsen testar variabeln $? för att se om föregående kommando misslyckades. I så fall skapar nyckelordet throw ett undantag att fånga. Blocket catch kan användas för att skriva ett felmeddelande eller hantera felet.

Exemplet återställs $ErrorActionPreference till standardvärdet.

Mer information om PowerShell-felhantering finns i Allt du vill veta om undantag.

Aktivera flikens slutförande i PowerShell

Tabbavslut, även kallat "Azure CLI-slutförare", ger slutförande av indata för att ge tips, aktivera identifiering och påskynda inmatning. Kommandonamn, kommandogruppsnamn, parametrar och vissa parametervärden kan automatiskt infogas i kommandoraden genom att trycka på tabbtangenten.

Tabbavslut är aktiverat som standard i Azure Cloud Shell och i de flesta Linux-distributioner. Från och med Azure CLI version 2.49 kan du aktivera tabbar för Azure CLI i PowerShell. Följ de här stegen:

  1. Skapa eller redigera profilen som lagras i variabeln $PROFILE. Det enklaste sättet är att köra notepad $PROFILE i PowerShell. Mer information finns i Så här skapar du din profil och profil och körningsprincip.

  2. Lägg till följande kod i din PowerShell-profil:

    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. Om du vill visa alla tillgängliga alternativ på menyn lägger du till Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete i din PowerShell-profil.

Se även