nifty-cloud-sdk 1.7

data/CHANGELOG

@@ -0,0 +1,112 @@
+-----------------------------
+ニフティクラウド SDK for Ruby
+-----------------------------
+
+
+2011-07-31 SDK for Ruby Version.1.7
+-------------------------------------------------------------------------------
+	* 新規リリース
+	- API Version 1.7 に対応
+
+オリジナルからの変更点
+
+	* lib/NIFTY.rb
+	- ファイル名を"AWS.rb"から"NIFTY.rb"へ変更
+	- Baseクラスのinitializeオプションを追加
+	- pathlist、pathhashlistのバリデーションを追加
+	- pathlist、pathhashlistで、パラメータ値がnilまたは空の場合は除外する処理を追加
+	- pathkvlistを削除
+	- リクエストでタイムアウトが出た場合、リトライするよう変更
+	- 署名バージョン、署名生成に使用するアルゴリズムを選択できるよう変更
+	- サーバーからのエラー応答に対応するエラークラスを1つのクラスに統合
+
+	* lib/NIFTY
+	- ディレクトリ名を"AWS"から"NIFTY"へ変更
+	- Autoscaling/を削除
+	- Cloudwatch/を削除
+	- ELB/を削除
+	- RDS/を削除
+	- Autoscaling.rbを削除
+	- Cloudwatch.rbを削除
+	- ELB.rbを削除
+	- RDS.rbを削除
+
+	* lib/NIFTY/Cloud
+	- "AWS/EC2"の名前を"NIFTY/Cloud"へ変更
+	- console.rbを削除
+	- devpay.rbを削除
+	- elastic_ips.rbを削除
+	- image_attributes.rbを削除
+	- password.rbを削除
+	- products.rbを削除
+	- snapshots.rbを削除
+	- spot_instance_requests.rbを削除
+	- spot_prices.rbを削除
+	- subnets.rbを削除
+	- tags.rbを削除
+
+	* lib/NIFTY/Cloud.rb
+	- initializeでconfigの値をセットするよう変更
+
+	* lib/NIFTY/config.rb
+	- 新規作成(ユーザー定義値の設定)
+
+	* lib/NIFTY/exceptions.rb
+	- ConfigurationErrorを追加
+	- ResponseFormatErrorを追加
+	- ResponseErrorを追加(APIエラーレスポンスの共通エラークラス)
+	- エラー毎のエラークラスを削除
+
+	* lib/NIFTY/version.rb
+	- VERSIONを変更
+
+	* lib/NIFTY/Cloud/availability_zones
+	- 指定不可パラメータを除外できるよう変更
+
+	* lib/NIFTY/Cloud/certificates.rb
+	- 新規作成(SSL作成・削除など)
+
+	* lib/NIFTY/Cloud/images.rb
+	- バリデーションの追加
+	- 指定不可パラメータを除外できるよう変更
+	- deregister_imageを削除
+	- register_imageを削除
+	- modity_image_attributeを追加
+
+	* lib/NIFTY/Cloud/instances.rb
+	- バリデーションの追加
+	- 指定不可パラメータを除外できるよう変更
+	- reset_instance_attributeを削除
+	- monitor_instancesを削除
+	- unmonitor_instancesを削除
+	- describe_reserved_instancesを削除
+	- describe_reserved_instances_offeringsを削除
+	- purchase_reserved_instances_offeringを削除
+
+	* lib/NIFTY/Cloud/keypairs.rb
+	- バリデーションの追加
+
+	* lib/NIFTY/Cloud/load_balancers.rb
+	- AWS/ELB/load_balancers.rbから移動
+	- バリデーションの追加
+	- 指定不可パラメータを除外できるよう変更
+	- disable_availability_zones_for_load_balancerを削除
+	- enable_availability_zones_for_load_balancerを削除
+	- resister_port_with_load_balancerを追加
+	- update_load_balancerを追加
+	- set_filter_for_load_balancerを追加
+
+	* lib/NIFTY/Cloud/security_groups.rb
+	- バリデーションの追加
+	- 指定不可パラメータを除外できるよう変更
+	- deregister_instances_from_security_groupを追加
+	- register_instances_with_security_groupを追加
+	- describe_security_activitiesを追加
+	- update_security_groupを追加
+
+	* lib/NIFTY/Cloud/volumes.rb
+	- バリデーションの追加
+	- 指定不可パラメータを除外できるよう変更
+
+
+Copyright 2011 NIFTY Corporation All Rights Reserved.

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in NIFTY.gemspec
+gemspec

data/INSTALL

