仮想ホストの一覧の取得

機能

次の条件をすべて満たす仮想ホストの一覧を取得します。仮想ホスト以外のITリソースは取得しません。

条件に一致した仮想ホストがJP1/ITRM上に登録されていない場合は,0件となります。

取得する項目を次の表に示します。

項目説明
リソースIDシステムで自動的に割り振られたリソースID。仮想ホストを一意に表す。
リソース名仮想ホストのリソース名。
リソース管理画面のリソース一覧エリアに表示される[リソース名]と同じリソース名を出力する。
ホスト名仮想ホストのホスト名。
[リソース編集]画面の[ホスト名]と同じホスト名を出力する。
電源状態※1仮想ホストの電源状態。
仮想ホストの状態によって,次の文字列を出力する。
  • ON
    ・仮想ホストの電源が入っていて,電源を操作中ではない。
    ・仮想ホストが仮想化ソフトウェアのCPUまたはメモリを使用している。
    ・仮想ホストの停止,または強制停止が完了していない。
  • OFF
    ・仮想ホストの電源が切れている。
    ・仮想ホストが起動する途中である。
  • ERROR
    ・仮想ホストに障害が発生している。
  • UNKNOWN
    ・ON,OFF,ERRORに当てはまらない。
    ・電源状態が不明である。
    ・電源状態を取得できなかった。
OS仮想ホスト上のOSの名称(ゲストOSが認識しているOSの名称)。
リソース管理画面のリソース一覧エリアに表示される[OS]と同じOS名を出力する。
予約IDシステムで自動的に割り振られた予約を示す値。
スケジュール画面の予約一覧エリアに表示される[予約ID]と同じ予約IDを出力する。
予約名予約名称。
スケジュール画面の予約一覧エリアに表示される[予約名]と同じ予約名を出力する。
業務グループIDシステムで自動的に割り振られた業務グループID。予約に対応する業務グループを一意に表す。
業務グループ名予約に対応する業務グループの名称。
スケジュール画面の予約一覧エリアに表示される[業務グループ]と同じ業務グループ名を出力する。
予約コメント予約に対応するコメント。
スケジュール画面の予約一覧エリアに表示される[コメント]と同じコメントを出力する。
個別予約期間名個別予約の期間名。
スケジュール画面の[すべて]タブに表示される[予約名]と同じ予約名を出力する。
個別予約開始日時個別予約の開始日時。
スケジュール画面の[すべて]タブに表示される[開始日時]と同じ日時を出力する。
個別予約終了日時個別予約の終了日時。
スケジュール画面の[すべて]タブに表示される[終了日時]と同じ日時を出力する。
システム情報へのリンク※2システム情報を取得するAPIへのリンクアドレス。
パフォーマンス情報へのリンク※2パフォーマンス情報を取得するAPIへのリンクアドレス。
ドライブ情報へのリンク※2ドライブ情報を取得するAPIへのリンクアドレス。
仮想ホスト操作へのリンク※2起動・停止・リブートするAPIへのリンクアドレス。
注※1
仮想ホストの電源状態は,次の契機で更新されます。
・設定画面の[監視間隔設定]エリアで[状態監視]を指定して仮想ホストを管理する仮想化ソフトウェアから稼働情報を収集したとき。
・設定画面の[管理リソース一覧]エリアで仮想ホストを管理する仮想化ソフトウェアから構成情報を再収集したとき。
・仮想ホストを操作するタスクが完了したとき。
なお,仮想ホストを管理する仮想化ソフトウェアが,監視停止の状態である場合,およびJP1/ITRMから仮想化ソフトウェアに通信できない状態である場合は,電源状態は更新されません。
注※2
リンクアドレス中のサーバを示す部分には,ユーザー設定プロパティファイル(jp1itrm.properties)のCO.ITRMServerURLキーで設定されたものが使用されます。詳細については,「ユーザー設定プロパティファイル(jp1itrm.properties)」(2. 定義ファイル)を参照してください。

 

