Cara mengkueri output perintah Azure CLI menggunakan kueri JMESPath

Azure CLI menggunakan parameter --query untuk menjalankan kueri JMESPath pada hasil perintah. JMESPath adalah bahasa kueri untuk JSON, memberi Anda kemampuan untuk memilih dan mengubah data dari output CLI.

Semua perintah di Azure CLI mendukung --query parameter . Artikel ini membahas cara menggunakan fitur JMESPath dan memberikan contoh kueri. Pelajari tentang konsep JMESPath yang berguna untuk mengkueri bagian tab konsep. Lihat contoh kueri JMESPath di tab contoh.

Azure CLI menggunakan kueri untuk memilih dan memodifikasi output perintah Azure CLI. Kueri adalah sisi klien yang dijalankan pada objek JSON yang ditampilkan perintah Azure CLI sebelum pemformatan tampilan apa pun.

Karakter escape yang diperlukan dalam kueri berbeda untuk tiap-tiap lingkungan. Disarankan untuk menjalankan kueri di Azure Cloud Shell atau cmd karena shell ini memerlukan lebih sedikit karakter escape. Untuk memastikan contoh kueri benar secara sintis, pilih tab untuk shell yang Anda gunakan.

Kamus dan daftar hasil CLI

Hasil perintah CLI pertama kali diperlakukan sebagai JSON untuk kueri, bahkan ketika format output adalah sesuatu selain JSON. Hasil CLI adalah array atau kamus JSON. Array adalah urutan objek yang dapat diindeks, dan kamus adalah objek tidak berurutan yang diakses dengan kunci.

Ini adalah contoh array:

[ 
  1,
  2,
  3
]

Ini adalah contoh kamus:

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

Perintah yang dapat mengembalikan lebih dari satu objek akan mengembalikan array, dan perintah yang selalu mengembalikan hanya satu objek akan mengembalikan kamus.

Mendapatkan properti dalam kamus

Menggunakan hasil kamus, Anda dapat mengakses properti dari tingkat atas hanya dengan kunci. Karakter . (subekspresi) digunakan untuk mengakses properti kamus berlapis. Sebelum memperkenalkan kueri, lihat output yang tidak dimodifikasi dari perintah az vm show:

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

Perintah mengeluarkan kamus. Beberapa konten telah dihilangkan.

{
  "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
  },
  ....
}

Perintah berikut membuat kunci umum SSH diotorisasi untuk terhubung ke VM dengan menambahkan kueri:

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

String kueri peka huruf besar/kecil. Misalnya, mengubah 'osProfile' menjadi 'OsProfile' di kueri sebelumnya tidak mengembalikan hasil yang benar.

Mendapatkan beberapa nilai

Untuk mendapatkan lebih dari satu properti, letakkan ekspresi yang dipisahkan koma dalam tanda kurung siku [ ] (daftar banyak pilihan). Perintah berikut menhasilkan nama VM, pengguna admin, dan kunci SSH sekaligus:

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

Nilai-nilai ini tercantum dalam array hasil dalam urutan yang diberikan dalam kueri. Karena hasilnya adalah array, tidak ada kunci yang terkait dengan hasil. Untuk mendapatkan kamus alih-alih array, lihat bagian berikutnya.

Mengganti nama properti dalam kueri

Untuk mendapatkan kamus, bukan array saat kueri untuk beberapa nilai, gunakan { } operator (hash multiselect). Format untuk hash multiselect adalah {displayName:JMESPathExpression, ...}. displayName adalah string yang ditampilkan dalam output, dan JMESPathExpression merupakan ekspresi JMESPath untuk dievaluasi. Ubah contoh dari bagian terakhir dengan mengubah daftar multipilih menjadi hash:

Catatan

Jika Anda memilih untuk menggunakan spasi dalam nama kolom baru, seperti VM name alih-alih VMName, aturan kutipan berubah di Bash dan PowerShell. Lihat Meneruskan spasi di parameter Azure CLI misalnya.

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

Mendapatkan properti dalam array

Array tidak memiliki properti sendiri, tetapi dapat diindeks. Fitur ini ditampilkan dalam contoh terakhir dengan ekspresi publicKeys[0], yang mendapatkan elemen pertama dari array publicKeys. Tidak ada jaminan output CLI diurutkan, jadi hindari menggunakan pengindeksan kecuali Anda yakin dengan urutannya atau tidak peduli elemen apa yang Anda dapatkan. Untuk mengakses properti elemen dalam array, Anda dapat menjalankan salah satu dari dua operasi: perataan atau pemfilteran. Bagian ini membahas cara meratakan array.

Meratakan array dilakukan dengan operator [] JMESPath. Semua ekspresi setelah operator [] diterapkan ke setiap elemen dalam array saat ini. Jika muncul di awal kueri, [] akan meratakan hasil perintah CLI. Hasil az vm list dapat diperiksa dengan fitur ini. Untuk mendapatkan nama, OS, dan nama administrator pada setiap mesin virtual dalam grup sumber daya:

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

Array apa pun dapat diratakan, bukan hanya hasil tingkat atas yang dikembalikan oleh perintah. Di bagian terakhir, ekspresi osProfile.linuxConfiguration.ssh.publicKeys[0].keyData digunakan untuk mendapatkan kunci umum SSH untuk masuk. Untuk mendapatkan setiap kunci umum SSH, ekspresi dapat ditulis sebagai osProfile.linuxConfiguration.ssh.publicKeys[].keyData. Ekspresi kueri ini meratakan array osProfile.linuxConfiguration.ssh.publicKeys, lalu menjalankan ekspresi keyData pada setiap elemen:

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

Memfilter array dengan ekspresi boolean

Operasi lain yang digunakan untuk mendapatkan data dari array adalah pemfilteran. Pemfilteran dilakukan dengan operator [?...] JMESPath. Operator ini mengambil predikat sebagai isinya. Predikat adalah pernyataan apa pun (termasuk properti Boolean) yang dapat dievaluasi ke true atau false. Ekspresi di mana predikat mengevaluasi ke true disertakan dalam output.

Kueri pertama menunjukkan cara mencantumkan nama semua langganan Azure yang tersambung ke akun Anda yang propertinya isDefault benar. Kueri kedua dan ketiga menunjukkan dua cara berbeda untuk mencantumkan semua langganan yang properti isDefault-nya salah.

# 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 menawarkan perbandingan standar dan operator logika. Ini termasuk <, <=, >, >=, ==, dan !=. JMESPath juga mendukung logika dan (&&), atau (||), dan bukan (!). Ekspresi dapat dikelompokkan dalam tanda kurung, sehingga memungkinkan ekspresi predikat yang lebih kompleks. Untuk detail lengkap tentang predikat dan operasi logika, lihat spesifikasi JMESPath.

Di bagian terakhir, Anda meratakan array untuk mendapatkan daftar lengkap semua mesin virtual dalam grup sumber daya. Dengan penggunaan filter, output ini hanya dapat dibatasi untuk VM Linux:

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

Anda juga dapat memfilter nilai numerik seperti ukuran disk OS. Contoh berikut menunjukkan cara memfilter daftar VM untuk menampilkan VM dengan ukuran disk yang lebih besar dari atau sama dengan 50 GB.

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

Untuk array besar, mungkin lebih cepat menerapkan filter sebelum memilih data.

Penting

Di JMESPath, string selalu dikelilingi oleh tanda kutip tunggal (') atau karakter escape (`). Jika Anda menggunakan tanda kutip ganda sebagai bagian dari string dalam predikat filter, Anda akan mendapatkan output kosong.

Fungsi JMESPath

JMESPath juga memiliki fungsi bawaan yang memungkinkan kueri yang lebih kompleks dan untuk memodifikasi output kueri. Bagian ini berfokus pada penggunaan fungsi JMESPath untuk membuat kueri sementara bagian Memanipulasi output dengan fungsi memperlihatkan cara menggunakan fungsi untuk memodifikasi output.

Ekspresi dievaluasi sebelum memanggil fungsi, sehingga argumen pertama bisa berupa ekspresi JMESPath. Contoh berikut menunjukkan konsep ini dengan menggunakan contains(string, substring), yang memeriksa untuk melihat apakah string berisi substring. Contoh berikutnya menampilkan semua mesin virtual yang menggunakan penyimpanan SSD untuk disk OS-nya:

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

Ekspresi pipa

Mirip dengan cara | digunakan di baris perintah, | dapat digunakan dalam kueri JMESPath untuk menerapkan ekspresi ke hasil kueri menengah. Kita juga dapat menggunakan | untuk memecah kueri yang kompleks menjadi subekspresi yang lebih sederhana. Untuk mempersingkat kueri dari bagian sebelumnya, gunakan | untuk menerapkan filter setelah meratakan dan memilih data.

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

Lihat Spesifikasi JMESPath - Fungsi Bawaan untuk daftar lengkap fungsi.

Memanipulasi output dengan fungsi

Fungsi JMESPath juga memiliki tujuan lain, yaitu untuk beroperasi pada hasil kueri. Fungsi apa pun yang mengembalikan nilai nonboolean mengubah hasil ekspresi. Misalnya, Anda dapat mengurutkan data menurut nilai properti dengan sort_by(array, &sort_expression). JMESPath menggunakan operator khusus, &, untuk ekspresi yang harus dievaluasi nanti sebagai bagian dari suatu fungsi. Contoh berikutnya menunjukkan cara mengurutkan daftar VM berdasarkan ukuran disk OS:

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

Lihat Spesifikasi JMESPath - Fungsi Bawaan untuk daftar lengkap fungsi.

Memformat hasil kueri

Azure CLI menggunakan JSON sebagai format output default-nya, tetapi format output yang berbeda mungkin lebih cocok dengan kueri bergantung pada tujuan dan hasilnya. Kueri selalu dijalankan pada output terlebih dahulu lalu diformat JSON .

Bagian ini akan membahas pemformatan tsv dan table serta beberapa kasus penggunaan untuk setiap format. Untuk informasi selengkapnya, lihat Format output untuk perintah Azure CLI.

Format output TSV

tsv Format output mengembalikan nilai yang dipisahkan tab dan baris baru tanpa pemformatan tambahan, kunci, atau simbol lainnya. Format ini berguna ketika output disimpan dalam parameter dan digunakan dalam perintah lain.

Satu kasus penggunaan untuk pemformatan tsv adalah kueri yang mengambil nilai dari perintah CLI, seperti ID sumber daya Azure atau nama sumber daya, dan menyimpan nilai dalam variabel lingkungan lokal. Secara default, hasilnya dikembalikan dalam format JSON, yang mungkin menjadi masalah saat berhadapan dengan string JSON yang diapit " karakter. Tanda kutip mungkin tidak ditafsirkan oleh shell jika output perintah langsung ditetapkan ke variabel lingkungan. Masalah ini terlihat dalam contoh berikut yang menetapkan hasil kueri ke variabel lingkungan:

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

Gunakan tsv pemformatan, seperti yang ditunjukkan dalam kueri berikut, untuk mencegah menyertakan nilai pengembalian dengan informasi jenis:

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

Format output tabel

Format table mencetak output sebagai tabel ASCII, sehingga mudah dibaca dan dipindai. Tidak semua bidang tidak disertakan dalam tabel, jadi format ini paling baik digunakan sebagai ringkasan data yang dapat dicari manusia. Bidang yang tidak disertakan dalam tabel masih bisa difilter sebagai bagian dari kueri.

Catatan

Kunci tertentu difilter dan tidak dicetak dalam tampilan tabel. Kunci tersebut adalah id, type, dan etag. Untuk melihat nilai ini, Anda dapat mengubah nama kunci dalam hash multiselect.

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

Kita dapat menggunakan kueri sebelumnya untuk menunjukkan konsep ini. Kueri asli menampilkan objek JSON yang berisi nama, OS, dan nama administrator untuk setiap mesin virtual dalam grup sumber daya:

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

Saat digabungkan dengan format output --output table, nama kolom akan cocok dengan nilai displayKey dari hash banyak pilihan sehingga memudahkannya untuk membaca informasi:

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

Langkah berikutnya

Untuk mempelajari selengkapnya tentang kueri JMESPath, lihat Tutorial JMESPath.

Untuk mempelajari selengkapnya tentang konsep Azure CLI lain yang disebutkan dalam artikel ini lihat: