Freigeben über

Abfragen der Azure CLI-Befehlsausgabe mithilfe einer JMESPath-Abfrage

Die Azure CLI verwendet den --query Parameter, um eine JMESPath-Abfrage für die Ergebnisse von Befehlen auszuführen. JMESPath ist eine Abfragesprache für JSON, sodass Sie Daten aus der CLI-Ausgabe auswählen und ändern können.

Alle Befehle in Azure CLI unterstützen den --query Parameter. In diesem Artikel wird beschrieben, wie Sie die Features von JMESPath verwenden und Beispiele für Abfragen bereitstellen. Erfahren Sie mehr über JMESPath-Konzepte, die für abfragen auf der Registerkarte "Konzepte" nützlich sind. Beispiele für JMESPath-Abfragen finden Sie auf der Registerkarte "Beispiele".

Azure CLI verwendet Abfragen zum Auswählen und Ändern der Ausgabe von Azure CLI-Befehlen. Abfragen werden clientseitig auf dem zurückgegebenen JSON-Objekt des Azure CLI-Befehls vor jeder Anzeigeformatierung ausgeführt.

Die in Abfragen benötigten Escapezeichen unterscheiden sich für verschiedene Umgebungen. Es wird empfohlen, Abfragen in Azure Cloud Shell oder cmd auszuführen, da für diese Shells weniger Escapezeichen erforderlich sind. Um sicherzustellen, dass die Abfragebeispiele syntaktisch korrekt sind, wählen Sie die Registerkarte für die verwendete Shell aus.

CLI-Ergebnisse für Wörterbuch und Liste

CLI-Befehlsergebnisse werden zuerst als JSON für Abfragen behandelt, auch wenn das Ausgabeformat etwas anderes als JSON ist. CLI-Ergebnisse sind entweder ein JSON-Array oder ein Wörterbuch. Arrays sind Sequenzen von Objekten, die indiziert werden können, und Wörterbücher sind ungeordnete Objekte, auf die mit Schlüsseln zugegriffen wird.

Dies ist ein Beispiel für ein Array:

[ 
  1,
  2,
  3
]

Dies ist ein Beispiel für ein Wörterbuch:

{
  "isRunning": false,
  "time": "12:00",
  "number": 1
}

Befehle, die mehrere Objekte zurückgeben können , geben ein Array zurück, und Befehle, die immernur ein einzelnes Objekt zurückgeben, geben ein Wörterbuch zurück.

Abrufen von Eigenschaften in einem Wörterbuch

Wenn Sie mit Wörterbuchergebnissen arbeiten, können Sie mit nur dem Schlüssel auf Eigenschaften der obersten Ebene zugreifen. Das . Zeichen (Unterausdruck) wird verwendet, um auf Eigenschaften von geschachtelten Wörterbüchern zuzugreifen. Sehen Sie sich vor der Einführung von Abfragen die unveränderte Ausgabe des Befehls "az vm show " an:

az vm show --resource-group QueryDemo --name TestVM

Der Befehl gibt ein Wörterbuch aus. Einige Inhalte wurden weggelassen.

{
  "additionalCapabilities": null,
  "availabilitySet": null,
  "diagnosticsProfile": {
    "bootDiagnostics": {
      "enabled": true,
      "storageUri": "https://xxxxxx.blob.core.windows.net/"
    }
  },
  ...
  "osProfile": {
    "adminPassword": null,
    "adminUsername": "azureuser",
    "allowExtensionOperations": true,
    "computerName": "TestVM",
    "customData": null,
    "linuxConfiguration": {
      "disablePasswordAuthentication": true,
      "provisionVmAgent": true,
      "ssh": {
        "publicKeys": [
          {
            "keyData": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso",
            "path": "/home/azureuser/.ssh/authorized_keys"
          }
        ]
      }
    },
    "secrets": [],
    "windowsConfiguration": null
  },
  ....
}

Der folgende Befehl ruft die öffentlichen SSH-Schlüssel ab, die zum Herstellen einer Verbindung mit dem virtuellen Computer autorisiert sind, indem eine Abfrage hinzugefügt wird:

az vm show --resource-group QueryDemo --name TestVM --query "osProfile.linuxConfiguration.ssh.publicKeys"

[
  {
    "keyData": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso",
    "path": "/home/azureuser/.ssh/authorized_keys"
  }
]

Abfragezeichenfolgen sind groß-/kleinschreibungssensitiv. Wenn Sie z. B. "osProfile" in "OsProfile" in der vorherigen Abfrage ändern, werden die richtigen Ergebnisse nicht zurückgegeben.

Abrufen mehrerer Werte

Um mehr als eine Eigenschaft zu erhalten, platzieren Sie Ausdrücke, die durch Kommas getrennt sind, in eckigen Klammern [ ] (eine Mehrfachauswahlliste). Der folgende Befehl ruft den VM-Namen, den Administratorbenutzer und den SSH-Schlüssel auf einmal ab:

az vm show --resource-group QueryDemo --name TestVM --query "[name, osProfile.adminUsername, osProfile.linuxConfiguration.ssh.publicKeys[0].keyData]"

[
  "TestVM",
  "azureuser",
  "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso"
]

Diese Werte werden im Ergebnisarray in der Reihenfolge aufgelistet, in der sie in der Abfrage angegeben wurden. Da das Ergebnis ein Array ist, gibt es keine Schlüssel, die den Ergebnissen zugeordnet sind. Informationen zum Abrufen eines Wörterbuchs anstelle eines Arrays finden Sie im nächsten Abschnitt.

Umbenennen von Eigenschaften in einer Abfrage

Wenn Sie ein Wörterbuch anstelle eines Arrays abrufen möchten, wenn Sie mehrere Werte abfragen, verwenden Sie den { } Operator (Multiselect-Hash). Das Format für einen Multiselect-Hash lautet {displayName:JMESPathExpression, ...}. displayName ist die in der Ausgabe angezeigte Zeichenfolge und JMESPathExpression ist der zu bewertende JMESPath-Ausdruck. Ändern Sie das Beispiel aus dem letzten Abschnitt, indem Sie die Mehrfachauswahlliste in einen Hash ändern:

Hinweis

Wenn Sie ein Leerzeichen in einem neuen Spaltennamen verwenden möchten, z VM name . B. anstelle von VMName, ändern sich die Quotingregeln sowohl in Bash als auch in PowerShell. Beispiele finden Sie unter Pass spaces in Azure CLI-Parametern .

az vm show --resource-group QueryDemo --name TestVM --query "{VMName:name, admin:osProfile.adminUsername, sshKey:osProfile.linuxConfiguration.ssh.publicKeys[0].keyData}"

{
  "VMName": "TestVM",
  "admin": "azureuser",
  "ssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso"
}

Abrufen von Eigenschaften in einem Array

Ein Array besitzt keine eigenen Eigenschaften, kann aber indiziert werden. Dieses Feature wird im letzten Beispiel mit dem Ausdruck publicKeys[0] gezeigt, der das erste Element des publicKeys-Arrays abruft. Es gibt keine Garantie, dass die CLI-Ausgabe geordnet ist. Vermeiden Sie daher die Verwendung der Indizierung, es sei denn, Sie sind sicher über die Reihenfolge, oder es ist Ihnen egal, welches Element Sie erhalten. Wenn Sie auf die Eigenschaften von Elementen in einem Array zugreifen möchten, führen Sie einen von zwei Vorgängen aus: Flachmachen oder Filtern. In diesem Abschnitt wird beschrieben, wie Sie ein Array flacherten.

Das Abblenden eines Arrays erfolgt mit dem [] JMESPath-Operator. Alle Ausdrücke nach dem []-Operator werden auf jedes Element im aktuellen Array angewendet. Wenn [] am Anfang der Abfrage angezeigt wird, wird das CLI-Befehlsergebnis vereinfacht. Die Ergebnisse von az vm list können mit dieser Funktion überprüft werden. Die folgende Abfrage ruft den Namen, das Betriebssystem und den Administratornamen für jeden virtuellen Computer in einer Ressourcengruppe ab:

