JMESPath チュートリアル

渡辺です。 AWSCLIのqueryオプションで利用できるJMESPathですが、導入部分の敷居は低いのですが、使いこなそうとするとなかなか難解な仕様な気がします。 そこで、複雑なqueryも書けるように、チュートリアルを紹介します。

JMESPathとは

JMESPathはJSONのクエリ言語です。 ひらたく言えば、JMESPathを利用することで、JSONを対象としてフィルターや抽出を行い結果を取得できます。 jqが近いツールですが、jqはコマンド（ツール）であり、JMESPathはクエリ言語という点が相違点です。

JMESPathは、AWS CLI (v1.2以降）で利用できるため、結果となるJSONオブジェクトを加工するのに便利です（AWS CLIのフィルターとクエリーの使い方についてまとめてみた）。

基本書式

最もシンプルな書式は identifier（識別子）です。 JSONオブジェクトのキーを指定することで、値を抽出します。

{"a": "foo", "b": "bar", "c": "baz"}

JMESPath	Result
a	"foo"
b	"bar"

ネストしたオブジェクトの値を抽出するには、identifierを.（ピリオド）で連結します。

{
  "a":  {
    "b": {
      "c": {
        "d": "value"
      }
    }
  }
}

JMESPath	Result
a.b.c.d	"value"
a.b.c	{ "d": "value" }

配列の要素を抽出するには、要素のインデックスを指定します。

["a", "b", "c", "d", "e", "f"]

JMESPath	Result
[1]	"b"
[2]	"c"
[-1]	"f"
[]	["a", "b", "c", "d", "e", "f"]

末尾からのインデックスは、-1といった負数を指定することで抽出可能です。 要素を指定しない場合は、配列全体を抽出します。

identifierとインデックスを組み合わせての抽出ができます。

{
  "a": [
    { "b": "value1" },
    { "b": "value2" },
    { "b": "value3" }
  ]
}

JMESPath	Result
a[0].b	"value1"

スライス

:（コロン）を利用することで、配列の一部を抽出することができます。

["a", "b", "c", "d", "e", "f"]

JMESPath	Result
[0:2]	["a", "b"]
[1:4]	["b", "c", "d"]

コロンの後ろで指定したインデックスの要素は含みません。

コロンの前を省略すれば指定したインデックスの前の要素までの配列を、 コロンの後ろを省略すれば指定したインデックスまでの配列を、それぞれ取得できます。

JMESPath	Result
[3:]	["d", "e", "f"]
[:3]	["a", "b", "c"]

偶数インデックスの要素のみを抽出したい場合などには、コロンを追加し増分を指定してのスライスが可能です。

JMESPath	Result
[::2]	["a", "c", "e"]
[1::2]	["b", "d", "f"]
[::3]	["a", "d"]
[::-1]	["f", "e", "d", "c", "b", "a"]

負数を指定すれば逆順になります。

ec2 describe-instances でのサンプル

ここまでの内容を利用すれば、awscliの結果から値を抽出することは簡単にできるでしょう。 例えば、ec2 describe-instancesの結果（一部）はこんな構造です。

{
    "Reservations": [
        {
            "Instances": [
                {
                    "InstanceId": "i-xxxxxxfc"
                }
            ]
        },
        {
            "Instances": [
                {
                    "InstanceId": "i-xxxxxxfd"
                }
            ]
        }
    ]
}

JMESPath	Result
Reservations[].Instances[0].InstanceId	["i-xxxxxxfc", "i-xxxxxxfd"]
Reservations[0].Instances[0].InstanceId	"i-xxxxxxfc"
Reservations[1].Instances[0].InstanceId	"i-xxxxxxfd"

awscliで利用する場合はこのようなイメージです。

aws ec2 describe-instances \
  --query Reservations[].Instances[].InstanceId

実践してみよう

awscliを利用して、以下の情報を取得してください。

• EC2インスタンスのEIP一覧
• EC2インスタンスのインスタンスID一覧
• セキュリティグループ名の一覧

まとめ

JMESPathの基本として、identifierとインデックスについて学ぶことができました。 ここまでは直感的で簡単に使えるかと思いますが、ある意味で一番実践的だと思います。