この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章の内容は、次のとおりです。
Cisco IMC XML API は、C シリーズ ラックマウント サーバ 用のCisco Integrated Management Controller(Cisco IMC)ソフトウェアのプログラムのインターフェイスです。この API は、HTTP または HTTPS 経由で XML ドキュメントを受け取ります。開発者は、任意のプログラミング言語を使用して API メソッドを含む XML ドキュメントを生成できます。Cisco IMC の構成およびステータス情報は、XML API を介して完全にアクセスできる、管理情報ツリー(MIT)と呼ばれる階層ツリー構造に格納されます。
Cisco IMC XML API は、Cisco UCS Manager XML API で利用可能なメソッドのサブセットおよび管理情報モデルを実装します。両方の API の動作は構文およびセマンティクスの面で似ており、両方で同じクライアント開発ツールおよび技術を使用できます。Cisco IMC XML API の範囲は、Cisco UCS Manager XML API とは対照的に単一の C シリーズ ラックマウント サーバ に制限されており、スイッチ、FEX モジュール、サーバ、およびその他のデバイスで構成される Cisco UCS ドメイン 全体を制御します。
Cisco IMC XML API を使用して、ユーザはサーバを設定、管理、およびモニタするために Cisco IMC にプログラムでアクセスします。この API は、Cisco IMC CLI および GUI インターフェイスからアクセスできる機能の大部分を提供します。
API の動作はトランザクション型で、Cisco IMC で保持される単一のデータ モデルで終了します。
API モデルには、次のプログラマチック エンティティが含まれます。
クラス:MIT のオブジェクトのプロパティおよび状態を定義します。
メソッド:1 つまたは複数のオブジェクトに対して API が実行するアクションです。
タイプ:オブジェクト ステート(たとえば、equipmentPresence)に値をマッピングするオブジェクトのプロパティです。
一般的な要求は Cisco IMC に着信し、FIFO 順にトランザクタ キューに配置されます。トランザクタはこのキューから要求を取得し、要求を解釈して認可チェックを実行します。要求の確認後、トランザクタが MIT を更新します。このすべての動作は、1 つのトランザクションで行われます。
イベント サブスクリプションがサポートされます。最大で 4 つの Cisco IMC XML API クライアントが、Cisco IMC からのイベント通知を受信するようにサブスクライブできます。イベント サブスクリプション操作によって接続セッションが確立され、Cisco IMC によって非同期的に送信される XML 形式のイベント通知メッセージをクライアントが受信できるようになります。
(注) | リリース 1.5(1.x) では、Cisco IMC XML API はエラーに関連するイベントのみについてイベント通知を送信します。 |
Cisco UCS を構成するすべての物理および論理コンポーネントは、MIT とも呼ばれる階層型管理情報モデル(MIM)で表されます。このツリー内の各ノードは、管理ステータスと動作ステータスを含む、管理対象オブジェクト(MO)またはオブジェクトのグループを表します。
階層構造は最上部(sys)から始まり、親ノードと子ノードを含みます。このツリー内の各ノードは管理対象オブジェクトであり、Cisco UCS 内の各オブジェクトは、オブジェクトとツリー内の位置を示す一意の識別名(DN)を持ちます。管理対象オブジェクトはCPU、DIMM、アダプタ カード、ファン、および電源装置などの Cisco UCS リソースを抽象化したものです。
設定ポリシーは、システム内のポリシーの大半を占め、さまざまな Cisco UCS コンポーネントの設定を説明します。ポリシーは、ある環境下でシステムがどのように動作するかを決定します。特定の管理対象オブジェクトはユーザが作成せず、自動的に Cisco UCS によって作成されます(電源オブジェクトやファン オブジェクトなど)。API を起動することによって、MIM にオブジェクトの読み取りと書き込みを行います。
Cisco IMC 管理情報モデルは、Cisco UCS 管理情報モデルのサブセットです。C シリーズ ラックマウント サーバ は、次の例のように MIT の sys/rack-unit-1 からモデル化されています。
Tree (topRoot):—————————————-Distinguished Name: |——sys———————————––– (sys) |——rack-unit-1————————(sys/rack-unit-1) |——adaptor-1————————(sys/rack-unit-1/adaptor-1) |——psu-1————————(sys/rack-unit-1/psu-1) |——psu-2————————(sys/rack-unit-1/psu-2)
一般的な要求はCisco IMCに着信し、FIFO の順でトランザクタ キューに配置されます。トランザクタはこのキューから要求を取得し、要求を解釈して認可チェックを実行します。要求が確認されると、トランザクタは管理情報ツリーを更新します。このプロセスは、単一のトランザクションで実行されます。
次の図は、Cisco IMC がサーバの起動要求を処理する方法を示しています。その下の表に、サーバの起動要求に伴うステップを示します。
手順 |
コマンド/プロセス |
MO(サーバ)の動作上の電源状態 |
---|---|---|
1 |
CMD 要求:サーバの起動 |
ダウン |
2 |
要求をキューに投入 |
ダウン |
3 |
管理情報ツリーのステート変更および管理対象オブジェクト(MO)ステート変更の永続化 |
ダウン |
4 |
ブート スティミュラスの適用 |
アップ |
特定のオブジェクトは、識別名(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>"
各メソッドは XML ドキュメントに対応します。
(注) | このマニュアルのいくつかのコード例では、用語 <real_cookie> は 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf などの実際の Cookie に置き換えられます。XML API の Cookie は 47 文字の文字列です。これは、セッション情報を維持するために Web ブラウザがローカルに保存する Cookie とは種類が異なります。 |
認証方式は、セッションを認証して保持します。次に例を示します。
aaaLogin:ログインする最初のメソッドです。
aaaRefresh:現在の認証 Cookie を更新します。
aaaLogout:現在のセッションを終了し、対応する認証 Cookie を非アクティブ化します。
有効な Cookie を取得する場合は、aaaLogin メソッドを使用します。セッションを保持し、Cookie をアクティブに保つ場合は、aaaRefresh を使用します。セッションを終了(また、Cookie を無効化)する場合は、aaaLogout メソッドを使用します。Cisco UCS に対して一度に最大 4 個のセッションを開くことができます。
操作は、HTTP の post メソッドを使用して(Cisco IMC は HTTP 要求と HTTPS 要求の両方をサポートします)TCP で実行されます。HTTP および HTTPS が別のポート番号を使用するように設定できますが、TCP/443(または非セキュア接続の場合は TCP/80)がデフォルトで使用されます。HTTP のエンベローブには XML の設定が含まれます。
ヒント | Cisco IMC では、HTTP から HTTPS へのリダイレクトはデフォルトで有効です。クライアント アプリケーションと Cisco IMC の間の HTTP パケットをキャプチャするには、Cisco IMC GUI または CLI のリダイレクトを無効にします。 |
クエリー メソッドは、オブジェクトの現在の設定状態情報を取得します。以下に、クエリーのサポートされているメソッドを示します。
configResolveDn:DN によりオブジェクトを取得します。
configResolveClass:該当するクラスのオブジェクトを取得します。
configResolveChildren:オブジェクトの子オブジェクトを取得します。
configResolveParent:オブジェクトの親オブジェクトを取得します。
ほとんどのクエリー メソッドは、引数 inHierarchical(ブール値 true/yes または false/no)を持ちます。true の場合、inHierarchical 引数はすべての子オブジェクトを返します。
<configResolveDn … inHierarchical="false"></> <configResolveDn … inHierarchical="true"></>
Cisco IMC から返されるデータ量は非常に大きいことがあるため、inHierarchical 引数は慎重に使用してください。たとえば、クエリー メソッドが、管理情報ツリーの上部にある管理対象オブジェクト(MO)を参照するクラスまたは DN で使われていて、inHierarchical が true に設定されている場合、応答には Cisco IMC 構成のほぼすべてが含まれる可能性があります。Cisco IMC が要求を処理するために必要なリソースが多くなると、Cisco IMC が応答するまでにかかる時間が長くなります。遅延を回避するには、クエリー メソッドを少数の MO に関連する小さな規模で実行する必要があります。
ヒント | クエリー メソッドが応答しない、または応答に時間がかかる場合は、クライアント アプリケーションのタイムアウト期間を長くするか、関連する MO の数を減らすようにクエリー メソッドを調整します。 |
クエリーの API メソッドには、コールを再帰的にするかどうかを指定するために inRecursive 引数が含まれる場合があります(他のオブジェクトまたは親オブジェクトをポイントし返す場合など)。
(注) | ホストの電源が少なくとも 1 回投入されるまでに、Cisco IMC はインベントリおよびステータス情報の取得を完了していない場合があります。たとえば、Cisco IMC がリセットされた場合は、ホストの電源が次にオンになるまで、CPU、メモリ、またはアダプタの詳細なインベントリ情報は取得されません。使用できないデータに対応する MO でクエリー メソッドが実行された場合、応答は空白になります。 |
Cisco IMC XML API では、管理対象オブジェクトの設定変更を行うために単一のメソッドのみがサポートされます。
アプリケーションは、通常のポーリングまたはイベント サブスクリプションによってステート変更に関する情報を取得します。リソースをより効率的に使うために、イベント サブスクリプションは通知に最適な方法です。ポーリングは非常に限定的な状況にある場合だけ使用してください。
次の例に示すように、イベントに対して登録するために eventSubscribe を使用します。
<eventSubscribe cookie="<real_cookie>"> </eventSubscribe>
通知を受信するには、TCP 経由で HTTP または HTTPS セッションを開き、このセッションを開いたままにします。eventSubscribe を受信すると、 は新しく発生したすべてのイベントの送信を開始します。これらのイベントのサブスクリプションを解除するには、eventUnsubscribe メソッドを使用します。
各イベントは一意のイベント ID を持ちます。イベント ID はカウンタとして動作し、すべてのメソッドの応答に含まれます。イベントが生成されると、イベント ID カウンタが増加し、新しいイベント ID が割り当てられます。このシーケンス番号により、イベントの追跡が可能になり、イベントを見逃すことがなくなります。
ユーザが開始したイベント チャネル接続は、イベント チャネル セッションの Cookie に関連付けられた非アクティビティが 600 秒経過してから、 によって自動的に切断されます。イベント チャネル接続が によって自動的に閉じられることを防ぐには、ユーザは 600 秒以内に同じイベント チャネル セッション Cookie に対して aaaKeepAlive 要求を送信するか、または同じイベント チャネル セッション Cookie を使用して に他の XML API メソッドを送信する必要があります。
(注) | リリース 1.5(1.x) 以降では、Cisco IMC API はエラーに関連するイベントについてのみ、イベント通知を送信します。 |
が XML API 要求に応答する場合、応答は要求が完了できない場合に失敗を示します。成功の応答は、要求が有効かどうかだけを示し、操作が完了したことは示しません。たとえば、電源投入の要求をサーバが完了するには時間がかかることがあります。電源状態は、サーバの電源が実際に投入されてからのみダウンからアップに変更されます。
要求が正常に実行されると、Cisco IMC は要求された情報または変更が行われたことの確認を含む XML ドキュメントを返します。次に、識別名 sys/rack-unit-1/adaptor-2/ext-eth-0 に対する configResolveDn クエリーの例を示します。
<configResolveDn
dn="sys/rack-unit-1/adaptor-2/ext-eth-0"
cookie="<real_cookie>"
inHierarchical="false"/>
応答には次の情報が含まれます。
<configResolveDn cookie="<real_cookie>" response="yes" dn="sys/rack-unit-1/adaptor-2/ext-eth-0"> <outConfig> <adaptorExtEthIf id="0" ifType="physical" linkState="up" mac="00:22:BD:D6:42:DA" name="" operState="up" portId="0" purpose="general" transport="CE" type="" dn="sys/rack-unit-1/adaptor-2/ext-eth-0" > </adaptorExtEthIf> </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>
存在しないオブジェクトに対するクエリー要求は、Cisco IMC によって失敗として扱われません。オブジェクトが存在しない場合、Cisco IMC は成功メッセージを返しますが、要求されたオブジェクトが見つからなかったことを示すために、XML ドキュメントには空のデータ フィールド(<outConfig> </outConfig>)が含まれます。次に、存在しないラックマウント サーバの識別名を解決する試みに対する応答の例を示します。
<configResolveDn
cookie="<real_cookie>"
response="yes"
dn="sys/rack-unit-1/adaptor-9999">
<outConfig>
</outConfig>
</configResolveDn>