curlでお手軽にさくらのクラウドAPIを使ってみた(curl + jq)

今年の締めくくりとして、さくらのクラウドをとり上げてみたいと思います。
最近はクラウド全盛で、AWSやDigitalOcean等のパブリッククラウド事業者をつまみ食いしていますが、さくらのクラウドも国産のパブリッククラウドとして有名なので、今回はAPIを経由してサーバーを操作してみました。

クラウドサーバーならさくらのクラウド

前準備

awscliみたいにコマンドで扱えて、さらには結果はJSONで取得できて、awscliのJSON操作コマンドとして有名なjqを使って必要な情報を取得できると嬉しいです。
さくらのクラウドの生のREST APIもcurlで叩けばレスポンスはJSONでもらえるようです。
というより、最近の潮流としてはAPIはRESTで提供してJSONで構造化したテキストデータを返却するのが多いように感じます。

jqって何？

jq とはawscliを使うときに存在を知ったのですが、JSONを操作するコマンドです。sed等のストリームエディタの系統のものです。
awscliの結果はJSONで返却されるので（デフォルトはそうじゃないのでしょうか？）、jqを多用してJSONの整形や目的とする属性値を取得します。
慣れてくると結構面白いコマンドです。
以下のサンプルではとりあえずjqコマンドがインストールされていて、パスが通っていればすぐに実行可能です。
インストール方法は JSON処理コマンド jq を使ってみた | ユニキャストラボ になります。

なお、APIを叩くのはcurlコマンド自体あればできるので、無理にjqコマンドを使う必要はありません。
また、本操作は さくらのクラウドAPI 1.1 に対応しています。

さくらのクラウドAPIキーを生成する

AWSのAPIを叩くときもそうですが、APIキーが必要になります。
さくらのクラウドのコントロールパネルにアクセスして、設定＞APIキー＞追加ボタンでAPIキーを追加します。
追加したらその ACCESS TOKEN と ACCESS TOKEN SECRET を控えます。
当然ですが、そのキーは漏れたらやばいので厳重に管理します。

サーバーの基本的なAPI操作

ここではサーバーはすでに作成してあるものと仮定します。ちょっと手順が複雑ですぐにはわかりませんでした。
ちなみに、EC2インスタンスと違って、インスタンスを停止しても時間課金が継続されるようですので注意が必要です。
不要になったらインスタンスを削除しましょう。

サーバーの一覧を取得

まずは現在作成済みのサーバーの一覧を取得します。 aws ec2 describe-instances に相当します。
はじめは少しずつコマンド結果を洗練していきます。

まずは最低限の呼び出し

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/ \
    2>/dev/null

• --user でBasic認証キーの設定
• URL中にゾーン is1b（石狩第2ゾーン）を指定する
• 2>/dev/null で curl の進捗表示を捨てています

一応結果は得られましたが、人間が読むのにはつらいです。今度はAPIで提供されているカスタムリクエストヘッダ X-Sakura-API-Beautify を指定してあげます。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/ \
    2>/dev/null

さくらAPI側できれいに整形してくれました。それでも単色なのと、エスケープされていてわかりにくい気がします（テキストで取得している以上しょうがないですが・・・）。
そこで、パイプを使ってjqコマンドに流し込んでみましょう。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/ \
    2>/dev/null | jq '.'

いやー綺麗ですね。

jqによる必要な情報の絞り込み

これでも長い気がするのでJSONの構造を掘り込んでいきます。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/ \
    2>/dev/null | jq '. .Servers [] .Instance'

{
  "CDROMStorage": null,
  "CDROM": null,
  "Host": null,
  "ModifiedAt": "2013-12-31T00:00:00+09:00",
  "Server": {
    "ID": "99999999999"
  },
  "Status": "down",
  "BeforeStatus": "cleaning",
  "StatusChangedAt": "2013-12-31T00:00:00+09:00",
  "MigrationProgress": null,
  "MigrationSchedule": null,
  "IsMigrating": null,
  "MigrationAllowed": null
}

かなり絞りこまれて見やすくなりました。同じ要領でさらにIDまで絞り込みます。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/ \
    2>/dev/null | jq '. .Servers [] .Instance .Server .ID'

"99999999999"

特定のサーバーの情報を取得する

IDがわかったので該当サーバーの詳細な情報を取得します。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/99999999999 \
    2>/dev/null | jq '.'

{
  "is_ok": true,
  "Server": {
    "Tags": [],
    "Appliance": null,
    "Interfaces": [
      {
        "PacketFilter": null,
        "Switch": {
          "UserSubnet": null,
          "Subnet": {
            "Internet": {
              "BandWidthMbps": 100
            },
            "DefaultRoute": "XXX.XXX.XXX.1",
            "NetworkMaskLen": 24,
            "NetworkAddress": "XXX.XXX.XXX.0",
            "ID": null
          },
// (snip)

IPアドレスまで掘り下げます。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/99999999999 \
    2> /dev/null | jq '. .Server .Interfaces [0] .IPAddress'

"XXX.XXX.XXX.XXX"

サーバーを起動・停止した時にこのIPアドレスでサーバーにping疎通の変化を確認してみると面白いと思います。

サーバーを起動する

今度はPUTメソッドを使います。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -X 'PUT' -d '' \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/99999999999/power \
    2> /dev/null | jq '.'

サーバーを停止

今度はDELETEメソッドを使います。

curl --user "API_ACCESS_TOKEN_HERE":"API_SECRET_KEY_HERE" \
    -X 'DELETE' -d '' \
    -H 'X-Sakura-API-Beautify:1' \
    https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/server/99999999999/power \
    2>/dev/null | jq '.'

まとめ

AWSのAPIがあるくらいだからさくらのクラウドにもプログラマブルデータセンター的なAPIがあるのかなーと思って検索しましたが、やはりありました。さくらのクラウドもAWSみたいにAPIで操作できるようになっているんだなあと実感して感慨深いです。

awscliみたいなsacloud CLIというのも純正であるみたいなのですが、Node.jsで実装されているようなので、まだ試せていません。さくらのクラウドもリリースされてだいぶたったので、APIに関連する記事がバンバン出てるのかと思ったのですが、あまり見つからなかったのでもっとツールが充実するといいいなと思っています。

最近時間課金モデルになったのでさくらのVPSよりも手軽な印象です。
そのほかにもいろいろできるようなので、たくさん勉強できそうです。
どんどん便利なものになるといいですね。

よいお年を。

参考文献

• さくらのクラウド API v1.1 ドキュメント
• sakura-internet/node-sacloud
• Getting started Guide · sakura-internet/node-sacloud Wiki
• 「さくらのクラウド」を使ってみる(1) sacloud CLI のインストールからサーバー起動まで #sacloud – jitsu102’s blog
• クラウドサーバーならさくらのクラウド
• JSON処理コマンド jq を使ってみた | ユニキャストラボ
• cURL – How To Use （マニュアルページ日本語訳）