Запрос выходных данных команды Azure CLI с помощью запроса JMESPath

Интерфейс Azure CLI использует параметр --query для выполнения запроса JMESPath к результатам выполнения команд. JMESPath — это язык запросов для JSON, который позволяет выбирать и изменять выходные данные команд CLI.

Параметр --query поддерживается всеми командами в Azure CLI. В этой статье описывается, как использовать функции JMESPath, и приведены примеры запросов. Узнайте о понятиях JMESPath, которые полезны для отправки запросов, на вкладке "Основные понятия". См. примеры запросов JMESPath на вкладке "Примеры".

Azure CLI использует запросы для отбора и изменения выходных данных команд Azure CLI. Запросы выполняются на стороне клиента с возвращенным командой Azure CLI объектом JSON до какого-либа форматирования.

Escape-символы, используемые в запросах, отличаются для разных сред. Рекомендуется выполнять запросы в Azure CloudShell или командной строке, так как для этих оболочек требуется меньше escape-символов. Чтобы обеспечить корректность синтаксиса для примеров запросов, выберите вкладку для используемой оболочки.

Результаты команд CLI в виде словарей и списков

Даже если используется формат выходных данных, отличный от JSON, при выполнении запросов результаты выполнения команд сначала обрабатываются как объекты JSON. Результаты выполнения команд CLI представляют собой массив или словарь JSON. Массивы — это последовательности объектов, доступ к которым может осуществляться по индексу, а словари — это неупорядоченные объекты, доступ к которым осуществляется с помощью ключей.

Ниже приведен пример массива:

[ 
  1,
  2,
  3
]

Ниже приведен пример словаря:

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

Команды, которые могут возвращать несколько объектов, возвращают массив, а команды, которые всегда возвращают только один объект, возвращают его в виде словаря.

Получение свойств из словаря

При работе с результатами в виде словаря вы всегда можете получить свойства верхнего уровня с помощью ключа. Для доступа к свойствам вложенных словарей используется символ . (часть выражения). Прежде чем перейти к запросам, рассмотрим неизмененные выходные данные команды az vm show:

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

Результаты этой команда выводятся в виде словаря. Часть содержимого опущена.

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

Следующая команда предназначена для получения открытых ключей SSH, имеющих разрешение на подключение к виртуальной машине, с помощью запроса:

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

Обратите внимание, что строки запроса чувствительны к регистру. Например, после изменения "osProfile" на "OsProfile" в приведенном выше запросе будут возвращены неверные результаты.

Получение нескольких значений

Чтобы получить несколько свойств, заключите список выражений, разделенных запятыми, в квадратные скобки — [ ] (список из нескольких элементов). Следующая команда одновременно получает имя виртуальной машины, пользователя администратора и ключ SSH:

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

Эти значения включены в полученный массив в том порядке, в котором они были указаны в запросе. Поскольку результат имеет формат массива, значения не имеют соответствующих ключей. Чтобы получить словарь вместо массива, см. раздел ниже.

Переименование свойств в запросе

Чтобы при запросе нескольких значений получить словарь вместо массива, используйте оператор { } (хэш-таблица из нескольких элементов). Формат запроса для получения хэш-таблицы имеет вид {displayName:JMESPathExpression, ...}. displayName — это строка, отображаемая в выходных данных, а JMESPathExpression — вычисляемое выражение JMESPath. Изменим пример из предыдущего раздела, чтобы заменить список элементов хэш-таблицей:

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

Получение свойств из массива

Массив не имеет свойств как таковых, но доступ к нему может осуществляться по индексу. Эта возможность показана в предыдущем примере, когда выражение publicKeys[0] использовалось для получения элемента с индексом publicKeys из массива. Порядок выходных данных в командах CLI не гарантирован. Поэтому используйте индексы, только если вы уверены в порядке выходных данных или вам все равно, какой элемент вы получите. Чтобы получить доступ к элементам массива, используется одна из двух операций: преобразование в плоскую структуру или фильтрация. В этом разделе описано преобразование массива в плоскую структуру.

Преобразование массива в плоскую структуру выполняется с помощью оператора JMESPath []. Все выражения после оператора [] применяются к каждому элементу в текущем массиве. Если оператор [] стоит в начале запроса, он преобразовывает в плоскую структуру результат выполнения команды CLI. Эта возможность позволяет изучить результат выполнения команды az vm list. Следующий запрос получает имя, сведения об операционной системе и имя администратора для каждой виртуальной машины в группе ресурсов:

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

Преобразовать в плоскую структуру можно любой массив, а не только массив верхнего уровня, возвращаемый командой. В предыдущем разделе с помощью выражения osProfile.linuxConfiguration.ssh.publicKeys[0].keyData мы получили открытый ключ SSH, используемый для входа. Чтобы получить все открытые ключи SSH, выражение можно записать в следующем виде: osProfile.linuxConfiguration.ssh.publicKeys[].keyData. Этот запрос преобразовывает массив osProfile.linuxConfiguration.ssh.publicKeys в плоскую структуру, а затем применяет выражение keyData к каждому элементу:

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

Фильтрация массивов с логическими выражениями

Еще одной операцией, используемой для получения данных из массива, является фильтрация. Фильтрация выполняется с помощью оператора JMESPath [?...]. В этом операторе используется предикат. Предикат — это любое выражение (в том числе логическое), результат которого равен true или false. Выражения, предикат которых возвращает true, включаются в выходные данные.

В первом запросе показано, как получить список имен всех подписок Azure, подключенных к вашей учетной записи, свойство isDefault которых имеет значение true. Во втором и третьем запросах показаны два разных способа вывода всех подписок, свойство isDefault которых имеет значение false.

# 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 поддерживает стандартные операторы сравнения и логические операторы. Это операторы <, <=, >, >=, == и !=. JMESPath также поддерживает логические операторы "И" (&&), "ИЛИ" (||) и "НЕ" (!). Выражения можно объединять в группы с помощью круглых скобок. Это позволяет использовать более сложные выражения в качестве предикатов. Подробные сведения о предикатах и логических операциях см. в спецификации JMESPath.

В последнем примере вы преобразовали массив в плоскую структуру, чтобы получить список всех виртуальных машин в группе ресурсов. С помощью фильтров в эти выходные данные можно включить только виртуальные машины с ОС 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

Вы также можете отфильтровать числовые значения, например размер диска ОС. В следующем примере показано, как отфильтровать список виртуальных машин, чтобы отобразить виртуальные машины с размером диска, превышающим или равным 50 ГБ.

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

Если в массиве с множество элементов, возможно, применение фильтра перед выбором данных ускорит операцию.

Важно!

В JMESPath строки всегда заключаются в одиночные кавычки (') или escape-символы (`). Если в строке, стоящей в предикате фильтра, используются двойные кавычки, команда вернет пустой результат.

Функции JMESPath

JMESPath также имеет встроенные функции, позволяющие выполнять более сложные запросы и изменять выходные данные запроса. В этом разделе рассматривается использование функций JMESPath для создания запросов, а в разделе Работа с выходными данными с использованием функций показано, как использовать функции для изменения выходных данных.

Выражения вычисляются до вызова функции. Поэтому первым аргументом может быть выражение JMESPath. В следующих примерах это демонстрируется с использованием функции contains(string, substring), которая проверяет, содержит ли строка подстроку. Эта команда выполняет поиск всех виртуальных машин, использующих диски SSD для размещения ОС:

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

Выражения с вертикальной чертой

Аналогично тому, как | используется в командной строке, | можно использовать в запросах JMESPath для применения выражений к промежуточным результатам запроса. Мы также можем использовать | для разбиения сложных запросов на более простые части выражения. Чтобы сократить запрос из предыдущего раздела, используйте | для применения фильтра после преобразования данных в плоскую структуру и их отбора.

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

Полный список встроенных функций см. в этом разделе спецификации JMESPath.

Работа с выходными данными с использованием функций

Функции JMESPath также можно использовать для обработки результатов запроса. Любая функция, которая возвращает значение, отличное от логического, изменяет результаты выражения. Например, данные можно отсортировать по значению свойства с помощью функции sort_by(array, &sort_expression). В JMESPath используется специальный оператор & для выражений, которые должны вычисляться позднее в функции. В следующем примере показано, как отсортировать список виртуальных машин по размеру диска с ОС:

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

Полный список встроенных функций см. в этом разделе спецификации JMESPath.

Форматирование результатов запроса

Azure CLI использует JSON в качестве формата выходных данных по умолчанию, но другие форматы выходных данных могут лучше подходить для запроса в зависимости от его назначения и результатов. Обратите внимание, что запросы всегда сначала выполняются для выходных данных JSON, а затем форматируются.

В этом разделе описано форматирование tsv и table, а также приведены некоторые варианты использования для каждого формата. См. дополнительные сведения о других форматах выходных данных в разделе Форматы выходных данных для команд Azure CLI.

Формат выходных данных TSV

Формат выходных данных tsv возвращает значения, разделенные табуляцией и символом новой строки без дополнительного форматирования, ключей и других символов. Это полезно, если выходные данные используются другой командой.

Одним из вариантов использования для форматирования tsv являются запросы, которые извлекают значение из команды CLI, например идентификатор ресурса Azure или имя ресурса, и сохраняют значение в локальной переменной среды. По умолчанию результаты возвращаются в формате JSON. Это может быть проблемой при работе со строками JSON, которые заключены в ". Кавычки могут не интерпретироваться оболочкой, если выходные данные команды назначаются переменной среды напрямую. Это можно увидеть в следующем примере, который назначает результат запроса переменной среды:

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

Чтобы не допустить включение возвращаемых значений в сведения о типе, используйте форматирование tsv, как показано в следующем запросе:

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

Формат табличных выходных данных

Формат table выводит данные в виде таблицы ASCII, упрощая чтение и сканирование данных. Некоторые поля не включаются в таблицу, поэтому этот формат лучше всего подходит, когда вам нужно получить представление данных в наглядной форме. Поля, которые не включаются в таблицу, все равно могут фильтроваться как часть запроса.

Примечание

Некоторые ключи отфильтровываются и не печатаются в табличном представлении. Эти ключи — id, type и etag. Чтобы отобразить эти значения, можно изменить имя ключа в хэш-таблице.

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

Для демонстрации этого можно использовать предыдущий запрос. Исходный запрос вернул объект JSON, содержащий имя, ОС и имя администратора для каждой виртуальной машины в группе ресурсов:

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

При использовании формата выходных данных --output table имена столбцов соответствуют значению displayKey в хэш-таблице, что упрощает просмотр сведений:

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

Дальнейшие действия

Дополнительные сведения о запросах JMESPath см. в учебнике по JMESPath.

Дополнительные сведения о других понятиях Azure CLI, упомянутых в этой статье, см. в следующих статьях: