Overwegingen voor het uitvoeren van de Azure CLI in een PowerShell-omgeving

  • Artikel

Azure CLI is een hulpprogramma voor het beheren van Azure-resources via Azure CLI-referentieopdrachten die worden uitgevoerd in een Bash- en PowerShell-omgeving. Er zijn echter kleine syntaxisverschillen in parameteropmaak tussen omgevingen die onverwachte resultaten kunnen opleveren. Het doel van dit artikel is om u te helpen bij het oplossen van Azure CLI-syntaxisfouten bij het werken in een PowerShell-omgeving.

In dit artikel worden syntaxisverschillen vergeleken van Azure CLI-opdrachten die worden uitgevoerd in de volgende omgevingen:

  • Bash wordt uitgevoerd in een Linux-besturingssysteem met behulp van Azure Cloud Shell.
  • PowerShell wordt uitgevoerd in een Linux-besturingssysteem met behulp van Azure Cloud Shell.
  • Windows PowerShell die wordt uitgevoerd in Windows 11 met behulp van de PowerShell 5-terminal.
  • PowerShell wordt uitgevoerd in een Windows 11 met behulp van de PowerShell 7-terminal.

Als u niet eerder met CLI werkt, kan het verwarrend zijn om onderscheid te maken tussen een hulpprogramma en een omgeving . Hoe u het juiste opdrachtregelprogramma kiest, biedt een goede vergelijking.

Vereisten

Dit artikel is bedoeld om te lezen en te leren. Als u de voorbeelden echter wilt uitvoeren, selecteert u het Prepare your environments tabblad om de omgevingen te installeren die in dit artikel worden gebruikt.

Belangrijk

Wanneer u een Azure CLI-script hebt dat een fout produceert, kunt u overwegen hoe de omgeving waarin u werkt, de syntaxis van de Azure CLI-opdracht parseert.

Spaties doorgeven in Azure CLI-parameters

Wanneer u in Azure CLI een parameterwaarde met een spatie moet doorgeven, zijn er verschillen tussen besturingssystemen en omgevingen. In dit voorbeeld gebruikt u az storage account list en wijzigt u de naam van uitvoerkolommen met een woord dat een spatie bevat.

In dit voorbeeld ziet u de wrapper met enkele aanhalingstekens ('...') met ingesloten dubbele aanhalingstekens ("..."). Dit voorbeeld werkt ook in PowerShell in Linux.

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

Als u een filter wilt toevoegen, wordt de syntaxis gewijzigd. In dit voorbeeld wordt de --query parameterwaarde tussen dubbele aanhalingstekens ("...") verpakt en wordt een backslash (\) escape-teken gebruikt. Dit script wordt niet uitgevoerd in PowerShell.

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

Als u net de filtersyntaxis in een PowerShell-omgeving probeert uit te voeren, hebt u een foutbericht argument --query: invalid jmespath_type value: "[?creationTime >=..."ontvangen. In Bash in een Linux-omgeving ziet uw uitvoer er echter ongeveer als volgt uit:

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

Parameters doorgeven in een URL die een querytekenreeks bevat

Vraagtekens in URL's geven het einde van de URL en het begin van een querytekenreeks aan. Hier volgt een voorbeeld waarin stap 3 in Learn wordt geopend om de Azure CLI te gebruiken:

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

De ?view=azure-cli-2020-09-01-hybrid resultaten in de gewenste versie van de Azure CLI-referentie-inhoud.

Wanneer u Azure CLI-opdrachten uitvoert in een PowerShell-omgeving, kunnen vraagtekens deel uitmaken van een variabelenaam. Dit kan verwarring veroorzaken in azure CLI-parameterwaarden.

Hier volgt een voorbeeld uit het artikel Azure REST API gebruiken:

U ziet hoe $containerRegistryName?api-version u samenvoegt zonder fout in Bash.

# 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

Parameters doorgeven die een speciaal PowerShell-teken bevatten

