Tipps für die erfolgreiche Verwendung der Azure CLI

Azure CLI ist ein Befehlszeilentool, mit dem Sie Azure-Ressourcen aus vielen Shellumgebungen konfigurieren und verwalten können. Nachdem Sie Ihre bevorzugte Shellumgebung ausgewählt und die Azure CLI installiert haben, finden Sie in diesem Artikel nützliche Tipps zum Vermeiden häufiger Fallstricke und erfolgreiche Verwendung der Azure CLI.

Weitere Informationen zu bestimmten Azure CLI-Befehlen finden Sie in der Azure CLI-Referenzliste.

Ausgabeformatierung

Mit Azure CLI-Befehlen werden drei gängige Ausgabeformate verwendet:

  1. Das json-Format zeigt Informationen als JSON-Zeichenfolge an.

    • JSON liefert die umfassendsten Informationen.
    • Dieses Format ist der Standardwert, sie können jedoch den Parameter --output verwenden, um eine andere Option anzugeben.
    • Verwenden Sie az config (z. B. az config set core.output=table), um das globale Standardformat in eine Ihrer persönlichen Einstellungen zu ändern.
    • Das JSON-Format behält die doppelten Anführungszeichen bei, was es im Allgemeinen für Skripterstellungszwecke ungeeignet macht.
  2. Das table-Format stellt die Ausgabe als lesbare Tabelle dar. Sie können angeben, welche Werte in der Tabelle angezeigt werden, und Abfragen verwenden, um die Ausgabe anzupassen, wie hier gezeigt:

    # command
    az vm show --resource-group myResourceGroup --name myVMname --query "{name: name, os:storageProfile.imageReference.offer}" --output table
    
    # output
    Name    Os
    ------  ------------
    myVMname   UbuntuServer
    
  3. Das tsv-Format gibt durch Tabstopp oder Zeilenumbruch getrennte Werte ohne zusätzliche Formatierung, Schlüssel oder andere Symbole zurück.

    • Das TSV-Format ist gut für kompakte Ausgaben und Skripterstellungszwecke geeignet.
    • Beim TSV-Format werden doppelte Anführungszeichen entfernt, die im JSON-Format beibehalten werden.
    • Verwenden Sie den Parameter --query, um das gewünschte Format für TSV anzugeben.
    export vm_ids=$(az vm list --show-details --resource-group myResourceGroup --query "[?powerState=='VM running'].id" --output tsv)
    az vm stop --ids $vm_ids
    

Weitere Informationen zu diesen und anderen Formaten finden Sie unter Ausgabeformate für Azure CLI-Befehle.

Übergeben von Werten an einen anderen Befehl

Wenn der Wert mehrmals verwendet wird, sollten Sie ihn einer Variablen zuweisen. Variablen ermöglichen es Ihnen, Werte mehrmals zu verwenden oder allgemeinere Skripts zu erstellen. In diesem Beispiel wird einer Variablen eine ID zugewiesen, die mit dem Befehl az vm list ermittelt wurde.

# assign the list of running VMs to a variable
running_vm_ids=$(az vm list --resource-group MyResourceGroup --show-details \
    --query "[?powerState=='VM running'].id" --output tsv)

# verify the value of the variable
echo $running_vm_ids

Erwägen Sie den Einsatz von Piping, wenn der Wert nur einmal verwendet wird. (Die Piping übergibt die Ausgabe eines Befehls als Eingabe an einen zweiten Befehl.)

az vm list --query "[?powerState=='VM running'].name" --output tsv | grep my_vm

Für Listen mit mehreren Werten sollten Sie die folgenden Optionen berücksichtigen:

  1. Verwenden Sie eine „for“-Schleife, falls Sie weitere Kontrollen für das Ergebnis benötigen:

    #!/usr/bin/env bash
    for vmList in $(az vm list --resource-group MyResourceGroup --show-details --query "[?powerState=='VM running'].id"   --output tsv); do
        echo stopping $vmList
        az vm stop --ids $vmList
        if [ $? -ne 0 ]; then
            echo "Failed to stop $vmList"
            exit 1
        fi
        echo $vmList stopped
    done
    
  2. Verwenden Sie alternativ xargs und ggf. das Flag -P, um die Vorgänge parallel auszuführen und so die Leistung zu verbessern:

    az vm list --resource-group MyResourceGroup --show-details \
      --query "[?powerState=='VM stopped'].id" \
      --output tsv | xargs -I {} -P 10 az vm start --ids "{}"
    
  3. Darüber hinaus verfügt die Azure CLI noch über integrierte Unterstützung für die Verarbeitung von Befehlen mit mehreren parallelen --ids, um den gleichen Effekt wie mit „xargs“ zu erzielen. @- wird zum Abrufen von Werten aus der Pipe verwendet:

    az vm list --resource-group MyResourceGroup --show-details \
      --query "[?powerState=='VM stopped'].id" \
      --output tsv | az vm start --ids @-
    

