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

  • Artikel

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

In diesem Artikel werden die Syntaxunterschiede von Azure CLI-Befehlen verglichen, die in den folgenden Umgebungen 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 Umgebung 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 die Beispiele jedoch ausführen möchten, wählen Sie die Prepare your environments Registerkarte aus, um die in diesem Artikel verwendeten Umgebungen zu installieren.

Wichtig

Wenn Sie über ein Azure CLI-Skript verfügen, das einen Fehler erzeugt, sollten Sie berücksichtigen, wie die Umgebung, 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 Umgebungen. 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-Umgebung 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://learn.microsoft.com/en-us/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-Umgebung 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 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

Übergeben von Parametern, die ein PowerShell-Sonderzeichen enthalten

Es gibt Sonderzeichen von PowerShell, z. B. das Symbol "At (@)". Um Azure CLI in PowerShell auszuführen, fügen Sie einen Backtick ` vor dem Sonderzeichen hinzu, um es zu escapeen. 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

Ü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. Beachten Sie, dass das At (@) -Symbol ein Splattingoperator in PowerShell ist, daher sollte es an zitiert werden.

Es gibt gute Beispiele in az ad app create , die sowohl JSON-Dateiinhalte als auch Befehlsbeispiele enthalten. Hier sehen Sie einen Codeausschnitt:

# Script for a Bash environment

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

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

Weitere Informationen finden Sie unter Erstellen von Tags, um Unterschiede im Lernprogramm "Lernen" zu üben, um das Lernprogramm der Azure CLI zu verwenden. In diesem Lernprogrammschritt finden Sie Beispiele für Bash, PowerShell und Cmd für die folgenden Szenarien für Schlüssel:Wert-Paare:

  • spaces
  • leere Werte
  • Sonderzeichen
  • variables

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 environment

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

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