クラウド基盤担当の常田です。
Advent Calendar 5日目の記事として書いています。
目次
はじめに
SoftLayerでは「180をに分かれたサービスにより提供される2200を超える文書化されたメソッドによりSoftLayerの内部管理およびカスタマーポータルが実現されています」とのことです。
今回は、SoftLayerのAPIを使ってみたいという人向けにはじめのとっかりを説明していきたいと思います。
APIへのアクセス
SoftLayerのAPIを利用するためには、プロトコルとしてSORP、XMLRPC、RESTを利用することができます。またライブラリとしてはC、Python、Ruby、PHP等が用意されています。REST等はCurl等でアクセスできますね。
SoftLayerを利用するユーザの多くが利用するであろうslコマンドもPythonのライブラリを利用して作られています。Github等を見る限りPythonライブラリが一番活発に更新されているように思います。ほんとに最近の傾向的には ember.js のライブラリがどんどん登録されていますね。
今回はPythonライブラリを利用してAPIを利用してみたいと思います。
- SoftLayer-Github
- SoftLayer API Python Client 3.3.0 — SoftLayer API Python Client 3.3.0 documentation
環境
今回はUbuntu14.04の環境で利用していきたいと思います。
APIキー
APIを利用するためには、SoftLayer上のアカウントが必要になります。またAPIを利用する際には、通常のポータルへのログインパスワードではなく「APIキー」というものを認証に用いて利用します。
Pythonライブラリの導入
まずはPythonから導入します。
[ root@1ccb2b80a9c6:~ ]$ apt-get install python python-pip -y
[ root@1ccb2b80a9c6:~ ]$ python --version
Python 2.7.6
Setting up python-pip (1.5.4-1) ...
[ root@1ccb2b80a9c6:~ ]$ pip --version
pip 1.5.4 from /usr/lib/python2.7/dist-packages (python 2.7)
次にPIPを用いて導入したいと思います。
[ root@1ccb2b80a9c6:~ ]$ pip install softlayer
以上で導入は完了しました。
作る
SoftLayerのAPIは結構曲者？です。まわりでもかなり最初の取っ掛かりがなくて苦労しています。まずここでは例題としてドキュメントの見方を含めてサンプルを作っていきたいと思います。
例題：APIからユーザのリスト（「id」、「ユーザ名」、「APIキー」）を一覧表示する
結論を書くと最終的には数行のプログラムなのですが取得する値をどうやって見つけていくかを流れで見て行きたいと思います。
最終的な回答
#!/usr/bin/env python3
#
import SoftLayer
client = SoftLayer.Client()
account = client['Account']
users = account.getUsers()
for user in users:
for key in client['User_Customer'].getApiAuthenticationKeys(id=user['id'],mask='authenticationKey'):
apikey = key['authenticationKey']
print("id:%d, %s ,%s" % (user['id'],user['username'],apikey))
apikey = "\0"
実行結果
agrant@ubuntu1404:~/api_study$ python user.py
id:123456, NIC32222 ,aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
id:123457, admin@NIC32222 , aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
メソッドを探す（ドキュメント）
APIリファレンス
- SoftLayer API | SoftLayer Development Network
- SoftLayer Services | SoftLayer Development Network
- SoftLayer API Python Client 3.3.0 — SoftLayer API Python Client 3.3.0 documentation
この3つのドキュメントから探しながら進めることになります。
Pythonでの準備
はじめにPythonを用いてSoftLayerのAPIを調べていく方法を書いておきます。APIを利用する際にもCLIで利用する際にも ~/.softlayer を定義すると便利です。
[softlayer]
username = 名前
api_key = APIキー
endpoint_url = https://api.softlayer.com/xmlrpc/v3/
この定義ファイルがあるとPythonでオブジェクトを生成する際にusername, api_keyを指定することなく利用することが可能です。
pythonコマンドをインタラクティブに使い各サービスが何を調べることが出来るのかを使います
vagrant@ubuntu1404:~/api_study$ python
Python 2.7.6 (default, Mar 22 2014, 22:59:56)
[GCC 4.8.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import SoftLayer
>>> client = SoftLayer.Client()
>>> client
<Client: endpoint=https://api.softlayer.com/xmlrpc/v3, user=<BasicAuthentication: NIC396820>>
>>> client['Account']
<Service: Account>
>>> client['Account'].getObject()
{'lastName': 'Tokida', 'city': 'Tokyo', 'postalCode': ・・・略・・・ 'isReseller': 0, 'createDate': '2014-10-27T23:34:05-07:00', 'claimedTaxExemptTxFlag': False}
>>>
こういった形で少しづつほじくり返していき調べる事が出来ます。
少し概要
SoftLayerのAPIは「Service」として定義されています。サービスには「Method」が定義されており各値を取得することができます。取得できる値は「Data Type」として用意されています。
APIの呼び出しには、先ほどの clientオブジェクトを例にすると client[サービス名].メソッド(引数) として実施します。上記の画像のAccountを例にすると client['Account'].addAchInfomation() となります。次に引数について見てみましょう。
このHeaderに書かれている項目が「引数」になります。この中の Required Hadersが必須の引数に成ります。現在記載されているauthenticateはPythonのライブラリが補完してくれますので記載は不要です。つまり今回の場合には引数は不要ですね。
「ユーザ」に関する項目を探してみる。
先ほどのリファレンスのサイトで、以下の検索Boxに適当な文字(user)を入れてみましょう。（補足ですが、ポータルにログインするIDはSoftLayer上では「ユーザ」と言われています。これら「ユーザ(user)」を含む環境全体が「アカウント(Account)」となります）
検索文字を入れると動的に絞込がされます。
ここで見てみると「Service」として「User_Customer」というのが有るのがわかります。次にこの「User_Customer」サービスを見てみましょう。
今回はユーザのID、名前、APIキーを取得(get)したいのでそれらしいメソッド（Methods)があるのかを次に調べます。取得する関数は概ね getを接頭語にもつように定義されています。また定義されている全ての値を取得する方法としては getObject()メソッドが用意されていることが多いので今回も中を見てみます。
引数を見てみると、どうやらUser_CustomerInitParametersが必要であるようです。つまりこの関数を呼び出すためにはそもそも調べたいユーザidが必要になりそうですね。実際にこの getObjectを実行するとData Typeで定義されている値が取得することができます。
他にも色見てみるとAPIキーはこれで取得できそうです。
その他探してみてもID自体を取得ることが出来るのがなさそうなので基本に立ち返ってSoftLayer_Accountからもう一度見てみたいと思います。
メソッドを検索しているとそもそもgetUsersという関数がありました。引数もなく利用できそうです。
>>> client['Account'].getUsers()
[{'username': 'NIC396820', 'modifyDate': '2014-12-02T05:44:47-06:00', 'localeId': 1, 'locale': {'languageTag': 'en-US', 'name': 'English'}, 'authenticationToken': {'userId': 278224, 'hash': '1d55558c50e6da359f0e237485ae6422'}, 'secondaryPasswordModifyDate': '2014-10-28T01:46:27-07:00', '
以下略
沢山出てきました。これで問題なくユーザの一覧が取得できそうです。
次にこの取得する際に、取得するデー
タを絞り込んだり条件をつけたりすることができます。これらをSoftLayerではObjectMaskとして定義されています。全てのデータを取得するとサイズが大きくなるので mask(フィルタ）をすることになります。今回の場合には、id , username が取れれば良いようです
>>> users = client['Account'].getUsers(mask='id,username')
これで目的のユーザのIDが取れました。先ほどのgetApiAuthenticationKeysが呼び出せそうです。先ほどの実行結果にて取得されたidを1つ利用して次のコードを実行してみましょう。
>>> client['User_Customer'].getApiAuthenticationKeys(id=1234567)
これで目的のAPIキーが確認できました。
スクリプト化する
これで最初に記載したプログラムを書くための準備ができたことと思います。最終的には AccountサービスからgetUsersでID/Nameを取得する。User_CustomerサービスからIDを元にAPIキーを探す。このステップでできますね。
まとめ
今回はPythonを使ってみましたがその他のライブラリでも同じように作っていくことが出来ると思います。今回のようにメソッド等を調べていく上ではPythonは非常に楽に利用することができるので積極的に使って行きたいと思っております。
日本語のドキュメントが非常に少ないので参考になれば幸いです。
