Freigeben über

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

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 ist dazu gedacht, dass Sie ihn lesen und dabei 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.

Von Bedeutung

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.

Leerzeichen in Azure CLI-Parametern übergeben

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 den Wrapper für das einfache Anführungszeichen ('...'), der mit eingebetteten doppelten Anführungszeichen ("...") versehen ist. 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 ("...") gesetzt wird und ein Rückwärtsstrich (\) als 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:

/cli/azure/account?view=azure-cli-2020-09-01-hybrid.

Die ?view=azure-cli-2020-09-01-hybrid führt zur 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 in Bash fehlerfrei miteinander verkettet wird.

# 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 mit 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 denselben Test verwenden, um einer Ressourcengruppe ein Tag hinzuzufügen, führt das &-Zeichen im Tagwert zu keinem 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 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']

Parameter übergeben, 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 maskieren. 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.exefinden Sie unter Quoting-Unterschiede zwischen Skriptsprachen – JSON-Zeichenfolgen.

Parameter übergeben, die Schlüssel-Wert-Paare enthalten

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

Syntaxbeispiele für Bash, PowerShell und Cmd finden Sie im Tutorial "Tags erstellen, um Unterschiede im Zitieren zu üben" im 'Learn to use the Azure CLI'. Dieser Anleitungsschritt enthält Beispiele für die folgenden Schlüssel-Wert-Paar-Szenarien:

  • Räume
  • leere Werte
  • Sonderzeichen
  • variablen

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 Azure CLI in PowerShell

Sie können Azure CLI-Befehle in PowerShell ausführen, wie unter "Auswählen des richtigen Azure-Befehlszeilentools" beschrieben. Wenn Sie dies tun, stellen Sie sicher, dass Sie die Azure CLI-Fehlerbehandlung in PowerShell verstehen. Insbesondere erstellt Azure CLI keine Ausnahmen, die von PowerShell abgefangen werden können.

Eine Alternative besteht darin, die $? automatische Variable zu verwenden. Diese Variable enthält den Status des zuletzt verwendeten Befehls. Wenn der vorherige Befehl fehlschlägt, $? hat der Wert von $False. Weitere Informationen finden Sie unter about_Automatic_Variables.

Das folgende Beispiel zeigt, wie diese automatische Variable für die Fehlerbehandlung funktionieren kann:

# Script for a PowerShell scripting language

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

Der az Befehl schlägt fehl, da der erforderliche --location Parameter fehlt. Die bedingte Anweisung stellt fest, dass $? falsch ist und gibt einen Fehler aus.

Wenn Sie die Schlüsselwörter try und catch verwenden möchten, können Sie throw nutzen, um eine Ausnahme für den try Block zu erstellen, der erfasst werden soll.

# 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 fängt PowerShell nur Abbruchfehler ab. In diesem Beispiel wird die $ErrorActionPreference globale Variable so Stop festgelegt, dass PowerShell den Fehler behandeln kann.

Die bedingte Anweisung testet die $? Variable, um festzustellen, ob der vorherige Befehl fehlgeschlagen ist. Wenn ja, erstellt das throw Schlüsselwort eine Ausnahme, die erfasst werden soll. Der catch Block kann verwendet werden, um eine Fehlermeldung zu schreiben oder den Fehler zu behandeln.

Im Beispiel wird der Standardwert von $ErrorActionPreference wiederhergestellt.

Weitere Informationen zur PowerShell-Fehlerbehandlung finden Sie unter Alles, was Sie über Ausnahmen wissen möchten.

Aktivieren der Vervollständigung per TAB-TASTE in PowerShell

Die Tab-Vervollständigung, auch bekannt als „Azure CLI-Komplettierungen“, erlaubt die Vervollständigung von Eingaben, indem sie Hinweise bereitstellt, schnellere Entdeckung ermöglicht und die Eingabe beschleunigt. 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 Version 2.49 der Azure CLI können Sie die Tab-Vervollständigung in PowerShell aktivieren. Folgen Sie diesen Schritten:

  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