IBM SmarterCloud Enterprise+ のサービスをプログラムで呼び出す

マネージド・クラウド・サービスをサポートする API の概要

この記事では、IBM SmarterCloud Enterprise+ Version 1.2 の管理者ユーザーのために、SmarterCloud Enterprise+ の API を使用して基本的な管理タスクを実行する方法について説明します。コマンドの例を示しながら、この API を使用してメタデータやリソースを確認する方法、管理用リソースを管理する方法、仮想サーバーを管理する方法を説明します。

Andrew Hoppe, Senior Software Engineer, IBM

Andrew Hoppe (理学博士) は、2003年に IBM が Rational を買収した際に IBM の一員となりました。彼には 20 年に及ぶソフトウェアのモデリング、設計、開発の経験があります。2013年には、テクニカル・アーキテクトとして IBM Global Technology Services (GTS) Global Cloud Ecosystem チームのメンバーとなりました。



Jeff Klink, Senior Technical Staff Member, IBM

Jeff Klink は IBM カナダのシニア・テクニカル・スタッフ・メンバー (STSM) です。この 10 年は、Linux ベースの技術や設計を中心に、仮想化、アプライアンス、ネットワーキング、バックアップなどの技術に携わってきました。現在は、IBM x86 および Power シリーズを使用した SaaS ベンダーが、SoftLayer および IBM SmartCloud Enterprise+ のパブリック・クラウド上でソリューションを設計、構築できるようにするための IBM Global Technology Services (GTS) Global Cloud Ecosystem テクニカル・チームのワールドワイド・リーダーを務めています。



2014年 2月 13日

IBM SmarterCloud Enterprise+

IBM クラウド・コンピューティング・オファリングの 1 つである SmarterCloud Enterprise+ は、エンタープライズ・クラスの IaaS (Infrastructure as a Service) 環境を提供します。IBM では、Tivoli の自動化ツールやモニター・ツールを始めとする、自動化されたツールを使用して、SmarterCloud Enterprise+ の運営および全体の管理を行います。SmarterCloud Enterprise+ は、セキュリティー、信頼性、およびパフォーマンスに優れていること特徴としていることから、クラウド対応のレガシー本番ワークロードを IBM のグローバルなデータ・センターでホストするにはうってつけです。

IBM SmarterCloud Enterprise+ のユーザーは、ISM (Integrated Service Management: 統合サービス管理) ベースの Web ポータルを利用して仮想資産を作成、管理することができます。ポータルの機能の大部分は API を使用して利用することもできます。API を使用すると、SmarterCloud Enterprise+ のリソースの作成および保守をプログラムから行うことができます。つまり、API を使用して SmarterCloud Enterprise+ のデプロイメントを自動的にプロビジョニング、スケーリング、再構成することができます。

SmarterCloud Enterprise+ の API は、あらかじめ定義されているエンドポイント URL に用意されている REST (REpresentational State Transfer) 呼び出しとして実装されています。(エンドポイント URL は SmarterCloud Enterprise+ のオンボード時に IBM のお客様に通知されるため、この記事の例では実際のエンドポイント URL の代わりに endpoint_URL をプレースホルダーとして使用します。) この API には以下の 3 つの主な機能があります。

  • SmarterCloud Enterprise+ のメタデータやリソースに対する読み取り専用での確認
  • 管理用リソース (ユーザー、チーム、プロジェクト、承認) の管理
  • SmarterCloud Enterprise+ の仮想サーバー、パッチ、スナップショットの管理

この記事では、上記 3 つのカテゴリーすべてについて、例を示しながら API の使い方を説明します。この記事のコード・サンプルでは cURL コマンドライン・ユーティリティーを使用します。cURL を使用すると、単純な HTTP コマンドを使用してデータを送信することができます。またこの記事では、cURL での各呼び出しの中で REST を呼び出すためのパラメーターについても説明します。

呼び出しの構文

SmarterCloud Enterprise+ の REST API リクエストでは、呼び出しパラメーターを HTTP リクエストのヘッダーに含めて渡すことも、HTTP リクエストの本体に含めて渡すこともできます。リクエストのメッセージ本体に含めてパラメーターを渡す場合、Content-Type ヘッダー要素の値として application/xml または application/json のいずれかを指定する必要があります。Content-Type の値に応じて、作成されるリソースに関するすべての属性を含む XML 要素または JSON (JavaScript Object Notation) 要素をリクエストの本体に含める必要があります。また、Accept ヘッダーを使用して、レスポンスに要求されるフォーマット (application/xml または application/json) を指定することもできます。

一連の要素を返すための REST クエリー (HTTP GET リクエスト) には、そのクエリーに対するフィルタリング基準を指定する URL パラメーターを追加することもできます (例えば、GET baseURL/users?first_name=John など)。また、結果のソートまたは一部削除を GET クエリーでリクエストすることもできます。詳細については、IBM SmarterCloud Enterprise+ の API 仕様についてのドキュメントを参照してください。このドキュメントは、オンボード時に入手することができます。


SmarterCloud Enterprise+ のプロジェクトとサーバー・インスタンスを表示、作成、保守する

次に、API を使用して SmarterCloud Enterprise+ のプロジェクトとサーバー・インスタンスの表示、作成、保守をプログラムで行う方法を説明します。

リソースのメタデータを取得する

図 1 は SmarterCloud Enterprise+ のリソース・モデルを示す図です。

図 1. SmarterCloud Enterprise+ のリソース・モデル
SmarterCloud Enterprise+ のリソース・モデルの説明

図 1 で、矢印はリソース間の依存関係、つまり、あるリソースによる別のリソースの参照を示しています。このモデルから、インスタンス (SmarterCloud Enterprise+ サーバー) の作成に必要なリソースの種類がわかります。インスタンスはグループに関連付けられます。「グループ」はリソースを抽象的にグループ化したものであり、グループに対して SmarterCloud Enterprise+ の中で唯一、実際に実現されるものはプロジェクトです。そしてプロジェクトは、ユーザーを含むチームで構成されます。チーム、ユーザー、グループにインスタンスを関連付けるには、その前にチーム、ユーザー、グループを作成する必要があります。

: この記事で紹介するコマンドの例のすべてにおいて、太字の斜体フォントは、コマンドを実行するユーザーがエンドポイント URL の他に指定しなければならない情報 (その一例) を示しています。また、この記事で説明する cURL コードのサンプルには、読みやすくするために改行を含めてあるので、これらのコマンドを実行する際には、改行を削除してください。

さらに、ユーザーとインスタンスを既存の SmarterCloud Enterprise+ リソースの数々と関連付ける必要があるため、これらのリソースのメタデータを抽出する必要があります。例えば、ユーザーには SmarterCloud Enterprise+ 固有のリソースであるロールが必要です。

SmarterCloud Enterprise+ のユーザーは、最大 2 つのロールを持つことができます。ユーザーのロールのメタデータを取得するには、以下のように REST で GET コマンドを実行します。

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/roles

上記のコマンドに対するレスポンスの例を以下に示します。

<roles>
  <role>
    <id>53</id>
    <name>Administrator</name>
    <role_group>IaaS-User</role_group>
  </role>
  <role>
    <id>54</id>
    <name>Business Manager</name>
    <role_group>IaaS-User</role_group>
  </role>
</roles>

ブラウザーはデフォルトで HTTP の GET リクエストを実行するため、ブラウザーで REST の GET コマンドを実行することもできます。その場合は、以下のように REST 呼び出しの URL を入力します。

https://endpoint_URL/roles

するとブラウザーは、デフォルト・フォーマットである XML フォーマットのレスポンスを表示します。

ユーザーを作成する

ユーザーを作成するには、以下の項目を指定する必要があります。

  • ユーザー ID (ユーザーの e-メール・アドレス)
  • 表示名
  • 姓 (ラスト・ネーム)
  • 名 (ファースト・ネーム)
  • ロール参照のリスト
  • 言語
  • ロケール

ロール・リストはロールの URI (Uniform Resource Identifier) の配列でなければなりません。REST 呼び出しに含めるこれらの URI の形式は、/tag/id であり、例えば、管理者ロールは /roles/53 といった具合です。以下の例は REST リクエスト内の XML データ要素の中でユーザー・データを指定する方法を示しています。

<user>
  <userid>billtester@test.com</userid>
  <name>Bill Tester</name>
  <first_name>Bill</first_name>
  <last_name>Tester</last_name>
  <roles>
    <role uri="/roles/53" />
   </roles>
  <language>EN</language>
  <locale>en_US</locale>
</user>

同じことを JSON オブジェクトで行う場合は以下のようにします。

{ "user":
  { "userid":"billtester@test.com",
    "name":"Bill Tester",
    "first_name":"Bill",
    "last_name":"Tester",
    "roles":[
        {"uri":"/roles/ro53"}],
    "language":"EN",
    "locale":"en_US"
  }
}

これで、管理者ロールを持つ新しいユーザーを作成するための cURL コマンドを作成することができます。以下のコマンドは XML を使用しています。

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<user><userid>billtester@test.com</userid><name>Bill Tester</name><first_name>Bill
</first_name><last_name>Tester</last_name><roles><role uri=\"/roles/53\"/></roles>
<language>EN</language><locale>en_US</locale></user>" https://endpoint_URL/users

あるいは、以下のように JSON を使用することもできます。

curl -k -u johntester@test.com:johnspasswd -X POST -H "ContentType:application/json" 
-d "{\"user\":{\"userid\":\"billtester@test.com \",\"name\":\"Bill Tester\",
\"first_name\":\"Bill\",\"last_name\": \"Tester\",\"roles\":[{\"uri\":\"/roles/53\"}],
\"language\":\"EN\",\"locale\":\"en_US\"}}" https://endpoint_URL/users

こうしたリクエストを実行しても、SmarterCloud Enterprise+ から即座にレスポンスが返されるわけではありません。ユーザーを作成するジョブが開始され、リクエストを実行したユーザーにはジョブの進行状況が e-メールで通知されます。

チームを作成する

参加するすべてのユーザーを作成した後、SmarterCloud Enterprise+ のチームを作成する必要があります。まず、オンボード・プロセスで与えられる LOB (Line of Business) ID を知る必要があります。そのためには以下のコマンドを実行します。

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/lobs

この例では ID が 8888 であるとします。次に、以下のように空のチームを作成します。

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<team><name>Test Team</name><description>Project XYZ Test Team</description><lob uri=
\"/lobs/8888\"/></team>" https://endpoint_URL/teams

最後に、この空のチームにユーザーの配列を追加します。以下の例ではチーム ID が 9999、ユーザー ID が 100110021003 です。

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<team><name>Test Team 1</name><description>Project XYZ Test Team</description><lob uri=
\"/lobs/8888\"/><users>[{\"uri\":\"/users/1001\"}{\"uri\":\"/users/1002\"}{\"uri\":\
"/users/1003\"}]</users></team>" https://endpoint_URL/teams/9999

プロジェクトを作成する

これで、SmarterCloud Enterprise+ のプロジェクトを作成する準備が整いました。プロジェクトは管理の単位であり、プロジェクトに SmarterCloud Enterprise+ サーバーを関連付ける必要があります。プロジェクトを作成するには、サーバー・インスタンスを保持するコンテナーであるグループを作成します。以下の例では、チームの URL が team という名前のオプションの値として指定されています。

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<group><name>Project XYZ</name><description>Project XYZ Description</description>
<options><option><name>team</name><value><team uri=\"/teams/9999\"/></value></option>
</options></group>" https://endpoint_URL/groups

サーバー・インスタンスを作成する

これで、SmarterCloud Enterprise+ サーバーをインスタンス化する準備が整ったので、以下の項目の ID を確定するために REST の GET コマンドを実行します。

  • 仮想マシンの構成
  • イメージ
  • プロジェクト (グループ)
  • セキュリティー・ゾーン
  • サービス・レベル・アグリーメント
  • パッチ・スケジュール・カテゴリー

