この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章は、次の項で構成されています。
認証は との XML API の交換を可能にします。認証を使用すると、権限を設定し、実行できる操作を制御できます。
(注) | このマニュアルのほとんどのコード例では、用語 <real_cookie> は 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf などの実際の Cookie に置き換えられます。Cisco UCS の Cookie は 47 文字の文字列です。これは、セッション情報を維持するために Web ブラウザがローカルに保存する Cookie とは種類が異なります。 |
ログインするために、XML API クライアントは Cisco UCS Central HTTPS サーバへの TCP 接続を確立し、aaaLogin メソッドを格納している XML ドキュメントを URL(https://<UCSCENTRALIP>/xmlIM/)へポストします。
次に、クライアントは aaaLogin メソッドを指定し、ユーザ名とパスワードを提供します。
<aaaLogin inName="admin" inPassword="password" />
(注) | XML API ドキュメントに XML バージョンまたは DOCTYPE の行を含めないでください。inName 属性と inPassword 属性はパラメータです。 |
各 XML API ドキュメントは、実行する操作を表します。要求が XML API ドキュメントとして受け取られると、Cisco UCS は要求を読み取り、メソッドで指定されているアクションを実行します。Cisco UCS は、XML ドキュメント形式のメッセージで応答し、要求の成否を示します。
次に、一般的な成功応答を示します。
1 <aaaLogin 2 response="yes" 3 outCookie="<real_cookie>" 4 outRefreshPeriod="600" 5 outPriv="aaa,ext-lan-policy,ext-lan-qos,ext-san-policy,operations, pod-policy,pod-qos,read-only" 6 outDomains="mgmt02-dummy" 7 outChannel="noencssl" 8 outEvtChannel="noencssl"> 9 </aaaLogin>
応答の各行は、次のように解釈されます。
ログインに使用するメソッドを指定します。
これが応答であることを確認します。
セッションの Cookie を提供します。
推奨される Cookie のリフレッシュ間隔を指定します。デフォルトのログイン セッションの長さは 600 秒です。
ユーザ アカウントに割り当てられる権限レベルを指定します。
outDomains 値は mgmt02-dummy です。
noencssl の outChannel 値は、このセッションが SSL を介した暗号化を使用していないことを宣言します。
noencssl の outEvtChannel 値は、すべてのイベント サブスクリプションで SSL を介した暗号化を使用していないことを宣言します。
終了タグ。
また、XML API へのログインに cURL ユーティリティを使用できます。次の例に示すように、cURL コマンドで HTTPS を使用する必要があります。
curl -d "<aaaLogin inName='admin' inPassword='password'></aaaLogin>" https://192.0.20.72/xmlIM/
セッションは、aaaLogin 応答または以前の更新から取得された 47 文字の Cookie を使用して、aaaRefresh メソッドで更新されます。
<aaaRefresh inName="admin" inPassword="mypasword" inCookie="real_cookie"/>
セッションからログアウトするには、次のメソッドを使用します。
<aaaLogout inCookie="<real_cookie>" />
失敗したログイン:
<aaaLogin response="yes" cookie="<real_cookie>" errorCode="551" invocationResult="unidentified-fail" errorDescr="Authentication failed"> </aaaLogin>
存在しないオブジェクト(空白が返される場合は、指定した DN オブジェクトが存在しないことを示します):
<configResolveDn dn="sys-machine/chassis-1/blade-4711“ cookie="<real_cookie>“ response="yes"> <outConfig> </outConfig> </configResolveDn>
不正な要求:
<configConfMo dn="fabric/server“ cookie="<real_cookie>“ response="yes“ errorCode="103“ invocationResult="unidentified-fail“ errorDescr="can't create; object already exists."> </configConfMo>
クエリー メソッド
MIT の子オブジェクトの解決時に、次のことに注意してください。
このメソッドが、名前付きクラスのインスタンスである名前付きオブジェクトのすべての子オブジェクトを取得している。クラス名を省略すると、名前付きオブジェクトのすべての子オブジェクトが返されます。
inDn 属性により、子オブジェクトが取得される名前付きオブジェクトが指定されている(必須)。
classId 属性により、返される子オブジェクト クラスの名前が指定されている(任意)。
認証 Cookie(aaaLogin または aaaRefresh から)が必須である。
inHierarchical 属性(デフォルト値は false)が true の場合は、結果が階層形式であることが指定されている。
列挙値、classIds、およびビット マスクが文字列として表示されている。
configResolveChildrenに示す要求または応答の例を参照してください。
クラスの解決時には、次のことに注意してください。
指定したクラス タイプのすべてのオブジェクトが取得されている。
classId が、返されるオブジェクト クラスの名前を指定している(必須)。
認証 Cookie(aaaLogin または aaaRefresh から)が必須である。
inHierarchical 属性(デフォルト値は false)が true の場合は、結果が階層形式であることが指定されている。
列挙値、classIds、およびビット マスクが文字列として表示されている。
結果セットは大きくなることがあります。結果セットは正確に定義してください。たとえば、サーバのリストだけを取得する場合は、クエリーで classId の属性値として computeItem を使用します。装置のすべてのインスタンスを取得するには、equipmentItem クラスを問い合わせます。この例は、equipmentItem クラスのすべてのインスタンスについて問い合わせます。
<configResolveClass cookie="real_cookie" inHierarchical="false" classId="equipmentItem"/>
configResolveClassに示す要求または応答の例を参照してください。
複数のクラスの解決時には、次のことに注意してください。
このメソッドが、指定したクラス タイプのすべてのオブジェクトを取得している。
classId 属性により、返されるオブジェクト クラスの名前が指定されている(必須)。
認証 Cookie(aaaLogin または aaaRefresh から)が必須である。
inHierarchical 属性(デフォルト値は false)が true の場合は、結果が階層形式であることが指定されている。
列挙値、classIds、およびビット マスクが文字列として表示されている。
無効なクラス名が inId 属性で指定された場合は、XML 解析エラーが生成され、クエリーは実行できません。
configResolveClassesに示す要求または応答の例を参照してください。
DN を解決するときは、次のことに注意してください。
DN により指定されたオブジェクトが取得されている。
指定された DN が、解決するオブジェクト インスタンスを識別している(必須)。
認証 Cookie(aaaLogin または aaaRefresh から)が必須である。
inHierarchical 属性(デフォルト値は false)が true の場合は、結果が階層形式であることが指定されている。
列挙値、classIds、およびビット マスクが文字列として表示されている。
configResolveDnに示す要求または応答の例を参照してください。
複数の DN を解決するときは、次のことに注意してください。
DN により指定されたオブジェクトが取得されている。
指定された DN が、解決するオブジェクト インスタンスを識別している(必須)。
認証 Cookie(aaaLogin または aaaRefresh から)が必須である。
inHierarchical 属性(デフォルト値は false)が true の場合は、結果が階層形式であることが指定されている。
列挙値、classIds、およびビット マスクが文字列として表示されている。
要求の順序によって応答の順序が決まるわけではない。
未知の DN が、outUnresolved 要素の一部として返されている。
configResolveDnsに示す要求または応答の例を参照してください。
オブジェクトの親オブジェクトの解決時に、次のことに注意してください。
このメソッドが、指定 DN の親オブジェクトを取得している。
dn 属性が子オブジェクトの DN である(必須)。
認証 Cookie(aaaLogin または aaaRefresh から)が必須である。
inHierarchical 属性(デフォルト値は false)が true の場合は、結果が階層形式であることが指定されている。
列挙値、classIds、およびビット マスクが文字列として表示されている。
configResolveParentに示す要求または応答の例を参照してください。
クエリーのスコープを制限すると、粒度が細かくリソースを大量に消費しない要求を実現できます。クエリーは、管理情報ツリーでルート以外の場所に固定できます。クエリー スコープの設定時に、次のことに注意してください。
このメソッドが、指定された DN にクエリーのルート(スコープ)を設定し、指定されたクラス タイプのオブジェクトを返す。
dn が、クエリーのスコープが設定された名前付きオブジェクトである(必須)。
inClass 属性が、返されるオブジェクト クラスの名前を指定している(任意。クラスを指定しないと、クエリーは configResolveDn と同様に動作します)。
認証 Cookie(aaaLogin または aaaRefresh から)が必須である。
inHierarchical 属性(デフォルト値は false)が true の場合は、結果が階層形式であることが指定されている。
列挙値、classIds、およびビット マスクが文字列として表示されている。
次は、シャーシ 1 のブレードのイーサネット インターフェイスに対するクエリーの例を示します。
<configScope dn="sys/chassis-1" inClass="adaptorExtEthIf" cookie="<real_cookie>" inHierarchical="false"/>
configScopeに示す要求または応答の例も参照してください。
すべての MAC アドレスのリストを取得するには、macpoolAddr に照会します。これらは、(システムが作成した)macpoolUniverse の子です。要求は次のとおりです。
<configScope cookie="<real_cookie>" inHierarchical="false" dn="mac" inClass="macpoolAddr"/>
応答は次のとおりです。
<?xml version="1.0" encoding="UTF-8"?> <configScope cookie="<real_cookie>" dn="mac" response="yes"> <outConfigs> <macpoolAddr assigned="no" assignedToDn="" dn="mac/00:00:00:00:FF:0F" id="00:00:00:00:FF:0F" owner="pool"> </macpoolAddr> <macpoolAddr assigned="no" assignedToDn="" dn="mac/00:00:00:00:FF:0E" id="00:00:00:00:FF:0E" owner="pool"> </macpoolAddr> . . . <\outconfig <\configScope
macpoolAddr クラスのオブジェクトは、MAC プール ユニバースの子としてのみ存在できるため、より簡単なクエリーは次のようになります。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="macpoolAddr"/>
どの computeItem(ブレードまたはラック マウント サーバ)に特定の MAC アドレスが割り当てられるかを判断するには、クエリーに MAC アドレスを指定し、応答の assignedToDn フィールドを確認します。次に、MAC アドレスを指定した要求の例を示します。
<configResolveDn cookie="<real_cookie>" inHierarchical="false" dn="mac/10:00:00:00:00:03"/>
応答は次のとおりです。
<configResolveDn dn="mac/10:00:00:00:00:03" cookie="real_cookie" response="yes"> <outConfig> <macpoolAddr assigned="yes" assignedToDn="org-root/ls-BOB/ether-eth1" dn="mac/10:00:00:00:00:03" id="10:00:00:00:00:03" owner="pool" /> </outConfig> </configResolveDn>
次に、重大な(メジャー)障害のリストを取得する例を示します。
<configResolveClass cookie="real_cookie" inHierarchical="false" classId="faultInst"/>
次に、すべての重大な障害(メジャーおよびクリティカル)のリストを取得する例を示します(フィルタ <inFilter>eq class= “faultInst” を含む)。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="faultInst"> <inFilter> <eq class="faultInst" property="highestSeverity" value="major" /> </inFilter> </configResolveClass>
フィルタの使用
Simple フィルタは、プロパティの true および false 条件を使用して結果を選択します。
false の例:
<configResolveClass cookie="<real_cookie>" classId="topSystem" inHierarchical="false"> <inFilter> </inFilter> </configResolveClass>
true の例:
<configResolveClass cookie="<real_cookie>" classId="topSystem" inHierarchical="true"> <inFilter> </inFilter> </configResolveClass>
Property フィルタ
この例は、すべての関連するサーバのクエリーを示します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="lsServer"> <inFilter> <eq class="lsServer" property="assocState" value="associated" /> </inFilter> </configResolveClass>
この例は、すべての未割り当てサーバ(割り当て状態のプロパティが assigned と等しくない)を検索します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="lsServer"> <inFilter> <ne class="lsServer" property="assignState" value="assigned" /> </inFilter> </configResolveClass>
この例は、容量が 1024 MB より多いメモリ アレイを検索します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <gt class="memoryArray" property="currCapacity" value="1024" /> </inFilter> </configResolveClass>
この例は、容量が 2048 MB 以上のメモリ アレイを検索します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <ge class="memoryArray" property="currCapacity" value="2048" /> </inFilter> </configResolveClass>
この例は、容量が 1024 MB より少ないメモリ アレイを検索します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <lt class="memoryArray" property="currCapacity" value="1024" /> </inFilter> </configResolveClass>
この例は、容量が 2048 MB 以下のメモリ アレイを検索します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <le class="memoryArray" property="currCapacity" value="2048" /> </inFilter> </configResolveClass>
Wildcard フィルタは標準の正規表現構文を使用します。この例は、シリアル番号がプレフィックス QCI1 で始まるすべてのアダプタ ユニットを検索します。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="adaptorUnit"> <inFilter> <wcard class="adaptorUnit" property="serial" value="QCI1.*" /> </inFilter> </configResolveClass>
この例は、connStatus が A または B のいずれかであるすべてのサーバを検索します(プロパティ connStatus はビット マスクです)。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="null" inHierarchical="false" classId="computeItem"> <inFilter> <anybit class="computeItem" property="connStatus" value="A,B" /> </inFilter> </configResolveClass>
この例は、configQualifier ビット マスクが vnic-capacity および vhba-capacity の両方に設定されているすべてのサービス プロファイルを検索します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="lsServer"> <inFilter> <allbits class="lsServer" property="configQualifier" value="vnic-capacity,vhba-capacity" /> </inFilter> </configResolveClass>
Composite フィルタ
プールに割り当てられ、所有されているすべての UUID を判定するには、次のクエリーを実行します。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="uuidpoolAddr"> <inFilter> <and> <eq class="uuidpoolAddr" property="owner" value="pool" /> <eq class="uuidpoolAddr" property="assigned" value="yes" /> </and> </inFilter> </configResolveClass>
応答は次のとおりです。
<configResolveClass classId="uuidpoolAddr" cookie="<real_cookie>" response="yes"> <outConfigs> <uuidpoolAddr assigned="yes" assignedToDn="org-root/ls-foo" dn="uuid/F000-00000000000F" id="F000-00000000000F" owner="pool"> </uuidpoolAddr> </outConfigs> </configResolveClass>
この例で AND フィルタは、ベンダーが Cisco Systems Inc で、シリアル番号が CHS A04 のシャーシを検索します。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="equipmentChassis"> <inFilter> <and> <eq property="vendor" value="Cisco Systems Inc" class="equipmentChassis"/> <eq class="equipmentChassis" property="serial" value="CHS A04"/> </and> </inFilter> </configResolveClass>
この例は、すべてのシャーシのスロット 1 またはスロット 8 にある、タイプが computeItem のすべてのオブジェクトを返します。
<configResolveClass inHierarchical="false" cookie="<real_cookie>" classId="compute"> <inFilter> <or> <eq class="computeItem" property="slotId" value="1"/> <eq class="computeItem" property="slotId" value="8"/> </or> </inFilter> </configResolveClass>
この例は、スロット 1、2、3、4、または 5 が入力されたメモリ アレイを検索します(間の範囲は含まれることに注意してください)。フィルタは次のようにフレーム化されます。
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryarray"> <inFilter> <bw class="memoryArray" property="populated" firstValue="1" secondValue="5"/> </inFilter> </configResolveClass>
この例は、AND、OR、NOT の組み合わせです。これは、シャーシ 5 を除くすべてのシャーシのスロット 1 またはスロット 8 にある、computeItem タイプのオブジェクトをすべて返します。
<configResolveClass inHierarchical="false" cookie="<real_cookie>" classId="computeItem"> <inFilter> <and> <or> <eq class="computeItem" property="slotId" value="1"/> <eq class="computeItem" property="slotId" value="8"/> </or> <not> <eq class="computeItem" property="chassisId" value="5"/> </not> </and> </inFilter> </configResolveClass>
NOT フィルタは、含まれているフィルタの結果を逆にします。フィルタは次のようにフレーム化されます。この例は、不明な connStatus を持たないサーバを照会します(プロパティ connStatus はビット マスクです)。
<configResolveClass cookie="null" inHierarchical="false" classId="computeItem"> <inFilter> <not> <anybit class="computeItem" property="connStatus" value="unknown" /> </not> </inFilter> </configResolveClass>