Amazon CloudSearch コマンドラインツールを使ってみる

AWSのコマンドラインツールとしてはAWS CLIがスタンダードとなっていますが、 2014年7月現在、Amazon CloudSearchに関しては独立した別のツールが提供されており、それを使うことが推奨されています（現時点では、AWS CLIでは、一部の機能しか利用できません）。

今回はそんなAmazon CloudSearch CLIの設定方法と使い方をまとめておきます。

準備

Amazon CloudSearch CLIはJavaのツールとして提供されています。 はじめに、公式ドキュメントからリンクを辿ってコマンドラインツールをダウンロードして適当なディレクトリに展開してください。

JRE

Amazon CloudSearch CLIは実行環境としてJava（JRE）が必要です。 Java 7以降が必要なのでインストールされているかを確認してください。

JAVA_HOMEの設定

環境変数にJAVA_HOMEを設定します。

MacOSであれば、

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_05.jdk/Contents/Home/

または

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_45.jdk/Contents/Home/

といったパスになります。

PATHの設定

環境変数CS_HOMEをCloudSearchコマンドラインツールのパスに設定し、binディレクトリをパスに通します。

export CS_HOME=path_to_cloud_search_cli_dir
export PATH=$PATH:$CS_HOME/bin

証明書ファイルの設定（オプション）

アカウントのアクセスキーとシークレットキーを保存した証明書ファイルを用意し、環境変数AWS_CREDENTIAL_FILEに設定します。

accessKey=YOUR_ACCESS_KEY
secretKey=YOUR_SECRET_KEY

export AWS_CREDENTIAL_FILE=path_to_credential_file

証明書ファイルのパーミッションは600としてください。

なお、環境変数で証明書ファイルを設定しない場合、コマンド実行時に--aws-credential-fileオプションまたは、--access-key/--secret-keyオプションが必須になります。

エンドポイントの設定（オプション）

CloudSearchのリージョンに相当するエンドポイントを環境変数に設定します。 東京（ap-northeast-1）リージョン以外を利用する場合はリージョン名を書き換えてください。

export CS_ENDPOINT=cloudsearch.ap-northeast-1.amazonaws.com

環境変数でエンドポイントを設定しない場合、コマンド実行時に--endpointオプションが必須になります。

基本コマンドの実行

幾つかのコマンドを実行してみましょう。

ドメインの確認 - cs-describe-domain

ドメインとは、CloudSearchで全文検索を行う単位です。 ドメインはcs-describe-domainコマンドで確認出来ます。

$ cs-describe-domain 
Connecting to CloudSearch in region [ap-northeast-1]

=== Domain Summary ===
Domain Name: developersio-cloudsearch
Document Service endpoint: doc-developersio-cloudsearch-xxxxxxxxxxxxxxxxxxxxx.ap-northeast-1.cloudsearch.amazonaws.com
Search Service endpoint: search-developersio-cloudsearch-xxxxxxxxxxxxxxxxxxxxx.ap-northeast-1.cloudsearch.amazonaws.com
SearchInstanceType: search.m1.small
SearchPartitionCount: 1
SearchInstanceCount: 1
Current configuration changes require a call to IndexDocuments: No
======================

ドメイン名だけでなく、インスタンスタイプやインスタンス数なども確認できました。

ドキュメントのアップロード - cs-import-documents

ドキュメントをアップロードするには、cs-import-documentsコマンドを利用します。 ドキュメントは、ローカルファイルからもアップロードできますが、S3やDynamoDBに保存したドキュメントを指定することもできます。

ドキュメントは、あらかじめ構造化し、JSONまたはXMLのフォーマットで作成しておかなれければなりません。 また、ドキュメントのアップロードの前にインデックスを作成する必要もあります。

ローカルファイル

ローカルファイルをアップロードする場合は、ファイルまでのパスを指定します。

$ cs-import-documents --format xml --source ./data/sample.xml --domain-name developersio-cloudsearch

S3

S3を指定する場合は、次のようにエンドポイントを指定します。 ワイルドカード（?, *, **）を利用し、大量のファイルをまとめてアップロード可能です。

$ cs-import-documents --format xml --source https://s3-us-west-2.amazonaws.com/developersio-xxxxx-xxxx/* --domain-name developersio-cloudsearch