Delen via

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

  • Artikel

Azure CLI is een hulpprogramma voor het beheren van Azure-resources via Azure CLI-referentieopdrachten die worden uitgevoerd in een Bash- en PowerShell-scripttaal. Er zijn echter kleine syntaxisverschillen in parameteropmaak tussen scripttalen 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-scripttaal.

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

  • 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 scripttaal. 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 scripttalen 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 scripttaal 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 scripttalen. 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 hebt geprobeerd de filtersyntaxis uit te voeren in een PowerShell-scripttaal, 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-scripttaal, 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 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

Parameters doorgeven die het ampersandsymbool bevatten

Als u een scenario hebt waarin u een ampersand moet doorgeven in een parameterwaarde, moet u er rekening mee houden dat het ampersand-symbool (&) wordt geïnterpreteerd door PowerShell. U kunt dit zien met behulp van de --debug parameter:

az "a&b" --debug

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

Als u echter dezelfde test gebruikt om een tag toe te voegen aan een resourcegroep, veroorzaakt het ampersand in de tagwaarde geen fout.

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

Als u een scenario hebt waarin de ampersand in een parameterwaarde een fout veroorzaakt, zijn er enkele oplossingen:

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

Parameters doorgeven die een at-symbool (@) bevatten

Er zijn speciale tekens van PowerShell, zoals het at-symbool (@) dat een splatting-operator in PowerShell is. Voeg een backtick ` toe vóór het speciale teken om het te ontsnappen. 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

Hier volgt een ander voorbeeld in de az ad app create opdracht: Let op de dubbele aanhalingstekens ("...") rond de JSON-bestandsnaam die nodig is in een PowerShell-scripttaal.

# Script for a PowerShell scripting language

az ad app create --display-name myTestAppName `
    --is-fallback-public-client `
    --required-resource-accesses "@manifest.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. Zie Voor voorbeelden van JSON-syntaxis voor Bash, PowerShell en Cmd.exe , de verschillen tussen scripttalen - JSON-tekenreeksen.

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 voor syntaxisvoorbeelden voor Bash, PowerShell en Cmd om te oefenen met het citeren van verschillen in de zelfstudie Learn voor het gebruik van de Azure CLI . Deze zelfstudiestap bevat voorbeelden voor de volgende scenario's voor sleutel-waardepaar:

  • Ruimten
  • lege waarden
  • speciale tekens
  • variabelen

Symbool voor stoppen-parseren

Het stopparseringsymbool (--%), geïntroduceerd in PowerShell 3.0, stuurt PowerShell om te onthouden van het interpreteren van invoer als PowerShell-opdrachten of -expressies. Wanneer er een stopparseringsymbool optreedt, worden de resterende tekens in de regel in PowerShell als een letterlijke waarde behandeld.

az --% vm create --name xxx

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

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