これらの ID を入手したら、目的のインスタンスを表す XML (または JSON) 要素を指定し、その要素を cURL コマンドに含め、以下のようにインスタンスを作成することができます。

curl -k -u johntester@test.com:johnspasswd -X POST -H "Content-Type:application/xml" -d 
"<instance><vm_configuration>/vm_configurations/2</vm_configuration><image uri=
\"/images/1033\"/><options><option><name>group</name><value><group uri=\"/groups/638\"/>
</value></option><option><name>security_zone</name><value><security_zone uri=
\"/security_zones/130\"/></value></option><option><name>sla</name><value><sla uri=
\"/slas/135\"/></value></option><option><name>patch_schedule_category</name><value>
<patch_schedule_category uri=\"/patch_schedule_categories/150\"/></value></option>
</options></instance>" https://endpoint_URL/instances

上記の cURL コマンドによってインスタンス作成ジョブが開始されます。以下のコマンドを実行すると、ジョブのステータスを問い合わせることができます。

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/jobs

上記の jobs コマンドに対するレスポンスから、最近実行されたすべての johntester ジョブのステータスを知ることができます。特定のジョブの ID を取得した場合には、コマンド内でその ID を指定することにより、そのジョブの詳細を取得することができます。以下の例では、ジョブの ID が 1234 であると仮定しています。

curl -k -X GET -u johntester@test.com:johnspasswd https://endpoint_URL/jobs/1234

サーバー・インスタンスを構成する

インスタンスが起動して実行状態になると、許容される制限の範囲内でインスタンスの構成を変更することができます。例えば、ディスクを追加することができます。以下の例ではインスタンスの ID が 3456 であると仮定しています。

curl -k -u johntester@test.com:johnspasswd -X PUT -H "Content-Type:application/xml" -d 
"<instance><disks><disk><name>disk1</name><size>64</size><options><option>
<name>type</name><value>additional</value></option></options></disk></disks></instance>" 
https://endpoint_URL/instances/3456

インスタンスを削除する

インスタンスが不要になった場合 (例えば、テストが完了した後など) には、そのインスタンスを以下のコマンドで削除することができます。

curl -k -u johntester@test.com:johnspasswd -X DELETE  https:// endpoint_URL/3456

まとめ

この記事では、SmarterCloud Enterprise+ の API を使用して SmarterCloud Enterprise+ の管理タスクをプログラムで実行する方法について説明しました。

SmarterCloud Enterprise+ の API は、他の IBM クラウド・オファリング (SCE (SmarterCloud Enterprise) など) とは以下のような点で異なっています。

  • SmarterCloud Enterprise+ の API の機能の範囲は、他のクラウド・オファリングよりも限定されています。これは、高度に管理されたクラウド環境によって一部のユーザー・アクションが許可されないという、SmarterCloud Enterprise+ の管理された性質のためです。例えば、最新の SmarterCloud Enterprise+ リリースにはプライベート・イメージ・カタログが存在しません。
  • 作成リクエストや更新リクエストは数分では完了せず、数時間から数日間もかかる場合があります。これはそうしたリクエストに応じてモニター・インフラストラクチャーを作成または更新する必要があるためです。これらのタスクを行うために、SmarterCloud Enterprise+ はジョブを作成します。API 呼び出しを実行したユーザーには、そのユーザーが登録した e-メール・アドレスにジョブの進行状況や完了を通知するメッセージが送信されます。
  • ユーザーに Customer Administrator ロールが割り当てられている場合、そのユーザーが実行するリクエストを、そのユーザーの Customer Business Manager が承認しなければならない場合があります。特に、リソース使用量が増加するリクエスト (仮想サーバーの作成や変更など) については、そのユーザーの Customer Business Manager による承認が必要となります。

参考文献

学ぶために

議論するために

  • developerWorks コミュニティーに参加してください。ここでは他の developerWorks ユーザーとのつながりを持てる他、開発者によるブログ、フォーラム、グループ、Wiki を調べることができます。

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Cloud computing
ArticleID=961873
ArticleTitle=IBM SmarterCloud Enterprise+ のサービスをプログラムで呼び出す
publish-date=02132014