@@ -0,0 +1,30 @@
+-----------------------------
+ニフティクラウド SDK for Ruby
+-----------------------------
+
+ニフティクラウド SDK for Ruby のインストールは、以下の手順で行います。
+
+1. ソースアーカイブの解凍
+
+  % unzip NIFTY_Cloud_SDK_for_Ruby.zip
+  % cd NIFTY_Cloud_SDK_for_Ruby
+
+2. 依存ライブラリの解決 ※bundlerがインストールされていること
+
+  % bundle install
+
+3. テストコードの実行
+
+  % rake test
+
+4. nifty-cloud-sdk のgemパッケージ作成
+
+  % rake build
+
+5. nifty-cloud-sdk をインストール(gemへ登録)
+
+  % rake install
+
+
+Copyright 2011 NIFTY Corporation All Rights Reserved.
+

data/LICENSE.txt

@@ -0,0 +1,58 @@
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README.rdoc

@@ -0,0 +1,375 @@
+= ニフティクラウド SDK for Ruby
+
+== 概要
+
+ニフティクラウド SDK for Ruby は、サーバーの作成・起動・停止やステータス参照などの操作を可能にする Ruby API です。
+この SDK を利用して、ニフティクラウド管理アプリケーションの開発、リソースコントロールの自動化などをより容易に実現することができます。
+
+詳しくは、下記のページをご覧ください。
+
+http://cloud.nifty.com/api/#ruby
+
+== ニフティクラウド SDK for Ruby に含まれているもの
+
+* ニフティクラウド Ruby ライブラリ
+    ニフティクラウドAPI（REST）との通信、処理を実装した Ruby API です。
+    RESTの知識がなくても、お使いの Ruby 環境を利用してアプリケーションの開発をすることが可能です。
+
+* サンプルコード
+    アプリケーション開発のためのライブラリ利用例を内包しています。
+
+* テストコード
+    テスト用のファイルを内包しています。
+
+* ドキュメント
+  * README.rdoc
+      ニフティクラウド SDK for Ruby の説明を記述しています。
+
+  * INSTALL
+      インストール手順について記述しています。
+
+  * LICENSE.txt
+      Ruby License の内容になります。
+
+  * CHANGELOG
+      変更箇所について記述しています。
+
+* パッケージ関連ファイル
+  * Gemfile
+  * Rakefile
+  * nifty-cloud-sdk.gempsec
+
+== 動作環境
+
+* Ruby 1.8.7
+* RubyGems 1.7.2
+* bundler 1.0.12
+* xml-simple 1.0.12
+* mocha 0.9.9
+* test-unix 2.1.2
+* test-spec 0.10.0
+* rcov 0.9.9
+* perftools 0.5.4
+* yard 0.6.2
+
+== 導入
+
+=== API 認証キーの取得
+
+ニフティクラウド SDK for Ruby を利用する前に、ニフティクラウドのアカウントを取得する必要があります。
+
+詳しくは、下記のページをご覧ください。
+
+http://cloud.nifty.com/api/#sdk
+
+=== ニフティクラウド SDK for Ruby のインストール
+
+INSTALL ファイルをご覧ください。
+
+
+== 利用方法
+
+ニフティクラウド SDK for Ruby を利用するためのインタフェースクラスは NIFTY::Cloud::Base です。
+
+=== 準備
+
+API認証キー（公開キー・秘密キー）は、事前に必ず設定してください。
+※それ以外の設定できる値は、環境に合わせて変更してください。
+
+設定方法は下記方法の何れかで設定できます。
+
+* 環境変数
+* 定義ファイル
+* オブジェクト生成時の引数
+
+すべての方法で設定した場合は、下記優先度に従い設定されます。
+
+  オブジェクト生成時の引数 ＞ 環境変数 ＞ 定義ファイル
+
+認証バージョン・APIの認証ロジックで設定できる値は、APIリファレンスをご覧ください。
+
+http://cloud.nifty.com/api/rest/
+
+
+==== 環境変数での設定
+
+[ NIFTY_CLOUD_ACCESS_KEY         ] 公開キー
+[ NIFTY_CLOUD_SECRET_KEY         ] 秘密キー
+[ NIFTY_CLOUD_ENDPOINT_URL       ] エンドポイント
+[ NIFTY_CLOUD_PROXY_SERVER       ] プロキシサーバーURL
+[ NIFTY_CLOUD_USER_AGENT         ] ユーザーエージェント
+[ NIFTY_CLOUD_MAX_RETRY          ] 最大リトライ回数
+[ NIFTY_CLOUD_CONNECTION_TIMEOUT ] 接続タイムアウト(秒)
+[ NIFTY_CLOUD_SOCKET_TIMEOUT     ] ソケットタイムアウト(秒)
+[ NIFTY_CLOUD_SIGNATURE_VERSION  ] 認証バージョン
+[ NIFTY_CLOUD_SIGNATURE_METHOD   ] APIの認証ロジック
+
+環境変数の指定方法は下記のようになります。
+
+例) 公開キーを環境変数で設定する場合(Linux)
+  % export NIFTY_CLOUD_ACCESS_KEY="<Your Access Key>"
+
+==== 定義ファイルでの設定
+
+定義ファイルは、lib/NIFTY/config.rb になります。
+
+[ ACCESS_KEY         ] 公開キー                   (default: '<default access key>')
+[ SECRET_KEY         ] 秘密キー                   (default: '<default secret key>')
+[ ENDPOINT_URL       ] エンドポイント             (default: 'https://cp.cloud.nifty.com/api/1.7/')
+[ PROXY_SERVER       ] プロキシサーバーURL        (default: nil)
+[ USER_AGENT         ] ユーザーエージェント       (default: 'NIFTY Cloud API Ruby SDK')
+[ MAX_RETRY          ] 最大リトライ回数           (default: 3)
+[ CONNECTION_TIMEOUT ] 接続タイムアウト(秒)       (default: 30)
+[ SOCKET_TIMEOUT     ] ソケットタイムアウト(秒)   (default: 30)
+[ SIGNATURE_VERSION  ] 認証バージョン             (default: '2')
+[ SIGNATURE_METHOD   ] APIの認証ロジック          (default: 'HmacSHA256')
+
+==== オブジェクト生成時の引数での設定
+
+[ :access_key         ]  公開キー
+[ :secret_key         ]  秘密キー
+[ :use_ssl            ]  SSL暗号化(現状true以外は認めていない)
+[ :server             ]  ニフティクラウドAPI ホスト名
+[ :port               ]  ニフティクラウドAPI ポート番号
+[ :path               ]  ニフティクラウドAPI パス
+[ :proxy_server       ]  プロキシサーバーURL
+[ :user_agent         ]  ユーザーエージェント
+[ :max_retry          ]  最大リトライ回数
+[ :connection_timeout ]  接続タイムアウト(秒)
+[ :socket_timeout     ]  ソケットタイムアウト(秒)
+[ :signature_version  ]  認証バージョン
+[ :signature_method   ]  APIの認証ロジック
+
+オブジェクト生成時の引数での設定例は、下記「基本操作」の項をご覧ください。
+
+==== プロキシサーバー利用時の設定方法
+
+プロキシサーバーを使用する場合は、プロキシサーバーURLを指定する必要があります。
+※設定例はLinux使用時のものとなります。
+
+＜ユーザー認証がない場合＞
+
+設定例）
+
+  % export NIFTY_CLOUD_PROXY_SERVER='//<host>:<port>'
+
+＜ユーザー認証がある場合＞
+
+設定例）
+
+  % export NIFTY_CLOUD_PROXY_SERVER='//<user>:<password>@<host>:<port>'
+
+* <user> プロキシサーバーに接続するためのユーザー名
+* <password> プロキシサーバーに接続するためのパスワード
+* <host> プロキシサーバーのホスト名
+* <port> プロキシサーバーのポート番号
+
+=== 基本操作
+
+ニフティクラウド SDK for Rubyを利用するためのインタフェースクラスを用いて操作を行います。
+
+  NIFTY::Cloud::Base
+
+オブジェクトの生成は以下のように行います。
+
+＜環境変数・定義ファイルの設定値を使う場合＞
+
+  @nifty = NIFTY::Cloud::Base.new
+
+＜オブジェクト生成時の引数を指定する場合＞
+
+  @nifty = NIFTY::Cloud::Base.new(:access_key => "<Your Access Key>", :secret_key => "<Your Secret Access Key>")
+
+※注意
+ニフティクラウド用に用意しているパブリックメソッドは、APIリファレンス(REST)に記載のあるAPI名とは異なっています。
+例えば 'RunInstances' は、'@nifty.run_instances()' となります。
+
+オブジェクト生成後、利用したいAPIに対応したメソッドを呼び出します。
+
+  res = @nifty.run_instances( options )
+
+  ※optionsには必要なオプションを設定
+
+res にレスポンス結果が格納されます。
+
+
+=== サンプルスクリプト
+
+sample ディレクトリ内をご覧ください。
+
+=== Ruby script 利用例:
+
+RunInstances の例）
+
+  #!/usr/bin/env ruby
+
+  require 'rubygems'
+  require "NIFTY"
+  require 'pp'
+
+  ACCESS_KEY = ENV["NIFTY_CLOUD_ACCESS_KEY"] || "<Your Access Key ID>"
+  SECRET_KEY = ENV["NIFTY_CLOUD_SECRET_KEY"] || "<Your Secret Access Key>"
+
+
+  ncs4r = NIFTY::Cloud::Base.new(:access_key => ACCESS_KEY, :secret_key => SECRET_KEY)
+
+  options = {
+    :image_id                 => "imageId",
+    :key_name                 => "keyName",
+    :security_group           => ["groupName"],
+    :instance_type            => "instanceType",
+    :disable_api_termination  => false,
+    :accounting_type          => "accountingType",
+    :instance_id              => "instanceId",
+    :admin                    => "admin",
+    :password                 => "password",
+    :ip_type                  => "static"
+  }
+
+  pp response = ncs4r.run_instances(options)
+  
+=== Ruby on Rails 利用例:
+
+＜プラグインとして追加＞
+
+プラグイン作成コマンドを実行します。
+
+  % script/generate plugin nifty_cloud_api
+
+作成されたライブラリディレクトリにSDKを展開します。
+
+  ${RAILS_HOME}/vendor/plugins/nifty_cloud_api/lib/NIFTY/…
+                                                   NIFTY.rb
+
+また、作成されたinit.rbファイルを編集し、
+
+  # init.rb
+  # Include hook code here
+  require 'NIFTY'
+
+アプリケーション初期化時に読み込まれるように設定します。
+
+RunInstances の例）
+
+  ncs4r = NIFTY::Cloud::Base.new(:access_key => ACCESS_KEY, :secret_key => SECRET_KEY)
+  options = { ... }
+  pp response = ncs4r.run_instances(options)
+
+=== レスポンス結果の取り扱い
+
+ニフティクラウドからのレスポンスはXML形式で返ってきます。
+
+ニフティクラウド SDK for Ruby では、返ってきたレスポンスをハッシュ構造体にしてユーザーに返却します。
+
+==== レスポンス例
+
+  <RunInstancesResponse xmlns="https://cp.cloud.nifty.com/api/1.7/">
+    <requestId>22e11cc4-0e5a-4815-9892-b1ed6aeed6c4</requestId>
+    <reservationId/>
+    <ownerId/>
+    <groupSet>
+      <item>
+        <groupId>groupName</groupId>
+      </item>
+    </groupSet>
+    <instancesSet>
+      <item>
+        <instanceId>instanceId</instanceId>
+        <imageId>imageId</imageId>
+        <instanceState>
+          <code>0</code>
+          <name>pending</name>
+        </instanceState>
+        <privateDnsName/>
+        <dnsName/>
+        <keyName>keyName</keyName>
+        <admin/>
+        <instanceType>instanceType</instanceType>
+        <launchTime>2011-07-01T13:21:59.074+09:00</launchTime>
+        <placement>
+          <availabilityZone>ap-japan-1a</availabilityZone>
+        </placement>
+        <platform>centos</platform>
+        <monitoring>
+          <state>monitoring-disabled</state>
+        </monitoring>
+        <privateIpAddress/>
+        <ipAddress/>
+        <privateIpAddressV6/>
+        <ipAddressV6/>
+        <architecture>i386</architecture>
+        <rootDeviceType>disk</rootDeviceType>
+        <blockDeviceMapping/>
+        <accountingType>accountingType</accountingType>
+        <ipType>static</ipType>
+      </item>
+    </instancesSet>
+  </RunInstancesResponse>
+
+==== アクセス方法
+
+上記レスポンスが返ってくるとした場合、imageIdを参照したい時は下記操作で参照できます。
+
+  puts res.instancesSet.item[0].imageId         # => imageId
+
+
+=== 例外処理
+
+何らかの理由で処理が失敗した時は、例外が発生します。
+例外の定義は lib/NIFTY/exception.rb で定義されています。
+
+ニフティクラウド SDK for Ruby で発生させる例外は下記になります。
+
+====  定義エラー
+定義値に不正があった場合に出力されれます。
+
+  ConfigurationError
+
+==== 引数エラー
+引数に不正があった場合に出力されれます。
+
+  ArgumentError 
+
+==== フォーマットエラー
+サーバーからのレスポンスが解析できない場合に出力されます。
+
+  ResponseFormatError
+
+==== レスポンスエラー
+サーバーからのレスポンスがエラーの場合に出力されれます。
+
+  ResponseError
+
+===== レスポンスエラー時のエラー情報取得方法について
+レスポンスエラーの場合は、エラーコード・エラーメッセージがクラス内で定義されています。
+
+  begin
+    @nifty.describe_instances
+  rescue ResponseError => e
+    puts "Error Code: #{e.error_code}"
+    puts "Error Message: #{e.error_message}"
+  end
+
+
+== 謝辞
+
+Glenn Rempe氏のライブラリを改変して作成しております。
+
+詳しくは下記ページをご覧ください。
+
+https://github.com/grempe/amazon-ec2/tree/master
+
+== ライセンス
+
+このソフトフェアのライセンスは、Ruby License に従います。
+
+== その他
+
+=== ウェブサイト
+
+* ニフティクラウド : http://cloud.nifty.com/ 
+* ニフティクラウドAPI : http://cloud.nifty.com/api/ 
+* rdoc : http://cloud.nifty.com/api/sdk/rdoc/ 
+
+Copyright 2011 NIFTY Corporation All Rights Reserved.
+