AWS CLIの”–query”と”–filter”オプションの使い方を理解してみた

最近RDSインスタンスのDBエンジンごとに台数をカウントするシェルスクリプトを作成したのですが、"--query"と"--filter"オプションの使い方がいまいち理解できていなかったのでブログに残します。

"--query"と"--filter"オプションの違い

"--query"オプション

"--query"は必要な項目を取得するために使用するオプションです。
例えばdescribe-db-instancesの出力でDBInstanceIdentifierという項目のみ取得したい場合は以下のようになります。

aws rds describe-db-instances --query DBInstances[*].DBInstanceIdentifier

RDSインスタンスが2台ある場合の実行結果は以下のようになります。

[
    "database-1-test",
    "database-1-test2"
]

以下は"aws rds describe-db-instances"をオプションを付けずに実行したときの出力です。(長いので出力の一部のみを転記しています)
上記コマンドの"--query"オプションと照らし合わせると"DBInstances"というリストの中にある要素の"DBInstanceIdentifier"を指定しているということが分かると思います。

{
    "DBInstances": [
        {
            "DBInstanceIdentifier": "database-1-test",
            "DBInstanceClass": "db.t3.micro",
            "Engine": "mysql",
            "DBInstanceStatus": "creating",
            "MasterUsername": "admin",
            "AllocatedStorage": 200,
            "PreferredBackupWindow": "15:17-15:47",
            "BackupRetentionPeriod": 0,
            "DBSecurityGroups": [],
            "VpcSecurityGroups": [
                {
                    "VpcSecurityGroupId": "sg-yyyyyyyyyyy",
                    "Status": "active"
                }
<省略>

"--filter"オプション

"--filter"オプションは指定した条件に一致するリソースや情報を取得するときに使用します。
例えばdescribe-db-instancesコマンドでDBエンジンがMySQLのインスタンスのみの情報が取得したい場合は以下のようになります。

aws rds describe-db-instances --filters Name=engine,Values=mysql

上記コマンドを実行すると"Engine": "mysql"のインスタンスの情報のみが出力されます。
"--filter"オプションはコマンドによって"--filter"もしくは"--filters"という風になっています。
また、フィルターできる項目もコマンドごとに変わってくるためコマンドリファレンスを確認する必要があります。
describe-db-instancesでは以下の項目でフィルタリングすることが出来ます。

Nameで指定する項目	説明
db-cluster-id	RDSクラスター名かクラスターARNでフィルタリングする時に使用できます
db-instance-id	RDSインスタンス名かインスタンスARNでフィルタリングする時に使用できます
dbi-resource-id	RDSインスタンスのリソースIDでフィルタリングする時に使用できます
domain	RDSインスタンスが参加しているAWS Managed Microsoft ADのドメインIDでフィルタリングする時に使用できます
engine	RDSインスタンスのDBエンジンでフィルタリングする時に使用できます

参考ドキュメント

AWS CLI の出力をフィルタリングする

やってみた

ここからは知ってるとちょっと役に立つ使い方を紹介します。

"--query"オプションで特定条件でクエリする

RDSインスタンスクラスがdb.t3.microに設定されている"DBInstanceIdentifier"を取得したい場合は以下のようになります。

aws rds describe-db-instances --query 'DBInstances[?DBInstanceClass==`db.t3.micro`].DBInstanceIdentifier'

条件構文は以下のようになっています。
先頭は"?"で始めて比較演算子で値を比較します。

?条件に使う項目==`値`

"--filters"で条件を複数使う

RDSエンジンがMySQLもしくはMariaDBのものを取得したい場合は以下のようになります。

aws rds describe-db-instances --filters Name=engine,Values=mysql,mariadb

RDSエンジンがMySQLで"DBInstanceIdentifier"がdatabase-1のものを取得したい場合は以下のようになります。

aws rds describe-db-instances --filters Name=engine,Values=mysql Name=db-instance-id,Values=database-1

さいごに

"--query"と"--filter"オプションを使いこなすことで必要な情報だけを取得でき、無駄なシェルスクリプトを作成する必要が無くなります。
慣れるまでは時間がかかるかもしれませんが使い方を多少把握しておくのがよいと思います。