Weitere Informationen zur Verwendung von Bash-Konstrukten mit der Azure CLI einschließlich Schleifen, Fallanweisungen, if...then...else-Ausdrücke und Fehlerbehandlung finden Sie unter Erlernen der Verwendung von Bash mit der Azure CLI.

Verwenden von Anführungszeichen in Parametern

Beachten Sie bei der Verwendung von Azure CLI-Befehlen, wie Ihre Shell Anführungszeichen und Escapezeichen verwendet. Wenn Sie Skripts unterstützen, die in verschiedenen Shells verwendet werden, verstehen Sie, wie sie unterschiedlich sind.

Hinweis

Aufgrund eines bekannten Problems in PowerShell gelten für Escapezeichen einige zusätzliche Regeln. Weitere Informationen finden Sie unter Probleme mit Anführungszeichen bei PowerShell.

Hier sind einige Vorschläge angegeben, mit denen unerwartete Ergebnisse vermieden werden können:

  • Wenn Sie einen Parameter angeben, der Leerzeichen enthält, schließen Sie ihn in Anführungszeichen ein.

  • In Bash oder PowerShell werden sowohl einfache als auch doppelte Anführungszeichen richtig interpretiert. In der Windows-Eingabeaufforderung werden nur doppelte Anführungszeichen ordnungsgemäß interpretiert – einfache Anführungszeichen werden als Teil des Werts behandelt.

  • Wenn Ihr Befehl nur unter Bash (oder Zsh) ausgeführt wird, verwenden Sie einfache Anführungszeichen, um den Inhalt in der JSON-Zeichenfolge beizubehalten. Einfache Anführungszeichen sind erforderlich, wenn Inline-JSON-Werte bereitgestellt werden. Dieser JSON-Code ist beispielsweise in Bash korrekt: '{"key": "value"}'.

  • Wenn Ihr Befehl über eine Windows-Eingabeaufforderung ausgeführt wird, müssen Sie doppelte Anführungszeichen verwenden. Falls der Wert doppelte Anführungszeichen enthält, müssen Sie ihn mit Escapezeichen versehen. Die Entsprechung der JSON-Zeichenfolge oben ist "{\"key\": \"value\"}".

  • Wenn Ihr Wert in PowerShell eine leere Zeichenfolge ist, verwenden Sie '""'.

  • Wenn Ihr Wert in Bash oder PowerShell eine leere Zeichenfolge in Anführungszeichen ('') ist, verwenden Sie "''".

  • Verwenden Sie die @<file>-Konvention der Azure CLI für das Laden aus der Datei, um die Interpretationsmechanismen der Shell zu umgehen.

    az ad app create --display-name myName --native-app --required-resource-accesses @manifest.json
    
  • Bash wertet doppelte Anführungszeichen in exportierten Variablen aus. Entspricht dieses Verhalten nicht Ihren Vorstellungen, versehen Sie die Variable mit Escapezeichen: "\$variable".

  • Einige Azure CLI-Befehle verwenden eine Liste mit durch Leerzeichen getrennten Werten.

    • Wenn der Schlüsselname oder -wert Leerzeichen enthält, umschließen Sie das gesamte Paar: "my key=my value". Beispiel:

      az web app config app settings set --resource-group myResourceGroup --name myWebAppName --settings "client id=id1" "my name=john"
      
    • Wenn ein CLI-Parameter angibt, dass er eine durch Leerzeichen getrennte Liste akzeptiert, wird eines von zwei Formaten erwartet:

      1. Ohne Anführungszeichen, durch Leerzeichen getrennte Liste --parameterName firstValue secondValue
      2. Mit Anführungszeichen, durch Leerzeichen getrennte Liste --parameterName "firstValue" "secondValue"

      In diesem Beispiel handelt es sich um eine Zeichenfolge mit einem Leerzeichen darin. Es ist keine durch Leerzeichen getrennte Liste: --parameterName "firstValue secondValue".

  • Es gibt Sonderzeichen in PowerShell, z. B. @. Fügen Sie zum Ausführen der Azure CLI in PowerShell ` als Escapezeichen vor dem Sonderzeichen ein. Sie können den Wert auch in einfache oder doppelte Anführungszeichen "/" setzen.

    # The following three examples will work in PowerShell
    --parameterName `@parameters.json
    --parameterName '@parameters.json'
    --parameterName "@parameters.json"
    
    # This example will not work in PowerShell
    --parameterName @parameters.json
    
  • Bei Verwendung des Parameters --query mit einem Befehl müssen einige Zeichen von JMESPath in der Shell mit Escapezeichen versehen werden.

    Diese drei Befehle sind korrekt und führen in Bash zum gleichen Ergebnis:

    az version --query '"azure-cli"'
    az version --query \"azure-cli\"
    az version --query "\"azure-cli\""
    

    Hier sind zwei Beispiele für falsche Befehle in Bash:

    # Wrong, as the dash needs to be quoted in a JMESPath query
    az version --query azure-cli
    az version: error: argument --query: invalid jmespath_type value: 'azure-cli'
    
    # Wrong, as the dash needs to be quoted in a JMESPath query, but quotes are interpreted by Bash
    az version --query "azure-cli"
    az version: error: argument --query: invalid jmespath_type value: 'azure-cli'
    

    Weitere Beispielvergleiche zwischen Bash, PowerShell und Cmd finden Sie unter Abfragen der Azure CLI-Befehlsausgabe.


  • Die beste Möglichkeit zur Behandlung eines Problems mit Anführungszeichen ist die Ausführung des Befehls mit dem Flag --debug. Mit diesem Flag werden die Argumente, die von der Azure CLI tatsächlich empfangen werden, in Python-Syntax angezeigt.

    # Correct
    $ az '{"key":"value"}' --debug
    Command arguments: ['{"key":"value"}', '--debug']
    
    # Correct
    $ az "{\"key\":\"value\"}" --debug
    Command arguments: ['{"key":"value"}', '--debug']
    
    # Wrong, as quotes and spaces are interpreted by Bash
    $ az {"key": "value"} --debug
    Command arguments: ['{key:', 'value}', '--debug']
    
    # Wrong, as quotes are interpreted by Bash
    $ az {"key":"value"} --debug
    Command arguments: ['{key:value}', '--debug']
    