参考
APIクライアントで個別予約開始日時を利用することで,利用期間が現在なのか未来なのかを確認できます。APIクライアントの利用者に,開始日時を連絡するかどうかの判断材料に利用してください。

 

APIのサポートバージョン

このAPIは,01.00以降で提供します。

HTTPリクエスト形式

仮想ホストの一覧を取得するAPIのHTTPリクエスト形式を次の表に示します。

項目
MethodGET
URI/jp1itrm/api/instances
Query Stringrealm=業務グループID
注※
リクエストに使用するURIおよびQuery Stringは,APIクライアントで生成するのではなく,業務グループ情報の一覧の取得で返却される「仮想ホストの一覧へのリンク」を使用してリクエストしてください。

HTTPステータスコード

200 OK,またはエラーを示すステータスコードが出力されます。

詳細については,「API共通の仕様」の「HTTPステータスコード」を参照してください。

XMLのネームスペース

HTTPステータスコードが,200 OKの場合,http://www.hitachi.co.jp/soft/xml/jp1/itrm/api/instancesを使用します。

XMLのスキーマ

仮想ホストの一覧を格納するスキーマを次の表に示します。

エレメント説明type出現回数
階層1階層2最小最大
instances仮想ホストの一覧。11
instance仮想ホストの情報。
条件に一致する仮想ホストがJP1/ITRM上に1つも登録されていない場合,このエレメントの個数は0となる。
この配下の情報については,「システム情報の取得」(4. API)の「XMLのスキーマ」を参照。
00以上の任意の数字
(凡例)
-:なし。

使用例

認証情報にユーザー名「portal01」,パスワード「password」を指定して,業務グループID「1」の仮想ホストの一覧を取得する場合の使用例を示します。

GET△/jp1itrm/api/instances?realm=1△HTTP/1.0
Authorization:△Basic△cG9ydGFsMDE6cGFzc3dvcmQwMQ==

(凡例) △:半角スペース

出力例

業務グループID「1」の仮想ホストの一覧を取得する場合の出力例を示します。

HTTP/1.1 200 OK
Content-Length: 1639
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<instances xmlns="http://www.hitachi.co.jp/soft/xml/jp1/itrm/api/instances">
<instance href="http://localhost:23505/jp1itrm/api/instances/1" id="1">
<name>VM001</name>
<hostname>HOST_01</hostname>
<state>ON</state>
<os>Microsoft Windows Server 2008 R2 Enterprise</os>
<reservations>
<reservation id="123" name="aaa" realm_id="456" realm_name="第一開発/1課/グループA" comment="ccc"
period_name="yoyaku"
start_time="2011-09-10T23:59:48.812Z" end_time="2011-09-10T23:59:48.812Z" />
<reservation id="777" name="bbb" realm_id="888" realm_name="第一開発/1課/グループB" comment="dd"
period_name="yoyaku2"
start_time="2011-09-10T23:59:48.812Z" end_time="2011-09-10T23:59:48.812Z" />
</reservations>
<performance href="http://localhost:23505/jp1itrm/api/instances/1/performances" />
<storage_volume href="http://localhost:23505/jp1itrm/api/instances/1/storage_volumes" />
<actions>
<link rel="start" method="post"
href="http://localhost:23505/jp1itrm/api/instances/1/start?realm=1" />
<link rel="stop" method="post"
href="http://localhost:23505/jp1itrm/api/instances/1/stop?realm=1" />
<link rel="powerOff" method="post"
href="http://localhost:23505/jp1itrm/api/instances/1/powerOff?realm=1" />
<link rel="reboot" method="post"
href="http://localhost:23505/jp1itrm/api/instances/1/reboot?realm=1" />
<link rel="reset" method="post"
href="http://localhost:23505/jp1itrm/api/instances/1/reset?realm=1" />
</actions>
</instance>
<instance href="http://localhost:23505/jp1itrm/api/instances/2" id="2">
<name>VM002</name>
:
</instance>
:
</instances>