Cisco CIMC XML API
Cisco CIMC XML API

Cisco CIMC XML API

この章は、次の項で構成されています。

Cisco CIMC XML API について

Cisco Integrated Management Controller(CIMC)XML API は、E シリーズ サーバの CIMC へのプログラム インターフェイスです。 この API は、HTTP または HTTPS 経由で XML ドキュメントを受け取ります。 開発者は、任意のプログラミング言語を使用して API メソッドを含む XML ドキュメントを生成できます。 CIMC の設定およびステータス情報は、XML API を介して完全にアクセスできる、管理情報ツリーと呼ばれる階層ツリー構造に格納されます。

Cisco CIMC XML API には、Cisco UCS Manager XML API で使用可能なメソッドおよび管理情報モデルのサブセットが実装されています。 両方の API の動作は構文およびセマンティクスの面で似ており、両方で同じクライアント開発ツールおよび技術を使用できます。 Cisco CIMC XML API の範囲は 1 台の E シリーズ サーバに限定されています。これに対して Cisco UCS Manager XML API は、スイッチ、FEX モジュール、サーバなどのデバイスで構成される UCS 環境全体を制御します。

Cisco CIMC XML API を使用すれば、CIMC にプログラム アクセスして、サーバを構成、管理、モニタできます。 この API には、CIMC CLI および GUI インターフェイス経由でアクセスできる同じ機能があります。

API の動作はトランザクション型で、CIMC で保持される単一のデータ モデルで終了します。

API モデルには、次のプログラマチック エンティティが含まれます。

  • クラス:管理情報ツリーのオブジェクトのプロパティおよび状態を定義します。
  • メソッド:1 つまたは複数のオブジェクトに対して API が実行するアクションです。
  • タイプ:オブジェクト ステート(たとえば、equipmentPresence)に値をマッピングするオブジェクトのプロパティです。

一般的な要求は CIMC に着信し、FIFO 順にトランザクタ キューに配置されます。 トランザクタはこのキューから要求を取得し、要求を解釈して認可チェックを実行します。 要求が確認されると、トランザクタは管理情報ツリーを更新します。 このすべての動作は、1 つのトランザクションで行われます。

イベント サブスクリプションがサポートされます。 最大で 4 台の Cisco CIMC XML API クライアントが CIMC からイベント通知の受信を登録できます。 イベント サブスクリプション操作によって接続セッションが確立され、CIMC によって非同期的に送信される XML 形式のイベント通知メッセージをクライアントが受信できるようになります。


(注)  


Cisco CIMC XML API が送信するイベント通知は、エラー関連のイベントに限られます。


Cisco UCS E シリーズ サーバ管理情報モデル

Cisco UCS E シリーズ サーバを構成するすべての物理および論理コンポーネントは、管理情報ツリーと呼ばれる階層型管理情報モデルで表されます。 このツリー内の各ノードは、管理ステータスと動作ステータスを含む、管理対象オブジェクト(MO)またはオブジェクトのグループを表します。

階層構造は最上部(sys)から始まり、親ノードと子ノードを含みます。 このツリー内の各ノードは管理対象オブジェクトであり、Cisco UCS 内の各オブジェクトは、オブジェクトとツリー内の位置を示す一意の識別名(DN)を持ちます。 管理対象オブジェクトは、CPU、DIMM、アダプタ カード、ファン、電源装置などの Cisco UCS リソースを抽象化したものです。

設定ポリシーは、システム内のポリシーの大半を占め、さまざまな Cisco UCS コンポーネントの設定を説明します。 ポリシーは、ある環境下でシステムがどのように動作するかを決定します。 特定の管理対象オブジェクトはユーザが作成せず、自動的に Cisco UCS によって作成されます(電源オブジェクトやファン オブジェクトなど)。 API を起動することによって、管理情報モデル(MIM)にオブジェクトの読み取りと書き込みを行います。

CIMC 管理情報モデル

CIMC 管理情報モデルは、Cisco UCS 管理情報モデルのサブセットです。 E シリーズ サーバは、次の例のように管理情報ツリーの sys/rack-unit-1 からモデル化されています。

|——sys———————————––– (sys)
     |——rack-unit-1————————(sys/rack-unit-1)
          |——adaptor-1————————(sys/rack-unit-1/adaptor-1)
          |——indicator-led-1————————(sys/rack-unit-1/indicator-led-1)
          |——indicator-led-2————————(sys/rack-unit-1/indicator-led-2)

Cisco CIMC XML API サンプル フロー

一般的な要求は CIMC に着信し、FIFO 順にトランザクタ キューに配置されます。 トランザクタはこのキューから要求を取得し、要求を解釈して認可チェックを実行します。 要求が確認されると、トランザクタは管理情報ツリーを更新します。 このプロセスは、単一のトランザクションで実行されます。

次の図に、CIMC がサーバの起動要求をどのように処理するかを示し、それに続く表に、サーバの起動要求に含まれる手順を示します。

図 1. サーバの起動要求のサンプル フロー



表 1  サーバの起動要求の説明

ステップ

コマンド/プロセス

MO(サーバ)の動作上の電源状態

1

CMD 要求:サーバの起動

Down

2

要求をキューに投入

Down

3

管理情報ツリーでのステートの変更

Down

4

管理対象オブジェクト(MO)のステート変更の永続化

Down

5

ブート スティミュラスの適用

Up

オブジェクトの命名

特定のオブジェクトは、識別名(DN)または相対名(RN)で識別できます。

識別名

識別名を使用すると、明確にターゲット オブジェクトを識別することができます。 識別名は、一連の相対名から構成される次の形式を持ちます。

dn = {rn}/{rn}/{rn}/{rn}...

次の例で DN は、オブジェクト ツリーの最上位からオブジェクトまで、adaptor-1 の完全修飾パスを提供します。 DN は、API コールが動作する管理対象オブジェクトを指定します。

< dn =”sys/rack-unit-1/adaptor-1” />

相対名

相対名は、親オブジェクトのコンテキスト内でオブジェクトを識別します。 識別名は、一連の相対名で構成されます。

次の識別名を例にします。

<dn = "sys/rack-unit-1/adaptor-1/host-eth-2"/>

これは、次の相対名で構成されます。

topSystem MO: rn="sys"
computeRackUnit MO: rn ="rack-unit-1"
adaptorUnit MO: rn="adaptor-<id>"
adaptorHostEthIf MO: rn="host-eth-<id>"

API メソッド カテゴリ

各メソッドは XML ドキュメントに対応します。


(注)  


このマニュアルのいくつかのコード例では、用語 <real_cookie> は 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf などの実際の Cookie に置き換えられます。 XML API の Cookie は 47 文字の文字列です。これは、セッション情報を維持するために Web ブラウザがローカルに保存する Cookie とは種類が異なります。


認証方法

認証メソッドは、アクティブ セッションを開始し、維持します。 他の API コールが許可される前に、正常な認証 Cookie がシステムによって返される必要があります。

セッションを認証するには、次のメソッドを使用します。

  • aaaLogin:成功した場合は、セッションを初期化し認証 Cookie を返します。 Cookie は、600 秒(10 分)の間有効で、期限が切れないようにするためにセッション期間中に更新する必要があります。 CIMC に対して一度に最大 4 個のセッションを開くことができます。
  • aaaRefresh:以前にアクティブなセッションの代わりに新しいセッションを作成します。 新しいセッションが作成されると、新しい認証 Cookie が返されます。
  • aaaKeepAlive:セッションを維持し、認証 Cookie を再び 600 秒間アクティブなままにします。
  • aaaLogout:現在のセッションを終了し、対応する認証 Cookie を非アクティブ化します。

操作は、TCP で HTTP の post メソッドを使用して実行されます(CIMC は HTTP 要求と HTTPS 要求の両方をサポートします)。 HTTP および HTTPS が別のポート番号を使用するように設定できますが、TCP/80(またはセキュア接続用に TCP/443)がデフォルトで使用されます。 HTTP のエンベローブには XML の設定が含まれます。


ヒント


CIMC では、HTTP から HTTPS へのリダイレクトはデフォルトでイネーブルです。 クライアント アプリケーションと CIMC の間の HTTP パケットをキャプチャするには、CIMC GUI または CLI でリダイレクトをディセーブルにします。


クエリー メソッド

クエリー メソッドは、オブジェクトの現在の設定状態情報を取得します。 次のクエリー メソッドがサポートされています。

  • configResolveDn:DN によりオブジェクトを取得します。
  • configResolveClass:該当するクラスのオブジェクトを取得します。
  • configResolveChildren:オブジェクトの子オブジェクトを取得します。
  • configResolveParent:オブジェクトの親オブジェクトを取得します。

ほとんどのクエリー メソッドは、引数 inHierarchical(ブール値 true/yes または false/no)を持ちます。 true の場合、inHierarchical 引数はすべての子オブジェクトを返します。

<configResolveDn … inHierarchical="false"></>
<configResolveDn … inHierarchical="true"></>

CIMC から返されるデータ量は非常に大きいことがあるため、inHierarchical 引数は慎重に使用してください。 たとえば、クエリー メソッドが、管理情報ツリーの上部にある管理対象オブジェクト(MO)を参照するクラスまたは DN で使われていて、inHierarchical が true に設定されている場合、応答には CIMC の設定全体のほとんどが含まれる可能性があります。 CIMC が要求を処理するために必要なリソースが多くなると、CIMC の応答にかかる時間がそれだけ長くなります。 遅延を回避するには、クエリー メソッドを少数の MO に関連する小さな規模で実行する必要があります。


ヒント


クエリー メソッドが応答しない、または応答に時間がかかる場合は、クライアント アプリケーションのタイムアウト期間を長くするか、関連する MO の数を減らすようにクエリー メソッドを調整します。


クエリーの API メソッドには、コールを再帰的にするかどうかを指定するために inRecursive 引数が含まれる場合があります(他のオブジェクトまたは親オブジェクトをポイントし返す場合など)。

この API は、クエリー メソッドの有用性を高めるためにフィルタ セットを提供します。 これらのフィルタは、クエリーの一部として渡すことができ、必要な結果セットを特定するために使用されます。


(注)  


inRecursive 引数およびクエリー フィルタはサポートされていないため、指定しても無視されます。



(注)  


ホストの電源が少なくとも 1 回投入されるまでに、CIMC はインベントリおよびステータス情報の取得を完了していない場合があります。 たとえば、CIMC がリセットされた場合は、ホストの電源が次にオンになるまで、CPU、メモリ、またはアダプタの詳細なインベントリ情報は取得されません。 使用できないデータに対応する MO でクエリー メソッドが実行された場合、応答は空白になります。


設定メソッド

CIMC では、管理対象オブジェクトの設定変更を行うために単一のメソッドのみがサポートされます。

  • configConfMo:管理情報ツリーの 1 つの管理対象オブジェクト(たとえば、DN)に影響します。

イベント サブスクリプション メソッド

アプリケーションは、通常のポーリングまたはイベント サブスクリプションによってステート変更に関する情報を取得します。 リソースをより効率的に使うために、イベント サブスクリプションは通知に最適な方法です。 ポーリングは非常に限定的な状況にある場合だけ使用してください。

次の例に示すように、イベントに対して登録するために eventSubscribe を使用します。

<eventSubscribe 
    cookie="<real_cookie>">
</eventSubscribe>

通知を受信するには、TCP 上で HTTP または HTTPS セッションを開き、このセッションを開いたままにします。 eventSubscribe の受信時に、CIMC は新しいイベントが発生すると、それらすべての送信を開始します。

各イベントは一意のイベント ID を持ちます。 イベント ID はカウンタとして動作し、すべてのメソッドの応答に含まれます。 イベントが生成されると、イベント ID カウンタが増加し、新しいイベント ID が割り当てられます。 このシーケンス番号により、イベントの追跡が可能になり、イベントを見逃すことがなくなります。

ユーザが開始したイベント チャネル接続は、イベント チャネル セッションの Cookie に関連付けられた非アクティビティが 600 秒経過してから、CIMC によって自動的に切断されます。 イベント チャネル接続が CIMC によって自動的に閉じられることを防ぐには、ユーザは 600 秒以内に同じイベント チャネル セッション Cookie に対して aaaKeepAlive 要求を送信するか、または同じイベント チャネル セッション Cookie を使用して CIMC に他の XML API メソッドを送信する必要があります。


(注)  


Cisco CIMC XML API が送信するイベント通知は、エラー関連のイベントに限られます。


成功または失敗の応答

CIMC が XML API 要求に応答する際、要求が完了できない場合に応答は失敗を示します。 成功の応答は、要求が有効かどうかだけを示し、操作が完了したことは示しません。 たとえば、電源投入の要求をサーバが完了するには時間がかかることがあります。 電源状態は、サーバの電源が実際に投入されてからのみダウンからアップに変更されます。

成功した要求

要求が正常に実行されると、CIMC は要求された情報または変更が行われたことの確認を含む XML ドキュメントを返します。 次に、識別名 sys/rack-unit-1/mgmt に対する configResolveDn クエリーの例を示します。

<configResolveDn 
				cookie="<real_cookie>" 
				inHierarchical="false"
				dn="sys/rack-unit-1/mgmt"/>

応答には次の情報が含まれます。

<configResolveDn 
				cookie="<real_cookie>" 
				response="yes"
				dn="sys/rack-unit-1/mgmt"> <outConfig> <mgmtController 
				dn="sys/rack-unit-1/mgmt" 
				model="UCS-E160DP-M1/K9" 
				serial="FHH16150031"
				subject="blade" 
				vendor="Cisco Systems Inc" ></mgmtController></outConfig> </configResolveDn>

失敗した要求

失敗した要求への応答には、errorCode および errorDescr の XML 属性が含まれます。 次に、失敗した要求に対する応答の例を示します。

<configConfMo dn="sys/rack-unit-1/adaptor-1/ext-eth-0"
     cookie="<real_cookie>"
     response="yes"
     errorCode="103"
     invocationResult="unidentified-fail"
     errorDescr="can't create; object already exists.">
</configConfMo>

空の結果

存在しないオブジェクトに対するクエリー要求は、CIMC によって失敗として扱われません。 オブジェクトが存在しない場合、CIMC は成功メッセージを返しますが、XML ドキュメントには、要求されたオブジェクトが見つからなかったことを示すために空のデータ フィールド(<outConfig> </outConfig>)が含まれます。 次に、存在しないオブジェクトの識別名を解決する試みに対する応答の例を示します。

<configResolveDn
    cookie="<real_cookie>"
    response="yes"
    dn="sys/rack-unit-1/adaptor-9999">
    <outConfig>
    </outConfig>
				</configResolveDn>