Verwenden von Bindestrichen in Parametern

Beginnt der Wert eines Parameters mit einem Bindestrich, versucht die Azure CLI, ihn als Parameternamen zu analysieren. Wenn Sie ihn als Wert analysieren möchten, verwenden Sie =, um den Parameternamen und den Wert zu verketten: --password="-VerySecret".

Asynchrone Vorgänge

Vorgänge in Azure können beträchtliche Zeit in Anspruch nehmen. Die Konfiguration einer VM in einem Rechenzentrum erfolgt beispielsweise nicht sofort. Die Azure CLI wartet, bis der Befehl abgeschlossen ist, bevor andere Befehle akzeptiert werden. Viele Befehle bieten daher einen --no-wait-Parameter, wie hier gezeigt:

az group delete --name MyResourceGroup --no-wait

Beim Löschen einer Ressourcengruppe werden auch alle zugehörigen Ressourcen entfernt. Das Entfernen dieser Ressourcen kann sehr lange dauern. Wenn Sie den Befehl mit dem Parameter --no-wait ausführen, kann die Konsole neue Befehle akzeptieren, ohne das Entfernen zu unterbrechen.

Viele Befehle bieten eine Warteoption, mit der die Konsole angehalten wird, bis eine Bedingung erfüllt ist. Im folgenden Beispiel wird der Befehl az vm wait verwendet, um das parallele Erstellen unabhängiger Ressourcen zu unterstützen:

az vm create --resource-group VMResources --name virtual-machine-01 --image centos --no-wait
az vm create --resource-group VMResources --name virtual-machine-02 --image centos --no-wait

subscription=$(az account show --query "id" -o tsv)
vm1_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-01"
vm2_id="/subscriptions/$subscription/resourceGroups/VMResources/providers/Microsoft.Compute/virtualMachines/virtual-machine-02"
az vm wait --created --ids $vm1_id $vm2_id

Nach der Erstellung der beiden IDs können Sie die Konsole wieder nutzen.

Verwendung hinter einem Proxy

Wenn Sie Azure CLI über einen Proxyserver verwenden, der selbstsignierte Zertifikate verwendet, kann die von der Azure CLI verwendete Python-Anforderungsbibliothek den folgenden Fehler verursachen: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Legen Sie zur Behebung dieses Fehlers die Umgebungsvariable REQUESTS_CA_BUNDLE auf den Pfad der CA-Bundlezertifikatdatei im PEM-Format fest.

Betriebssystem Standardbundle der Zertifizierungsstelle
Windows 32-Bit C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Windows (64-Bit) C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem
Ubuntu/Debian Linux /opt/az/lib/python<version>/site-packages/certifi/cacert.pem
CentOS/RHEL/SUSE Linux /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem
macOS /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem

Fügen Sie das Zertifikat des Proxyservers an die CA-Bundlezertifikatdatei an, oder kopieren Sie den Inhalt in eine andere Zertifikatdatei. Legen Sie dann REQUESTS_CA_BUNDLE auf den neuen Dateispeicherort fest. Hier sehen Sie ein Beispiel:

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