az vm list --resource-group QueryDemo --query "[].{Name:name, OS:storageProfile.osDisk.osType, admin:osProfile.adminUsername}"

[
  {
    "Name": "Test-2",
    "OS": "Linux",
    "admin": "sttramer"
  },
  {
    "Name": "TestVM",
    "OS": "Linux",
    "admin": "azureuser"
  },
  {
    "Name": "WinTest",
    "OS": "Windows",
    "admin": "winadmin"
  }
]

Jedes Array kann vereinfacht werden, nicht nur das ergebnis der obersten Ebene, das vom Befehl zurückgegeben wird. Im letzten Abschnitt wurde der Ausdruck osProfile.linuxConfiguration.ssh.publicKeys[0].keyData verwendet, um den öffentlichen SSH-Schlüssel für die Anmeldung abzurufen. Um jeden öffentlichen SSH-Schlüssel abzurufen, könnte der Ausdruck stattdessen als osProfile.linuxConfiguration.ssh.publicKeys[].keyDatageschrieben werden. Dieser Abfrageausdruck vereinfacht das osProfile.linuxConfiguration.ssh.publicKeys Array und führt dann den keyData Ausdruck für jedes Element aus:

az vm show --resource-group QueryDemo --name TestVM --query "{VMName:name, admin:osProfile.adminUsername, sshKeys:osProfile.linuxConfiguration.ssh.publicKeys[].keyData }"

{
  "VMName": "TestVM",
  "admin": "azureuser",
  "sshKeys": [
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso\n"
  ]
}

Filtern von Arrays mit booleschen Ausdrücken

Der andere Vorgang, der zum Abrufen von Daten aus einem Array verwendet wird, ist das Filtern. Das Filtern erfolgt mit dem [?...] JMESPath-Operator. Dieser Operator akzeptiert ein Prädikat als Inhalt. Ein Prädikat ist eine beliebige Aussage (einschließlich boolescher Eigenschaften), die entweder true oder false bewertet werden kann. Ausdrücke, bei denen das Prädikat zu true ausgewertet wird, werden in die Ausgabe einbezogen.

Die erste Abfrage veranschaulicht, wie die Namen aller Azure-Abonnements aufgelistet werden, die mit Ihrem Konto verbunden sind, dessen isDefault Eigenschaft wahr ist. Die zweite und dritte Abfrage zeigen zwei verschiedene Möglichkeiten zum Auflisten aller Abonnements, deren isDefault Eigenschaft falsch ist.

# Boolean values are assumed to be true, so you can directly evaluate the isDefault property to return the default subscription.
az account list --query "[?isDefault].name"

# To check if a Boolean property is false, you can use the comparison operator == or the logical operator !.
az account list --query '[?!isDefault].name'
az account list --query "[?isDefault == \`false\`].name"

JMESPath bietet die Standardvergleichs- und logischen Operatoren. Dazu gehören <, , <=, , >>=, und !===. JMESPath unterstützt auch die logischen Operatoren und (&&), oder (||) und nicht (!). Ausdrücke können innerhalb einer Klammer gruppiert werden, sodass komplexere Prädikatausdrücke möglich sind. Ausführliche Informationen zu Prädikaten und logischen Vorgängen finden Sie in der JMESPath-Spezifikation.

Im letzten Abschnitt haben Sie ein Array vereinfacht, um die vollständige Liste aller virtuellen Computer in einer Ressourcengruppe abzurufen. Mit der Verwendung von Filtern kann diese Ausgabe nur auf Linux-VMs beschränkt werden:

az vm list --resource-group QueryDemo --query "[?storageProfile.osDisk.osType=='Linux'].{Name:name,  admin:osProfile.adminUsername}" --output table

Name    Admin
------  ---------
Test-2  sttramer
TestVM  azureuser

Sie können auch numerische Werte wie die Größe des Betriebssystemdatenträgers filtern. Im folgenden Beispiel wird veranschaulicht, wie die Liste der virtuellen Computer gefiltert wird, um solche mit einer Datenträgergröße anzuzeigen, die größer als oder gleich 50 GB ist.

az vm list --resource-group QueryDemo --query "[?storageProfile.osDisk.diskSizeGb >=\`50\`].{Name:name,  admin:osProfile.adminUsername, DiskSize:storageProfile.osDisk.diskSizeGb }" --output table

Name     Admin     DiskSize
-------  --------  --------
WinTest  winadmin  127

Bei großen Arrays kann es schneller sein, den Filter anzuwenden, bevor Daten ausgewählt werden.

Von Bedeutung

In JMESPath sind Zeichenfolgen immer von einfachen Anführungszeichen (') oder Escape-Zeichen (`) umgeben. Wenn Sie doppelte Anführungszeichen als Teil einer Zeichenfolge in einem Filter-Prädikat verwenden, erhalten Sie eine leere Ausgabe.

JMESPath-Funktionen

JMESPath verfügt auch über integrierte Funktionen, die komplexere Abfragen und das Ändern der Abfrageausgabe ermöglichen. Dieser Abschnitt konzentriert sich auf die Verwendung von JMESPath-Funktionen zum Erstellen von Abfragen, während der Abschnitt Manipulation der Ausgabe mit Funktionen veranschaulicht, wie Funktionen zum Ändern der Ausgabe verwendet werden.

Ausdrücke werden vor dem Aufrufen der Funktion ausgewertet, sodass Argumente selbst JMESPath-Ausdrücke sein können. Die folgenden Beispiele veranschaulichen dieses Konzept mithilfe von contains(string, substring), das überprüft, ob eine Zeichenfolge eine Teilzeichenfolge enthält. Dieser Befehl findet alle virtuellen Computer, die SSD-Speicher für ihren Betriebssystemdatenträger verwenden:

az vm list --resource-group QueryDemo --query "[?contains(storageProfile.osDisk.managedDisk.storageAccountType,'SSD')].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType}"

[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

Pipeausdrücke

Ähnlich wie | in der Befehlszeile verwendet wird, kann | in JMESPath-Abfragen genutzt werden, um Ausdrücke auf Zwischenabfrageergebnisse anzuwenden. Wir können auch verwenden | , um komplexe Abfragen in einfachere Unterausdrücke aufzuteilen. Wenn Sie die Abfrage aus dem vorherigen Abschnitt kürzen möchten, verwenden Sie | um den Filter nach dem Glätten und der Auswahl der Daten anzuwenden.

az vm list --resource-group QueryDemo --query "[].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType} | [? contains(Storage,'SSD')]"

[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

Sehen Sie die JMESPath-Spezifikation – Integrierte Funktionen für die vollständige Liste der Funktionen.

Bearbeiten der Ausgabe mit Funktionen

JMESPath-Funktionen haben auch einen anderen Zweck, der für die Ergebnisse einer Abfrage verwendet werden soll. Jede Funktion, die einen nichtbooleanen Wert zurückgibt, ändert das Ergebnis eines Ausdrucks. Sie können z. B. Daten nach einem Eigenschaftswert sortieren mit sort_by(array, &sort_expression). JMESPath verwendet einen speziellen Operator für Ausdrücke, &die später als Teil einer Funktion ausgewertet werden sollen. Das nächste Beispiel zeigt, wie Sie eine VM-Liste nach Betriebssystemdatenträgergröße sortieren:

az vm list --resource-group QueryDemo --query "sort_by([].{Name:name, Size:storageProfile.osDisk.diskSizeGb}, &Size)" --output table

Name     Size
-------  ------
Test-2   30
TestVM   32
WinTest  127

Sehen Sie in der JMESPath-Spezifikation - Integrierte Funktionen die vollständige Liste der Funktionen.

Formatieren von Abfrageergebnissen

Die Azure CLI verwendet JSON als Standardausgabeformat, unterschiedliche Ausgabeformate passen jedoch je nach Zweck und Ergebnissen möglicherweise besser zu einer Abfrage. Abfragen werden immer zuerst auf der JSON Ausgabe ausgeführt und dann formatiert.

In diesem Abschnitt werden die Formatierungen von tsv und table sowie einige Anwendungsfälle für jedes Format erläutert. Weitere Informationen zu Ausgabeformaten finden Sie unter Ausgabeformate für Azure CLI-Befehle.

TSV-Ausgabeformat

Das tsv-Ausgabeformat gibt durch Tabulator- und Zeilenumbruch getrennte Werte ohne zusätzliche Formatierungen, Schlüssel oder andere Symbole zurück. Dieses Format ist nützlich, wenn die Ausgabe in einem Parameter gespeichert und in einem anderen Befehl verwendet wird.

Ein Anwendungsfall für tsv die Formatierung ist Abfragen, die einen Wert aus einem CLI-Befehl abrufen, z. B. eine Azure-Ressourcen-ID oder einen Ressourcennamen, und den Wert in einer lokalen Umgebungsvariable speichern. Standardmäßig werden die Ergebnisse im JSON-Format zurückgegeben, was beim Umgang mit JSON-Zeichenfolgen, die in " Zeichen eingeschlossen sind, ein Problem sein kann. Die Anführungszeichen werden möglicherweise nicht von der Shell interpretiert, wenn die Befehlsausgabe direkt der Umgebungsvariablen zugewiesen ist. Dieses Problem wird im folgenden Beispiel erkannt, das einer Umgebungsvariablen ein Abfrageergebnis zuweist:

USER=$(az vm show --resource-group QueryDemo --name TestVM --query "osProfile.adminUsername")
echo $USER

"azureuser"

Verwenden Sie tsv formatierungen, wie in der folgenden Abfrage gezeigt, um zu verhindern, dass Rückgabewerte mit Typinformationen eingeschlossen werden:

USER=$(az vm show --resource-group QueryDemo --name TestVM --query "osProfile.adminUsername" --output tsv)
echo $USER

azureuser

Tabellenausgabeformat

Beim table-Format wird die Ausgabe als ASCII-Tabelle zurückgegeben, die einfach gelesen und überprüft werden kann. Nicht alle Felder sind in der Tabelle enthalten, sodass dieses Format am besten als durchsuchbare Übersicht über Daten verwendet wird. Felder, die nicht in der Tabelle enthalten sind, können weiterhin als Teil einer Abfrage gefiltert werden.

Hinweis

Bestimmte Schlüssel werden herausgefiltert und nicht in der Tabellenansicht gedruckt. Diese Schlüssel sind id, typeund etag. Um diese Werte anzuzeigen, können Sie den Schlüsselnamen in einem Multiselect-Hash ändern.

az vm show --resource-group QueryDemo --name TestVM --query "{objectID:id}" --output table

Wir können eine vorherige Abfrage verwenden, um dieses Konzept zu veranschaulichen. Die ursprüngliche Abfrage hat ein JSON-Objekt zurückgegeben, das den Namen, das Betriebssystem und den Administratornamen für jeden virtuellen Computer in der Ressourcengruppe enthält:

az vm list --resource-group QueryDemo --query "[].{Name:name, OS:storageProfile.osDisk.osType, admin:osProfile.adminUsername}"

[
  {
    "Name": "Test-2",
    "OS": "Linux",
    "admin": "sttramer"
  },
  {
    "Name": "TestVM",
    "OS": "Linux",
    "admin": "azureuser"
  },
  {
    "Name": "WinTest",
    "OS": "Windows",
    "admin": "winadmin"
  }
]

In Kombination mit dem --output table Ausgabeformat stimmen die Spaltennamen mit dem displayKey Wert des Multiselect-Hashs überein, wodurch die Informationen leichter überspringt werden:

az vm list --resource-group QueryDemo --query "[].{Name:name, OS:storageProfile.osDisk.osType, Admin:osProfile.adminUsername}" --output table

Name     OS       Admin
-------  -------  ---------
Test-2   Linux    sttramer
TestVM   Linux    azureuser
WinTest  Windows  winadmin

Nächste Schritte

Weitere Informationen zu JMESPath-Abfragen finden Sie im JMESPath-Lernprogramm.

Weitere Informationen zu anderen in diesem Artikel erwähnten Azure CLI-Konzepten finden Sie unter: