Azure CLI コマンドの出力のクエリQuery Azure CLI command output

Azure CLI では、--query 引数を使用して、コマンドの結果に対して JMESPath クエリを実行します。The Azure CLI uses the --query argument to execute a JMESPath query on the results of commands. JMESPath は、CLI の出力からデータを選択して変更できるようにする、JSON 用のクエリ言語です。JMESPath is a query language for JSON, giving you the ability to select and modify data from CLI output. クエリは、表示書式設定の前に JSON 出力に対して実行されます。Queries are executed on the JSON output before any display formatting.

--query 引数は、Azure CLI のすべてのコマンドでサポートされています。The --query argument is supported by all commands in the Azure CLI. この記事では、一連の簡単な例を使って、JMESPath の機能の使用方法を説明します。This article covers how to use the features of JMESPath with a series of small, simple examples.

CLI の結果である辞書とリストDictionary and list CLI results

JSON 以外の出力形式を使用している場合でも、CLI コマンドの結果は、クエリのためにまず JSON として扱われます。Even when using an output format other than JSON, CLI command results are first treated as JSON for queries. CLI の結果は、JSON 配列または JSON 辞書です。CLI results are either a JSON array or dictionary. 配列はインデックスを作成できるオブジェクトのシーケンスであり、辞書はキーを使用してアクセスされる順序指定されていないオブジェクトです。Arrays are sequences of objects that can be indexed, and dictionaries are unordered objects accessed with keys. 複数のオブジェクトを返すことが "できる" コマンドは配列を返し、"常に" 単一オブジェクト "のみ" を返すコマンドは辞書を返します。Commands that could return more than one object return an array, and commands that always return only a single object return a dictionary.

辞書のプロパティを取得するGet properties in a dictionary

結果として辞書を使用すると、キーだけで最上位からプロパティにアクセスできます。Working with dictionary results, you can access properties from the top level with just the key. . (部分式) 文字は、入れ子になった辞書のプロパティにアクセスする際に使用します。The . (subexpression) character is used to access properties of nested dictionaries. クエリを導入する前に、az vm show コマンドの未変更の出力を見てみましょう。Before introducing queries, take a look at the unmodified output of the az vm show command:

az vm show -g QueryDemo -n TestVM -o json

このコマンドは辞書を出力します。The command will output a dictionary. 一部の内容は省略されています。Some content has been omitted.

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

次のコマンドでは、クエリを追加して、VM への接続を許可された SSH 公開キーを取得します。The following command gets the SSH public keys authorized to connect to the VM by adding a query:

az vm show -g QueryDemo -n TestVM --query osProfile.linuxConfiguration.ssh.publicKeys -o json
[
  {
    "keyData": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso",
    "path": "/home/azureuser/.ssh/authorized_keys"
  }
]

複数のプロパティを取得するには、式をコンマ区切りリストとして角かっこ [ ] (複数選択リスト) で囲みます。To get more than one property, put expressions in square brackets [ ] (a multiselect list) as a comma-separated list. VM 名、管理者ユーザー、SSH キーのすべてを一度に取得するには、次のコマンドを使用します。To get the VM name, admin user, and SSH key all at once use the command:

az vm show -g QueryDemo -n TestVM --query '[name, osProfile.adminUsername, osProfile.linuxConfiguration.ssh.publicKeys[0].keyData]' -o json
[
  "TestVM",
  "azureuser",
  "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso"
]

これらの値は、クエリで指定された順序で結果の配列に表示されます。These values are listed in the result array in the order they were given in the query. 結果は配列であるため、結果に関連付けられたキーはありません。Since the result is an array, there are no keys associated with the results.

単一の値を取得するGet a single value

一般的なケースとして、Azure リソース ID、リソース名、ユーザー名、パスワードなどの CLI コマンドから "1 つ" の値のみを取得する必要があります。A common case is that you need to only get one value out of a CLI command, such as an Azure resource ID, a resource name, a username, or a password. その場合、ローカルの環境変数に値を格納する必要が発生することも少なくありません。In that case, you also often want to store the value in a local environment variable. 1 つのプロパティを取得するには、まず、クエリから 1 つのプロパティのみを取得していることを確認します。To get a single property, first make sure that you're only getting one property out of the query. 最後の例を管理者ユーザー名のみを取得するように変更します。Modifying the last example to get only the admin username:

az vm show -g QueryDemo -n TestVM --query 'osProfile.adminUsername' -o json
"azureuser"

これは有効な単一の値のように見えますが、" 文字が出力の一部として返されることに注意してください。This looks like a valid single value, but note that the " characters are returned as part of the output. これは、オブジェクトが JSON 文字列であることを示します。This indicates that the object is a JSON string. この値をコマンドからの出力として環境変数に直接割り当てた場合、引用符はシェルによって解釈 "されない" ことに注意してください。It's important to note that when you assign this value directly as output from the command to an environment variable, the quotes may not be interpreted by the shell:

USER=$(az vm show -g QueryDemo -n TestVM --query 'osProfile.adminUsername' -o json)
echo $USER
"azureuser"

これは、ほぼ間違いなく望ましくない状態です。This is almost certainly not what you want. この場合、戻り値を型情報で囲まない出力形式を使用できます。In this case, you want to use an output format which doesn't enclose returned values with type information. この目的のため CLI が提供する最適な出力オプションは tsv (タブ区切りの値) です。The best output option that the CLI offers for this purpose is tsv, tab-separated values. 特に、単一値のみの値を取得するとき (ディクショナリまたは一覧ではなく)、tsv 出力が引用されることはなくなります。In particular, when retrieving a value that's only a single value (not a dictionary or list), tsv output is guaranteed to be unquoted.

az vm show -g QueryDemo -n TestVM --query 'osProfile.adminUsername' -o tsv
azureuser

tsv 出力形式について詳しくは、「Output formats - TSV output format (出力形式 - TSV 出力形式)」を参照してください。For more information about the tsv output format, see Output formats - TSV output format

クエリでプロパティの名前を変更するRename properties in a query

複数の値のクエリを実行するときに、配列ではなく、辞書を取得するには、{ } (複数選択ハッシュ) 演算子を使用します。To get a dictionary instead of an array when querying for multiple values, use the { } (multiselect hash) operator. 複数選択ハッシュの形式は、{displayName:JMESPathExpression, ...} です。The format for a multiselect hash is {displayName:JMESPathExpression, ...}. displayName は出力に表示される文字列であり、JMESPathExpression は評価する JMESPath 式です。displayName will be the string shown in output, and JMESPathExpression is the JMESPath expression to evaluate. 複数選択リストをハッシュに変更して、前のセクションの例を変更します。Modifying the example from the last section by changing the multiselect list to a hash:

az vm show -g QueryDemo -n TestVM --query '{VMName:name, admin:osProfile.adminUsername, sshKey:osProfile.linuxConfiguration.ssh.publicKeys[0].keyData }' -o json
{
  "VMName": "TestVM",
  "admin": "azureuser",
  "ssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso"
}

配列内のプロパティを取得するGet properties in an array

配列には独自のプロパティはありませんが、インデックスを作成できます。An array has no properties of its own, but it can be indexed. この機能は、前の例の式 publicKeys[0] で示されています。これは、publicKeys 配列の最初の要素を取得します。This feature is shown in the last example with the expression publicKeys[0], which gets the first element of the publicKeys array. CLI の出力が順序付けられているという保証はないため、順序が確かである場合や取得する要素を気にかけない場合を除き、インデックスを使用しないようにしてください。There's no guarantee CLI output is ordered, so avoid using indexing unless you're sure of the order or don't care what element you get. 配列内の要素のプロパティにアクセスするには、"フラット化" と "フィルター処理" の 2 つの操作のいずれかを実行します。To access the properties of elements in an array, you do one of two operations: flattening and filtering. このセクションでは、配列をフラット化する方法について説明します。This section covers how to flatten an array.

配列のフラット化は、[] JMESPath 演算子を使用して実行します。Flattening an array is done with the [] JMESPath operator. [] 演算子の後のすべての式が、現在の配列内の各要素に適用されます。All expressions after the [] operator are applied to each element in the current array. [] がクエリの先頭にある場合、CLI コマンドの結果がフラット化されます。If [] appears at the start of the query, it flattens the CLI command result. この機能を使用して、az vm list の結果を検査できます。The results of az vm list can be inspected with this feature. リソース グループ内の各 VM の名前、OS、管理者名を取得するには、次のコマンドを使用します。To get the name, OS, and administrator name for each VM in a resource group:

az vm list -g QueryDemo --query '[].{Name:name, OS:storageProfile.osDisk.osType, admin:osProfile.adminUsername}' -o json
[
  {
    "Name": "Test-2",
    "OS": "Linux",
    "admin": "sttramer"
  },
  {
    "Name": "TestVM",
    "OS": "Linux",
    "admin": "azureuser"
  },
  {
    "Name": "WinTest",
    "OS": "Windows",
    "admin": "winadmin"
  }
]

--output table 出力形式と組み合わせた場合、列名は複数選択ハッシュの displayKey 値と一致します。When combined with the --output table output format, the column names match up with the displayKey value of the multiselect hash:

az vm list -g 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

注意

特定のキーはフィルター処理され、テーブル ビューには出力されません。Certain keys are filtered out and not printed in the table view. これらのキーは、idtype、およびetag です。These keys are id, type, and etag. これらの値を表示するには、複数選択ハッシュのキー名を変更します。To see these values, you can change the key name in a multiselect hash.

az vm show -g QueryDemo -n TestVM --query "{objectID:id}" -o table

コマンドから返される最上位の結果だけでなく、配列もフラット化できます。Any array can be flattened, not just the top-level result returned by the command. 前のセクションでは、式 osProfile.linuxConfiguration.ssh.publicKeys[0].keyData を使用して、サインイン用の SSH 公開キーを取得しました。In the last section, the expression osProfile.linuxConfiguration.ssh.publicKeys[0].keyData was used to get the SSH public key for sign-in. "すべての" SSH 公開キーを取得するには、この式を osProfile.linuxConfiguration.ssh.publicKeys[].keyData と記述します。To get every SSH public key, the expression could instead be written as osProfile.linuxConfiguration.ssh.publicKeys[].keyData. このクエリ式では、osProfile.linuxConfiguration.ssh.publicKeys 配列をフラット化し、各要素に対して keyData 式を実行します。This query expression flattens the osProfile.linuxConfiguration.ssh.publicKeys array, and then runs the keyData expression on each element:

az vm show -g QueryDemo -n TestVM --query '{VMName:name, admin:osProfile.adminUsername, sshKeys:osProfile.linuxConfiguration.ssh.publicKeys[].keyData }' -o json
{
  "VMName": "TestVM",
  "admin": "azureuser",
  "sshKeys": [
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDMobZNJTqgjWn/IB5xlilvE4Y+BMYpqkDnGRUcA0g9BYPgrGSQquCES37v2e3JmpfDPHFsaR+CPKlVr2GoVJMMHeRcMJhj50ZWq0hAnkJBhlZVWy8S7dwdGAqPyPmWM2iJDCVMVrLITAJCno47O4Ees7RCH6ku7kU86b1NOanvrNwqTHr14wtnLhgZ0gQ5GV1oLWvMEVg1YFMIgPRkTsSQKWCG5lLqQ45aU/4NMJoUxGyJTL9i8YxMavaB1Z2npfTQDQo9+womZ7SXzHaIWC858gWNl9e5UFyHDnTEDc14hKkf1CqnGJVcCJkmSfmrrHk/CkmF0ZT3whTHO1DhJTtV stramer@contoso\n"
  ]
}

配列をフィルター処理するFilter arrays

配列からデータを取得するときに使用するもう 1 つの操作は "フィルター処理" です。The other operation used to get data from an array is filtering. フィルター処理は、[?...] JMESPath 演算子を使用して実行します。Filtering is done with the [?...] JMESPath operator. この演算子は、その内容として述語を受け取ります。This operator takes a predicate as its contents. 述語とは、true または false に評価できるステートメントです。A predicate is any statement that can be evaluated to either true or false. 述語が true に評価された式が出力に含まれます。Expressions where the predicate evaluates to true are included in the output.

JMESPath では、標準の比較演算子と論理演算子が提供されています。JMESPath offers the standard comparison and logical operators. これらには、<<=>>===!= が含まれます。These include <, <=, >, >=, ==, and !=. JMESPath では、論理 AND (&&)、論理 OR (||)、論理 NOT (!) もサポートされています。JMESPath also supports logical and (&&), or (||), and not (!). 式をかっこ内にグループ化できるので、より複雑な述語式を使用できます。Expressions can be grouped within parenthesis, allowing for more complex predicate expressions. 述語と論理演算の詳細については、JMESPath の仕様をご覧ください。For the full details on predicates and logical operations, see the JMESPath specification.

前のセクションでは、配列をフラット化して、リソース グループ内のすべての VM の完全なリストを取得しました。In the last section, we flattened an array to get the complete list of all VMs in a resource group. フィルターを使用すると、この出力を Linux VM だけに制限できます。Using filters, this output can be restricted to only Linux VMs:

az vm list -g QueryDemo --query "[?storageProfile.osDisk.osType=='Linux'].{Name:name,  admin:osProfile.adminUsername}" --output table
Name    Admin
------  ---------
Test-2  sttramer
TestVM  azureuser

重要

JMESPath では、文字列は常に単一引用符 (') で囲みます。In JMESPath, strings are always surrounded by single quotes ('). フィルター述語の文字列の一部として二重引用符を使用すると、空の出力が返されます。If you use double quotes as part of a string in a filter predicate, you'll get empty output.

JMESPath には、フィルター処理に役立つ組み込み関数もあります。JMESPath also has built-in functions that can help with filtering. このような関数の 1 つである contains(string, substring) は、文字列に部分文字列が含まれているかどうかを調べます。One such function is contains(string, substring), which checks to see if a string contains a substring. この関数を呼び出す前に式が評価されるので、最初の引数には完全な JMESPath 式を指定できます。Expressions are evaluated before calling the function, so the first argument can be a full JMESPath expression. 次の例では、OS ディスクに SSD ストレージを使用するすべての VM を検出します。The next example finds all VMs using SSD storage for their OS disk:

az vm list -g QueryDemo --query "[?contains(storageProfile.osDisk.managedDisk.storageAccountType,'SSD')].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType}" -o json
[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

このクエリは少し長くなっています。This query is a little long. storageProfile.osDisk.managedDisk.storageAccountType キーが 2 回記述され、出力でキー更新されています。The storageProfile.osDisk.managedDisk.storageAccountType key is mentioned twice, and rekeyed in the output. これを短くする 1 つの方法として、データをフラット化して選択した後にフィルターを適用します。One way to shorten it is to apply the filter after flattening and selecting data.

az vm list -g QueryDemo --query "[].{Name:name, Storage:storageProfile.osDisk.managedDisk.storageAccountType}[?contains(Storage,'SSD')]" -o json
[
  {
    "Name": "TestVM",
    "Storage": "StandardSSD_LRS"
  },
  {
    "Name": "WinTest",
    "Storage": "StandardSSD_LRS"
  }
]

大きな配列では、データを選択する前にフィルターを適用する方が速い場合があります。For large arrays, it may be faster to apply the filter before selecting data.

関数の全一覧については、JMESPath の仕様の組み込み関数に関するセクションをご覧ください。See the JMESPath specification - Built-in Functions for the full list of functions.

出力を変更するChange output

JMESPath の関数には別の目的もあります。それは、クエリの結果を操作することです。JMESPath functions also have another purpose, which is to operate on the results of a query. ブール値以外の値を返す関数では、式の結果が変更されます。Any function that returns a non-boolean value changes the result of an expression. たとえば、sort_by(array, &sort_expression) を使用して、データをプロパティ値で並べ替えることができます。For example, you can sort data by a property value with sort_by(array, &sort_expression). JMESPath では、関数の一部として後で評価する必要がある式に、特殊演算子の & を使用します。JMESPath uses a special operator, &, for expressions that should be evaluated later as part of a function. 次の例は、VM のリストを OS ディスク サイズで並べ替える方法を示しています。The next example shows how to sort a VM list by OS disk size:

az vm list -g QueryDemo --query "sort_by([].{Name:name, Size:storageProfile.osDisk.diskSizeGb}, &Size)" --output table
Name     Size
-------  ------
TestVM   30
Test-2   32
WinTest  127

関数の全一覧については、JMESPath の仕様の組み込み関数に関するセクションをご覧ください。See the JMESPath specification - Built-in Functions for the full list of functions.

対話形式でのクエリの実験Experiment with queries interactively

JMESPath で実験を開始できるように、JMESPath-terminal Python パッケージには、クエリを操作するための対話型環境が用意されています。To start experimenting with JMESPath, the JMESPath-terminal Python package offers an interactive environment to work with queries. データを入力としてパイプ処理してから、クエリを記述し、エディターで実行します。Data is piped as input, and then queries are written and run in the editor.

pip install jmespath-terminal
az vm list --output json | jpterm