Überlegungen zum Ausführen der Azure CLI in einer PowerShell-Skriptsprache

  • Artikel

Azure CLI ist ein Tool zum Verwalten von Azure-Ressourcen über Azure CLI-Referenzbefehle, die in einer Bash- und PowerShell-Skriptsprache ausgeführt werden. Es gibt jedoch geringfügige Syntaxunterschiede bei der Parameterformatierung zwischen Skriptsprachen, die zu unerwarteten Ergebnissen führen können. Der Zweck dieses Artikels besteht darin, Azure CLI-Syntaxfehler beim Arbeiten in einer PowerShell-Skriptsprache zu beheben.

In diesem Artikel werden die Syntaxunterschiede von Azure CLI-Befehlen verglichen, die in den folgenden Skriptsprachen ausgeführt werden:

  • Bash, das in einem Linux-Betriebssystem mit Azure Cloud Shell ausgeführt wird.
  • PowerShell , die in einem Linux-Betriebssystem mit Azure Cloud Shell ausgeführt wird.
  • Windows PowerShell , die in Windows 11 mit dem PowerShell 5-Terminal ausgeführt wird.
  • PowerShell, die in einem Windows 11-Gerät mit dem PowerShell 7-Terminal ausgeführt wird.

Wenn Sie noch nicht mit CLI arbeiten, kann die Unterscheidung zwischen einem Tool und einer Skriptsprache verwirrend sein. Die Auswahl des richtigen Befehlszeilentools bietet einen guten Vergleich.

Voraussetzungen

Dieser Artikel richtet sich an Sie, um sie zu lesen und zu lernen. Wenn Sie jedoch die Beispiele ausführen möchten, wählen Sie die Prepare your environments Registerkarte aus, um die in diesem Artikel verwendeten Skriptsprachen zu installieren.

Wichtig

Wenn Sie über ein Azure CLI-Skript verfügen, das einen Fehler erzeugt, sollten Sie berücksichtigen, wie die Skriptsprache, in der Sie arbeiten, die Azure CLI-Befehlssyntax analysiert.

Übergeben von Leerzeichen in Azure CLI-Parametern

Wenn Sie in Azure CLI einen Parameterwert übergeben müssen, der ein Leerzeichen enthält, gibt es Unterschiede zwischen Betriebssystemen und Skriptsprachen. Verwenden Sie in diesem Beispiel die Az-Speicherkontoliste , und benennen Sie Ausgabespalten mit einem Wort um, das ein Leerzeichen enthält.

Beachten Sie in diesem Beispiel das einfache Anführungszeichen ('...')-Wrapper mit eingebetteten doppelten Anführungszeichen ("..."). Dieses Beispiel funktioniert auch in PowerShell in Linux.

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

Wenn Sie einen Filter hinzufügen möchten, ändert sich die Syntax. Beachten Sie, wie in diesem Beispiel der --query Parameterwert in doppelte Anführungszeichen ("...") umbrochen wird und ein umgekehrter Schrägstrich (\) escapezeichen verwendet wird. Dieses Skript wird in PowerShell nicht ausgeführt.

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

Wenn Sie gerade versucht haben, die Filtersyntax in einer PowerShell-Skriptsprache auszuführen, wurde die Fehlermeldung argument --query: invalid jmespath_type value: "[?creationTime >=..."angezeigt. In Bash in einer Linux-Umgebung ähnelt ihre Ausgabe jedoch folgendem:

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

Übergeben von Parametern in einer URL, die eine Abfragezeichenfolge enthält

Fragezeichen in URLs geben das Ende der URL und den Anfang einer Abfragezeichenfolge an. Hier ist ein Beispiel, das Schritt 3 in "Lernen" öffnet, um die Azure CLI zu verwenden:

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

Die ?view=azure-cli-2020-09-01-hybrid Ergebnisse in der gewünschten Version des Azure CLI-Referenzinhalts.

Wenn Sie Azure CLI-Befehle in einer PowerShell-Skriptsprache ausführen, lässt PowerShell Fragezeichen als Teil eines Variablennamens zu. Dies kann Verwirrung in Azure CLI-Parameterwerten erzeugen.

Im Folgenden finden Sie ein Beispiel aus dem Artikel "Verwenden der Azure REST-API ":

Beachten Sie, wie $containerRegistryName?api-version sie in Bash ohne Fehler miteinander verkettet werden.

# 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

Übergeben von Parametern, die das kaufmännische Und-Zeichen enthalten

Wenn Sie ein Szenario haben, in dem Sie ein kaufmännisches Und-Zeichen in einem Parameterwert übergeben müssen, beachten Sie, dass das kaufmännische Und-Zeichen (&) von PowerShell interpretiert wird. Dies wird mithilfe des --debug Parameters angezeigt:

az "a&b" --debug

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

Wenn Sie jedoch diesen Test verwenden, um einer Ressourcengruppe ein Tag hinzuzufügen, verursacht das kaufmännische Und-Zeichen im Tagwert keinen Fehler.

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

Wenn Sie ein Szenario haben, in dem das kaufmännische Und-Zeichen in einem Parameterwert einen Fehler verursacht, sind hier einige Lösungen aufgeführt:

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

Übergeben von Parametern, die ein At (@)-Symbol enthalten

Es gibt Sonderzeichen von PowerShell, z. B. das At (@)-Symbol, bei dem es sich um einen Splattingoperator in PowerShell handelt. Fügen Sie einen Backtick ` vor dem Sonderzeichen hinzu, um es zu escapen. Sie können den Wert auch in einfache (') oder doppelte (") Anführungszeichen setzen.

Die folgenden drei Beispiele funktionieren in PowerShell:

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

Dieses Beispiel funktioniert in PowerShell nicht:

  • parameterName @parameters.json

Hier ein weiteres Beispiel im az ad app create Befehl: Beachten Sie die doppelten Anführungszeichen ("...") um den JSON-Dateinamen, der in einer PowerShell-Skriptsprache erforderlich ist.

# Script for a PowerShell scripting language

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

Übergeben von Parametern, die JSON enthalten

Bei komplexen Argumenten wie einer JSON-Zeichenfolge empfiehlt es sich, die Konvention der @<file> Azure CLI zum Laden aus einer Datei zu verwenden, um die Interpretation der Shell zu umgehen. Beispiele für JSON-Syntax für Bash, PowerShell und Cmd.exe finden Sie unter Quoting-Unterschiede zwischen Skriptsprachen – JSON-Zeichenfolgen.

Übergeben von Parametern, die Schlüssel:Wert-Paare enthalten

Einige Azure CLI-Parameterwerte, z. B. Azure-Ressourcentags, erfordern Schlüssel:Wert-Paare. Wenn Ihr key Leerzeichen value oder Sonderzeichen enthält, sind die Bash- und PowerShell-Syntax nicht immer identisch.

Syntaxbeispiele für Bash, PowerShell und Cmd finden Sie unter "Erstellen von Tags", um Unterschiede im Lernprogramm zur Verwendung des Azure CLI-Lernprogramms zu üben. Dieser Lernprogrammschritt enthält Beispiele für die folgenden Schlüssel:Wert-Paarszenarien:

  • spaces
  • leere Werte
  • Sonderzeichen
  • variables

Symbol für die Stoppanalyse

Das in PowerShell 3.0 eingeführte Stop-Parsing-Symbol (--%) weist PowerShell auf, die Eingabe nicht als PowerShell-Befehle oder -Ausdrücke zu interpretieren. Wenn ein Stoppanalysesymbol auftritt, behandelt PowerShell die verbleibenden Zeichen in der Zeile als Literal.

az --% vm create --name xxx

Fehlerbehandlung für die Azure CLI in PowerShell

Sie können Azure CLI-Befehle in PowerShell ausführen, wie dies unter Auswählen des richtigen Azure-Befehlszeilentools beschrieben ist. Stellen Sie hierbei sicher, dass Sie mit der Azure CLI-Fehlerbehandlung in PowerShell vertraut sind. Beachten Sie vor allem, dass von der Azure CLI keine Ausnahmen erstellt werden, die von PowerShell abgefangen werden können.

Eine Alternative ist die Verwendung der automatischen Variablen $?. Diese Variable enthält den Status des letzten Befehls. Falls für den vorherigen Befehl ein Fehler auftritt, enthält $? den Wert $False. Weitere Informationen finden Sie unter about_Automatic_Variables.

Im folgenden Beispiel wird veranschaulicht, wie diese automatische Variable für die Fehlerbehandlung genutzt werden kann:

# Script for a PowerShell scripting language

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

Für den Befehl az tritt ein Fehler auf, weil dafür der erforderliche Parameter --location fehlt. Die Bedingungsanweisung ermittelt, dass $? auf „False“ festgelegt ist, und schreibt einen Fehler.

Wenn Sie die Schlüsselwörter try und catch verwenden möchten, können Sie mit throw eine Ausnahme für den abzufangenden try-Block erstellen:

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

Standardmäßig werden in PowerShell nur Fehler mit Abbruch abgefangen. In diesem Beispiel wird die globale Variable $ErrorActionPreference auf Stop festgelegt, damit der Fehler von PowerShell behandelt werden kann.

Die Bedingungsanweisung testet die Variable $? darauf, ob für den vorherigen Befehl ein Fehler aufgetreten ist. Wenn ja, wird über das Schlüsselwort throw eine Ausnahme erstellt, die abgefangen werden kann. Der catch-Block kann zum Schreiben einer Fehlermeldung oder Behandeln des Fehlers verwendet werden.

Im Beispiel wird für $ErrorActionPreference der Standardwert wiederhergestellt.

Weitere Informationen zur PowerShell-Fehlerbehandlung finden Sie unter Alles, was Sie schon immer über Ausnahmen wissen wollten.

Aktivieren der Vervollständigung per TAB-TASTE in PowerShell

Die Vervollständigung per TAB-TASTE, auch bekannt als „ Azure CLI-Vervollständigung“, erreicht die Vervollständigung der Eingaben durch das Bereitstellen von Hinweisen, das Aktivieren von Ermittlungen und das Beschleunigen der Eingabe. Befehlsnamen, Befehlsgruppennamen, Parameter und bestimmte Parameterwerte können durch Drücken der TAB-TASTE automatisch in die Befehlszeile eingefügt werden.

Die Vervollständigung per TAB-TASTE ist in Azure Cloud Shell und in den meisten Linux-Distributionen standardmäßig aktiviert. Ab Azure CLI Version 2.49 können Sie die Vervollständigung per TAB-TASTE für die Azure CLI in PowerShell aktivieren. Führen Sie folgende Schritte aus:

  1. Erstellen oder bearbeiten Sie das in der Variablen $PROFILE gespeicherte Profil. Die einfachste Möglichkeit ist die Ausführung von notepad $PROFILE in PowerShell. Weitere Informationen finden Sie unter Erstellen Ihres Profils und Profile und Ausführungsrichtlinie.

  2. Fügen Sie Ihrem PowerShell-Profil den folgenden Code hinzu:

    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. Um alle verfügbaren Optionen im Menü anzuzeigen, fügen Sie Ihrem PowerShell-Profil Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete hinzu.

Siehe auch