Er zijn speciale tekens van PowerShell, zoals het at-symbool (@). Als u Azure CLI wilt uitvoeren in PowerShell, voegt u een backtick ` toe vóór het speciale teken om er een escape-teken aan toe te voegen. U kunt de waarde ook tussen enkele (') of dubbele (") aanhalingstekens plaatsen.

De volgende drie voorbeelden werken in PowerShell:

  • parameterNaam '@parameters.json
  • parameternaam '@parameters.json'
  • parameternaam '@parameters.json'

Dit voorbeeld werkt niet in PowerShell:

  • parameterName @parameters.json

Parameters doorgeven die JSON bevatten

Voor complexe argumenten, zoals een JSON-tekenreeks, kunt u het beste de Conventie van Azure CLI @<file> gebruiken om een bestand te laden om de interpretatie van de shell te omzeilen. Houd er rekening mee dat het symbool At (@) een splatting-operator in PowerShell is, dus deze moet worden geciteerd.

Er zijn goede voorbeelden in az ad app create die zowel JSON-bestandsinhoud als opdrachtvoorbeelden bevatten. Hier volgt een codefragment:

# Script for a Bash environment

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

Parameters doorgeven die sleutel-waardeparen bevatten

Voor sommige Azure CLI-parameterwaarden, zoals Azure-resourcetags, zijn sleutel-waardeparen vereist. Als uw key of value een spatie of speciaal teken bevat, zijn de Bash- en PowerShell-syntaxis niet altijd hetzelfde.

Zie Tags maken om te oefenen met het citeren van verschillen in de zelfstudie Learn voor het gebruik van de Azure CLI . Deze zelfstudiestap bevat voorbeelden voor scenario's voor Bash, PowerShell en Cmd voor de volgende sleutel-waardepaarscenario's:

  • Ruimten
  • lege waarden
  • speciale tekens
  • variabelen

Foutafhandeling voor Azure CLI in PowerShell

U kunt Azure CLI-opdrachten uitvoeren in PowerShell, zoals beschreven in het juiste Azure-opdrachtregelprogramma kiezen. Als dat het geval is, moet u weten hoe Azure CLI-fouten worden verwerkt in PowerShell. Azure CLI maakt met name geen uitzonderingen voor PowerShell om te vangen.

Een alternatief is het gebruik van de $? automatische variabele. Deze variabele bevat de status van de meest recente opdracht. Als de vorige opdracht mislukt, $? heeft de waarde van $False. Zie about_Automatic_Variables voor meer informatie.

In het volgende voorbeeld ziet u hoe deze automatische variabele kan werken voor foutafhandeling:

# Script for a PowerShell environment

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

De az opdracht mislukt omdat de vereiste --location parameter ontbreekt. De voorwaardelijke instructie vindt dat $? onwaar is en schrijft een fout.

Als u de try trefwoorden en catch trefwoorden wilt gebruiken throw , kunt u een uitzondering maken voor het try blok om te vangen:

# 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 ondervangt standaard alleen afsluitfouten. In dit voorbeeld wordt de $ErrorActionPreference globale variabele Stop zodanig ingesteld dat PowerShell de fout kan afhandelen.

Met de voorwaardelijke instructie wordt de $? variabele getest om te zien of de vorige opdracht is mislukt. Zo ja, dan maakt het throw trefwoord een uitzondering om te vangen. Het catch blok kan worden gebruikt om een foutbericht te schrijven of de fout af te handelen.

In het voorbeeld wordt $ErrorActionPreference de standaardwaarde hersteld.

Zie Alles wat u wilt weten over uitzonderingen voor meer informatie over de afhandeling van PowerShell-fouten.

Tabvoltooiing inschakelen in PowerShell

Tabvoltooiing, ook wel 'Azure CLI completers' genoemd, biedt voltooiing op invoer om hints te bieden, detectie in te schakelen en invoerinvoer te versnellen. Opdrachtnamen, opdrachtgroepnamen, parameters en bepaalde parameterwaarden kunnen automatisch worden ingevoegd in de opdrachtregel door op de Tab-toets te drukken.

Tabvoltooiing is standaard ingeschakeld in Azure Cloud Shell en in de meeste Linux-distributies. Vanaf Azure CLI versie 2.49 kunt u tabvoltooiing inschakelen voor de Azure CLI in PowerShell. Volg vervolgens deze stappen:

  1. Maak of bewerk het profiel dat is opgeslagen in de variabele $PROFILE. De eenvoudigste manier is om te worden uitgevoerd notepad $PROFILE in PowerShell. Zie Hoe u uw profiel- en profielbeleid en uitvoeringsbeleid maakt voor meer informatie.

  2. Voeg de volgende code toe aan uw PowerShell-profiel:

    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. Als u alle beschikbare opties in het menu wilt weergeven, voegt u dit toe Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete aan uw PowerShell-profiel.

Zie ook