Einige Proxys erfordern eine Authentifizierung. Das Format der Umgebungsvariablen HTTP_PROXY oder HTTPS_PROXY sollte die Authentifizierung beinhalten, etwa HTTPS_PROXY="https://username:password@proxy-server:port". Ausführliche Informationen finden Sie unter Konfigurieren von Proxys für die Azure-Bibliotheken.

Gleichzeitige Ausführung

Wenn Sie Azure CLI-Befehle gleichzeitig auf demselben Computer ausführen, können Schreibkonflikte auftreten, wenn mehrere Azure CLI-Befehle in denselben MSAL-Tokencache schreiben.

Um potenzielle Fehler zu vermeiden, können Sie den Azure CLI-Konfigurationsordner für jedes Skript isolieren, indem Sie die Umgebungsvariable AZURE_CONFIG_DIR für jedes Skript auf ein separates Verzeichnis festlegen. Azure CLI-Befehle in diesem Skript speichern die Konfiguration und den Tokencache am konfigurierten Speicherort und nicht im Standardordner ~/.azure.

export AZURE_CONFIG_DIR=/my/config/dir

Generische Updateparameter

Azure CLI-Befehlsgruppen enthalten häufig einen update-Befehl. Azure Virtual Machines enthält beispielsweise den Befehl az vm update. Die meisten update-Befehle bieten diese drei generischen Parameter: --add, --set und --remove.

Die Parameter --set und --add verwenden eine Liste von durch Leerzeichen getrennten Schlüssel-Wert-Paaren: key1=value1 key2=value2. Verwenden Sie zum Anzeigen der Eigenschaften, die aktualisiert werden können, einen show-Befehl, etwa az vm show.

az vm show --resource-group VMResources --name virtual-machine-01

Sie können eine JSON-Zeichenfolge verwenden, um den Befehl zu vereinfachen. Verwenden Sie beispielsweise den folgenden Wert, um einen neuen Datenträger an einen virtuellen Computer anzufügen:

az vm update --resource-group VMResources --name virtual-machine-01 \
--add storageProfile.dataDisks "{\"createOption\": \"Attach\", \"managedDisk\":
   {\"id\":
   \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/yg/providers/Microsoft.Compute/disks/yg-disk\"},
   \"lun\": 1}"

Generische Ressourcenbefehle (az-Ressource)

Ein Dienst, den Sie verwenden möchten, wird möglicherweise noch nicht von der Azure CLI unterstützt. Sie können die Befehle vom Typ az resource verwenden, um mit diesen Ressourcen zu arbeiten.

Wenn Sie nur create- oder update-Befehle benötigen, verwenden Sie az deployment group create. Arbeitsbeispiele finden Sie unter Azure-Schnellstartvorlagen.

REST-API-Befehle (az rest)

Wenn generische update-Parameter und az resource Ihre Anforderungen nicht erfüllen, können Sie den Befehl az rest verwenden, um die REST-API aufzurufen. Bei dem Befehl wird die Authentifizierung automatisch mit den bereits eingegebenen Anmeldeinformationen durchgeführt und der Header Content-Type: application/json festgelegt. Weitere Informationen finden Sie unter Azure-REST-API-Referenz.

Dieses Beispiel funktioniert mit der Microsoft Graph-API. Rufen Sie zum Aktualisieren von Umleitungs-URIs für eine Anwendung die REST-API zum Aktualisieren der Anwendung auf, wie in diesem Code gezeigt:

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

Bei Verwendung von --uri-parameters für Anforderungen in Form von OData sollten Sie darauf achten, $ in unterschiedlichen Umgebungen mit Escapezeichen zu versehen: in Bash sollte $ zu \$ werden, und in PowerShell sollte $ zu `$ werden.

Skriptbeispiele

Hier sind Beispiele für die Verwendung von Variablen und Schleifen in einer Liste beim Arbeiten mit Azure Virtual Machines. Ausführliche Beispiele zur Verwendung von Bash-Konstrukten mit der Azure CLI einschließlich Schleifen, Fallanweisungen, if...then...else-Ausdrücke und Fehlerbehandlung finden Sie unter Erlernen der Verwendung von Bash mit der Azure CLI.

Verwenden Sie diese Skripts, um IDs in Variablen zu speichern:

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
   `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    SET "vm_ids=%%F %vm_ids%"  :: construct the id list
)
az vm stop --ids %vm_ids% :: CLI stops all VMs in parallel

Verwenden Sie diese Skripts zum Durchlaufen einer Liste per Schleifenvorgang:

ECHO OFF
SETLOCAL
FOR /F "tokens=* USEBACKQ" %%F IN (
    `az vm list --resource-group VMResources --show-details --query "[?powerState=='VM running'].id" --output tsv`
) DO (
    ECHO Stopping %%F
    az vm stop --ids %%F
)

Siehe auch