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

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

Comments

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+ のリソース・モデルの説明
SmarterCloud Enterprise+ のリソース・モデルの説明

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

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

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

curl -k -X GET -u  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  -X POST -H "Content-Type:application/xml" -d 
"<user><userid></userid><name></name><first_name>
</first_name><last_name></last_name><roles><role uri=\"/roles/\"/></roles>
<language></language><locale></locale></user>" https://endpoint_URL/users

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

curl -k -u  -X POST -H "ContentType:application/json" 
-d "{\"user\":{\"userid\":\" \",\"name\":\"\",
\"first_name\":\"\",\"last_name\": \"\",\"roles\":[{\"uri\":\"/roles/\"}],
\"language\":\"\",\"locale\":\"\"}}" https://endpoint_URL/users

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

チームを作成する

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

curl -k -X GET -u  https://endpoint_URL/lobs

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

curl -k -u  -X POST -H "Content-Type:application/xml" -d 
"<team><name></name><description></description><lob uri=
\"/lobs/\"/></team>" https://endpoint_URL/teams

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

curl -k -u  -X POST -H "Content-Type:application/xml" -d 
"<team><name></name><description></description><lob uri=
\"/lobs/\"/><users>[{\"uri\":\"/users/\"}{\"uri\":\"/users/\"}{\"uri\":\
"/users/\"}]</users></team>" https://endpoint_URL/teams/

プロジェクトを作成する

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

curl -k -u  -X POST -H "Content-Type:application/xml" -d 
"<group><name></name><description></description>
<options><option><name>team</name><value><team uri=\"/teams/\"/></value></option>
</options></group>" https://endpoint_URL/groups

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

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

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

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

curl -k -u  -X POST -H "Content-Type:application/xml" -d 
"<instance><vm_configuration>/vm_configurations/</vm_configuration><image uri=
\"/images/\"/><options><option><name>group</name><value><group uri=\"/groups/\"/>
</value></option><option><name>security_zone</name><value><security_zone uri=
\"/security_zones/\"/></value></option><option><name>sla</name><value><sla uri=
\"/slas/\"/></value></option><option><name>patch_schedule_category</name><value>
<patch_schedule_category uri=\"/patch_schedule_categories/\"/></value></option>
</options></instance>" https://endpoint_URL/instances

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

curl -k -X GET -u  https://endpoint_URL/jobs

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

curl -k -X GET -u  https://endpoint_URL/jobs/

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

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

curl -k -u  -X PUT -H "Content-Type:application/xml" -d 
"<instance><disks><disk><name></name><size></size><options><option>
<name>type</name><value></value></option></options></disk></disks></instance>" 
https://endpoint_URL/instances/

インスタンスを削除する

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

curl -k -u  -X DELETE  https:// endpoint_URL/

まとめ

この記事では、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 による承認が必要となります。

ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

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