CloudStack API を呼び出すURL文字列の作り方を調べる

CloudStack APIを呼び出すAPIリクエスト(URL)の作り方



LDAP認証などは
CloudStack Management Serverが提供する
管理コンソール上からは設定することができない。

このようなGUI経由で操作できない
設定などを行いたい場合は、
CloudStackを外部のプログラムから操作できるAPIが
予め提供されているのでこれを使う必要がある。


で、これがかなり厄介、
手順がめんどくさいのだ。


まず認証。
これはAWSでログインする時などと同じ
APIキーと秘密キーを使う。

取得の仕方は、以下の操作を実行し、

1. Management Serverの管理コンソールへログオン
2. アカウント
3. admin(adminアカウントを使う場合)
4. ビューユーザーボタン押下
5. admin(adminユーザを使う場合)
6. 鍵アイコンのとなりのボタン（キーの生成とバルーン表示される）押下

画面に表示される「APIキー」と「秘密キー」を入手しておく。


次に、
ドキュメントとしてJava Docっぽいサイトが
公開されているので、
このなかから使いたいコマンドを探し出す。

CloudStack API Documentation (v3.0)

ここであたりをつけて
コマンド名、
パラメータのフィールド、
および値
が決まったら、
次に HTTP GETメソッドで送信するパラメータを含むURL
（APIリクエスト）を作る必要がある。



文字列のつくりかたは
CloudStack 2.2 -3.0 API Developer's Guideに書かれている。



APIリクエストの形式は、
"Base URL + API Path + Command String + Signature"形式
で構成される。

各構成は以下のとおり


Base URL: CloudStack Management ServerのIPアドレス、ポート
例）http://192.168.11.100:8080

API Path: リクエストを受け付けるAPI Serverのパス
/client/api?

Command String: コマンド、パラメータ群、CloudStack認証に使用するAPIキーを含む問い合わせ文字列
例）command=ldapConfig&hostname=127.0.0.1&searchbase=ou%3Dtesting%2Co%3Dproject&queryfilter=%28%26%28uid%3D%25u%29%29&binddn=cn%3DJohn+Singh%2Cou%3Dtesting%2Co%project&bindpass=secret&port=10389&ssl=true&truststore=C%3A%2Fcompany%2Finfo%2Ftrusted.ks&truststorepass=secret&response=json&apiKey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Signature: ユーザの秘密キーとハッシュ化アルゴリズムHMAC SHA-1を組み合わせたBase URLのハッシュ化された署名
例）signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx





Signatureを生成する手順：
1. HTTP GETメソッドで送信するために、Command Stringの各々のフィールドと値のペア(&で分割されたhogehoge=fugafuga形式のこと)に対して、値部分をURLエンコードする

注意：ただし、スペースは"+"の代わりに"%20"でエンコードすること

例）
編集前：command=aaaa&bbb=c c&ddd=(eee)&apikey=XXXXX
編集後：command=aaaa&bbb=c%20c&ddd=%28eee%29&apikey=XXXXX

2. Command String文字列を全部小文字化して、フィールド部分でソートする

例）
編集前：command=aaaa&bbb=c%20c&ddd=%28eee%29&apikey=XXXXX
編集後：apikey=xxxxx&bbb=c%20c&ddd=%28eee%29&command=aaaa


3. ユーザの秘密キーを使って、ソートしたCommand StringをハッシュアルゴリズムHMAC SHA-1(大抵のプログラミング言語はユーティリティメソッドとしてこの機能を保有している)にかける

例）OpenSSLを使ってハッシュ化する場合のコマンド
# echo -n apikey=xxxxx&bbb=c%20c&ddd=%28eee%29&command=aaaa openssl sha1 -binary hmac 秘密キー

ここでハッシュ化する対象を間違えたりしない様に注意する。

HTTP経由で安全に変換できるように、取得した文字列をさらにBase64エンコードしてUTF-8にする。

Base64 エンコード後の文字列がSigniture値(signiture=の後に続く文字列)となる。










..わけわからん..

なにか楽ができないものか..

色々調べてみると、
APIキー/秘密キーやコマンドやパラメータが確定していれば
エンコードやsignitureなどを加工してくれるシェルスクリプトを
公開している人(会社？)を見つけた。
ありがたや、ありがたや。

bash script for CloudStack API  - asako

この記事の最後にあるスクリプトに
自分のAPIキー、秘密キーを書き込み、
最後の行でcurlを使っているのでそこはコメントアウトして
実行すればよい。

./key_api.sh command=listAccounts
と実行すれば
 SEND URL: http://192.168.11.101:8080/client/api?command=listAccounts&apikey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
といったURLを表示してくれる。

command=listAccountsでURLを作って
ブラウザのURL入力欄にいれて実行して
びろびろ長いXMLが出てくれば成功で

errorcodeタグを含む短い文字列の場合は
失敗である。

APIをプログラムで使う前に
開発者はまずこれで
つながることを試す必要がある。

結果がXMLだったがresponse=jsonをつければ
JSON形式にもなるようだ。





..ここまで調べるのにまる１日..


もう、誰か本とかかいてくれないかなあ..



p.s.
Javaでこのシェルスクリプト相当の機能を実装してみました。
CloudStack API を呼び出すURLを生成するJavaサンプルコード