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

  • Статья

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

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

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

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

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

Результаты команды 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 для вычисления. Измените пример из последнего раздела, изменив список с несколькими выборками на хэш:

Примечание.

Если вы решили использовать пробел в новом имени столбца, например вместо VMNameэтого, правила кворирования изменяются как в Bash, так VM name и в PowerShell. Примеры см . в параметрах Azure CLI .

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, упомянутых в этой статье, см. в следующих статьях: