AWS Command Line Interface(AWS CLI)で複雑な入力パラメータを扱う

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

小ネタです。

公式ドキュメント等でも記載があるし(公式ドキュメントに載っているからこそ)、もしかして常識的過ぎる内容なのかも?と思っていたのですが、ざっと検索してみる感じ(少なくとも)国内であんま言及されていない&割と必要となる局面があるのでは(少なくとも自分は"灯台もと暗し"状態で公式を見ておらず『あ、こんな本丸に便利な情報が...!』と軽くテンション上がった)と思いこのエントリを書いてみました。

複雑な入力パラメータの使用

AWS CLIに於いて、多くのパラメータは以下例での『MyKeyPair』のように、シンプルに数値や文字列等が要求されます。

aws ec2 create-key-pair -–key-name MyKeyPair

しかしながら、幾つかの操作に関しては入力パラメータとして複雑なデータ構造の内容が求められる場合があります。

これらのパラメータは、直接コマンドラインまたはコマンドラインから参照されているファイルのいずれかで、JSONデータ構造として提供されなければなりません。

例えば、『ec2-describe-instances』コマンドを使う上で復数のパラメータを渡す必要がある『--filter』オプションの場合、JSONデータ構造としてパラメータをフォーマットした状態で用意しなければなりません。

$ aws ec2 describe-instances --region ap-northeast-1 help
DESCRIBE-INSTANCES()                                      DESCRIBE-INSTANCES()



NAME
       describe-instances -

DESCRIPTION
       The  describe-instances  operation  returns information about instances
       that you own.

       If you specify one or more instance IDs, Amazon EC2 returns information
       for  those  instances.  If  you do not specify instance IDs, Amazon EC2
       returns information for all  relevant  instances.  If  you  specify  an
       invalid  instance  ID,  a fault is returned. If you specify an instance
       that you do not own, it will not be included in the returned results.

       Recently terminated instances might appear  in  the  returned  results.
       This interval is usually less than one hour.

SYNOPSIS
       aws ec2 describe-instances
         [--filters <value>]
         [--instance-ids <value>]

REQUIRED PARAMETERS
       None

OPTIONAL PARAMETERS
       --filters (list)
              A  list of filters used to match properties for Instances. For a
              complete reference to the available filter keys for this  opera-
              tion, see the Amazon EC2 API reference .

       (structure)
              A  filter  used  to limit results when describing tags. Multiple
              values can be specified per filter. A tag must  match  at  least
              one of the specified values for it to be returned from an opera-
              tion.

              Wildcards can be included in filter  values;  *  specifies  that
              zero or more characters must match, and ? specifies that exactly
              one character must match. Use  a  backslash  to  escape  special
              characters.  For  example, a filter value of \*amazon\?\\ speci-
              fies the literal string *amazon?\

(長くなるので以下略)                                                          

フィルタをONにするためにどのようなパラメータを定めるかは、APIリファレンスをご参照ください。

そして、JSONデータ構造としてパラメータをフォーマットします。以下例では、"instance-type" パラメータ名と共に"m1.small"の値がJSONデータ構造としてフォーマットされています。

{"name":"instance-type","values":"m1.small"}

もし復数の値でフィルタリングしたい場合、それらをリスト又は配列の形でフォーマットします。

{"name":"instance-type","values":["m1.small","t1.micro"]}

JSONデータ構造としてフォーマットされれば、コマンドラインに構造を追加したり、JSONファイルとして保存し、コマンドラインからファイルを参照したり出来るようになります。

コマンドライン上でJSONデータ構造体を取り扱う

LinuxやUnix,Mac OS X等、シングルクオート(')でJSONデータ構造をエスケープする環境で JSONデータ構造体としてフォーマットされた形でパラメータを入力する方法です。以下例。

aws ec2 describe-instances --filter '{"name":"instance-type","values":"m1.small"}'

一方で、WindowsはJSONデータ構造を囲むようにエスケープ文字としてダブルクオート(")を使用します。

また、JSONデータ構造で用いられる各々のダブルクオートにはバックスラッシュ(\)エスケープ文字を付加する必要があります。以下例。

aws ec2 describe-instances --filter "{\"name\":\"instance-type\",\"values\":\"m1.small\"}"

もし複雑な入力パラメータを使用するのであれば、JSONデータ構造にフォーマットされたパラメータをファイル保存し、コマンドプロンプトからファイル参照する形で利用する事をお勧めします。

ファイル参照の形でJSONデータ構造体を取り扱う

JSONデータ構造体の形式でフォーマットされたJSONファイルを参照する場合、2つの方法があります。

1つは、ファイル接頭辞(file://)を使用して以下例の用にファイルへのパスを含める方法です。

aws ec2 describe-instances --filter file://C:\path\to\filename.json

もう1つは、ファイルをURL参照可能な形で準備し、『http:』若しくは『https://』で参照する方法です。

以下例ではAmazon S3バケットにあるJSONファイルをURL参照しています。

aws ec2 describe-instances --filter http://bucketnamehere.s3.amazonaws.com/filename.json

前述の2例では、filename.json ファイルは以下のJSONデータ構造体でフォーマットされたパラメータを含んでいます。

{"name":"instance-type","values":"m1.small"}

より複雑なJSONデータ構造体パラメータを扱っている例については、以下ガイドをご参照ください。

まとめ

引数に配列ならまだしも複雑な構造体を渡さにゃならんとなるとちまちま書くのは面倒だな~と思っていたし、実際そうしなければならなくなるのであればCLIの良さが失われてしまうよな~と思っていたのでこの機能はとてもありがたいですね。(JSONファイルベースで)共有出来る部分は上手く共有して行き、諸々の作業を捗らせて行きたいものです。