Cisco Virtual Network Management Center XML API リファレンス ガイド、リリース 1.2

認証方式

認証により、API は Cisco VNMC と対話できるようになります。また、認証を使用すると、権限を設定し、実行できる操作を制御できます。

（注） セッション Cookie は 47 文字の文字列であり、Web ブラウザがセッション情報を保持するためにローカルに保存する種類の Cookie ではありません。ほとんどのコード例では、<real_cookie> が 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf などの実際の Cookie の代わりに使用されています。

ここでは、次の内容について説明します。

• 「ログイン」

• 「セッションの更新」

• 「セッションからのログアウト」

• 「失敗したログインに対する応答」

ログイン

例 2-1 では、Linux POST コマンドで HTTPS を使用して Cisco VNMC に接続することにより認証要求を送信しています。

例 2-1 ログイン要求

（注） XML バージョンと DOCTYPES は、aaaLogin に含まれていません。これらを使用しないでください。inName 属性と inPassword 属性はパラメータです。

各 XML API ドキュメントは、実行する操作を表します。要求が XML API ドキュメントとして受け取られると、Cisco VNMC は要求を読み取り、メソッドで指定されているアクションを実行します。Cisco VNMC は、XML ドキュメント形式のメッセージで応答し、要求の成否を示します。

例 2-2 に、一般的な成功の応答を示します。

例 2-2 ログイン要求応答

（注） VNMC 1.0 イベント チャネルは HTTP を使用しています。そのため、暗号化されず、SSL を介して送信されません。

セッションの更新

セッションは、 aaaLogin 応答または以前の更新から取得された 47 文字の Cookie を使用して aaaRefresh メソッドで更新されます。

例 2-3 は、セッションを更新するメソッドです。

例 2-3 セッションの更新

セッションからのログアウト

例 2-4 は、セッションからログアウトするメソッドです。

例 2-4 セッションからのログアウト

失敗したログインに対する応答

例 2-5 は、失敗したログインに対する応答です。

例 2-5 失敗したログインに対する応答

情報収集用クエリー メソッド

クエリー メソッドは、階層、ステータス、およびスコープを含む情報を取得します。

ここでは、次の内容について説明します。

• 「configResolveDn の使用」

• 「configResolveDns の使用」

• 「configResolveClass の使用」

• 「configResolveClasses の使用」

• 「configFindDnsByClassId の使用」

• 「configResolveChildren の使用」

• 「configResolveParent の使用」

• 「configScope の使用」

configResolveDn の使用

DN の解決時には、次のことを確認してください。

• DN により指定されたオブジェクトが取得されている。

• 指定された DN が、解決するオブジェクト インスタンスを識別している（この DN は必須です）。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

「configResolveDn」（P.3-23） に示す要求または応答の例を参照してください。

configResolveDns の使用

複数の DN の解決時には、次のことを確認してください。

• DN により指定されたオブジェクトが取得されている。

• 指定された DN が、解決するオブジェクト インスタンスを識別している。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

• 要求の順序によって応答の順序が決まるわけではない。

• 未知の DN が、outUnresolved 属性の一部として返されている。

「configResolveDns」（P.3-24） に示す要求または応答の例を参照してください。

configResolveClass の使用

クラスの解決時には、次のことを確認してください。

• 指定されたクラス タイプのオブジェクトが取得されている。

• classId 属性により、返されるオブジェクト クラス名が指定されている。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

結果セットは大きくなることがあります。結果セットは正確に定義してください。たとえば、サーバのリストだけを取得する場合は、クエリーで classId の属性値として computeBlade を使用します。装置のすべてのインスタンスを取得するには、equipmentItem クラスを問い合わせます。

「configResolveClass」（P.3-20） に示す要求または応答の例を参照してください。

configResolveClasses の使用

複数のクラスの解決時には、次のことを確認してください。

• 指定されたクラス タイプのオブジェクトが取得されている。

• classId 属性により、返されるオブジェクト クラス名が指定されている。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

（注） 無効なクラス名が inId 属性で指定された場合は、XML 解析エラーが生成されます。クエリーは実行できません。

「configResolveClasses」（P.3-21） に示す要求または応答の例を参照してください。

configFindDnsByClassId の使用

指定されたクラスの識別名の検出時に、次のことを確認してください。

• 指定されたクラスの DN が取得されている。

• classId 属性により、取得するオブジェクト タイプが指定されている。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

「configFindDnsByClassId」（P.3-16） に示す要求または応答の例を参照してください。

configResolveChildren の使用

管理情報ツリーの子オブジェクトの解決時に、次のことを確認してください。

• このメソッドが、名前付きクラスのインスタンスである名前付きオブジェクトのすべての子オブジェクトを取得している。

（注） クラス名を省略すると、名前付きオブジェクトのすべての子オブジェクトが返されます。

• inDn 属性により、子オブジェクトが取得される名前付きオブジェクトが指定されている。

• classId 属性により、返される子オブジェクト クラスの名前が指定されている。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

「configResolveChildren」（P.3-18） に示す要求または応答の例を参照してください。

configResolveParent の使用

オブジェクトの親オブジェクトの解決時に、次のことを確認してください。

• このメソッドが、指定された DN の親オブジェクトを取得している。

• dn 属性が子オブジェクトの DN である。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

「configResolveParent」（P.3-26） に示す要求または応答の例を参照してください。

configScope の使用

クエリーのスコープを制限すると、粒度が細かくリソースを大量に消費しない要求を実現できます。クエリーは、管理情報ツリーでルート以外の場所に固定できます。

クエリー スコープの設定時に、次のことを確認してください。

• メソッドが、指定された DN にクエリーのルート（スコープ）を設定し、指定されたクラス タイプのオブジェクトを返している。

• dn が、クエリーのスコープが設定された名前付きオブジェクトである。

• inClass 属性により、返されるオブジェクト クラスの名前が指定されている。

（注） クラスが指定されない場合、クエリーは configResolveDn と同じように動作します。

• 認証 Cookie を aaaLogin または aaaRefresh から受け取っている。

• inHierarchical 属性（デフォルト値は false）が true の場合は、結果が階層形式であることが指定されている。

• 列挙値、クラス ID、およびビット マスクが文字列として表示されている。

「configScope」（P.3-28） に示す要求または応答の例を参照してください。

ポリシーに関するクエリー メソッド

ポリシーは、さまざまな組織で利用できます。多くのポリシーがある大規模なシステムでは、一度にすべてのポリシーを問い合わせるとリソースが大量に消費されます。代わりに、ポリシーのタイプと、ポリシーが割り当てられる親組織を指定してください。

例 2-6 に、ルールベースのポリシーに関するクエリーを示します。

例 2-6 ルールベースのポリシーに関するクエリー

応答は次のとおりです。

DN を使用する次のクエリーはさらに効率的です。

ポリシー オブジェクトとそのルール データを取得するには、inHierarchical を true に変更します。

障害に関するクエリー メソッド

例 2-7 に、障害に関するクエリーを示します。

例 2-7 障害に関するクエリー

次の例には、フィルタ <inFilter> eq class= "faultInst" が含まれていて、すべての主要または重大な障害のリストを取得します。

フィルタ

目的の特定のクエリーを作成するには、フィルタを使用します。

ここでは、次の内容について説明します。

• 「Simple フィルタ」

• 「Property フィルタ」

• 「Composite フィルタ」

• 「Modifier フィルタ」

Simple フィルタ

Simple フィルタは true 条件と false 条件を使用します。

ここでは、次の内容について説明します。

• 「false 条件」

• 「true 条件」

false 条件

次に、false 条件を使用した Simple フィルタの例を示します。

true 条件

次に、true 条件を使用した Simple フィルタの例を示します。

Property フィルタ

ここでは、次の内容について説明します。

• 「Equality フィルタ」

• 「Not equal フィルタ」

• 「Greater than フィルタ」

• 「Greater than or Equal to フィルタ」

• 「Less than フィルタ」

• 「Less than or Equal to フィルタ」

• 「Wildcard フィルタ」

• 「Any Bits フィルタ」

• 「All Bits フィルタ」

Equality フィルタ

次に、Equality フィルタの例を示します。

Not equal フィルタ

次に、Not equal フィルタの例を示します。

Greater than フィルタ

次に、Greater than フィルタの例を示します。

Greater than or Equal to フィルタ

次に、Greater than or Equal to フィルタの例を示します。

Less than フィルタ

次に、Less than フィルタの例を示します。

Less than or Equal to フィルタ

次に、Less than or Equal to フィルタの例を示します。

Wildcard フィルタ

次に、名前がプレフィクス「dmz」で始まるすべての仮想ファイアウォールを検索する Wildcard フィルタの例を示します。

Any Bits フィルタ

次に、Any Bits フィルタの例を示します。

All Bits フィルタ

次に、All Bits フィルタの例を示します。

Composite フィルタ

ここでは、次の内容について説明します。

• 「AND フィルタ」

• 「OR フィルタ」

• 「Between フィルタ」

• 「AND OR NOT Composite フィルタ」

AND フィルタ

次に、設定に関連付けられたファイアウォールを検索する AND フィルタの例を示します。

OR フィルタ

次に、操作ステータスが可視性なし、または未登録であるすべての管理対象エンドポイントを返す OR フィルタの例を示します。

Between フィルタ

次に、スロット 1、2、3、4、または 5 が使用されているメモリ アレイを検索する Between フィルタの例を示します。

AND OR NOT Composite フィルタ

次に、シャーシ 5 以外のすべてのシャーシのスロット 1 または 8 に存在する、タイプ computeBlade のすべてのオブジェクトを返す AND OR NOT Composite フィルタの例を示します。

Modifier フィルタ

NOT フィルタ

次に、NOT Modifier フィルタの例を示します。

Management Controller を使用した認証

Cisco VNMC へのアクセスはセッションベースであり、ログイン要求で最初に認証する必要があります。デフォルトのセッションの長さは 120 分です。aaaKeepAlive メソッドと aaaRefresh メソッドを使用して、セッションを延長できます。アクティビティが完了したときに、aaaLogout を使用してユーザがセッションから手動でログアウトすることが推奨されます。Cisco VNMC にログイン要求を送信する場合は、サービス タイプ mgmt-controller を使用します。

ここでは、次の内容について説明します。

• 「認証要求」

• 「認証応答」

認証要求

次に、認証要求の例を示します。

認証応答

次に、認証応答の例を示します。

サービス レジストリを使用したテナント管理

サービス レジストリ（サービス タイプが service-reg）は、ポリシーとリソースを整理するために使用されるテナントとサブ組織を作成および管理します。これらのテナントとサブ組織は、ボトムアップ ポリシーおよびリソース解決のためにツリー階層で配置されます。テナントとサブ組織の作成で使用されるクラス名は次の 4 つのレベルをサポートします。

• テナント、クラス orgTenant：最上位の組織を定義します。

• データセンター、クラス orgDatatcenter：テナント下のデータセンターを定義します。

• アプリケーション、クラス orgApp：データセンター下のアプリケーションを定義します。

• 階層、クラス orgTier：アプリケーション下の階層を定義します。

新しい組織を作成したり、既存の組織を更新したりする場合は、以下を指定します。

• オブジェクト DN

• 属性値

• created または modified に等しいステータス

組織を削除するには、要求で status = deleted を使用します。

ここでは、次の内容について説明します。

• 「組織の作成または更新の要求」

• 「組織の作成または更新の応答」

組織の作成または更新の要求

次に、demoTenant という名前のテナントを作成する例を示します。

組織の作成または更新の応答

次に、demoTenant という名前のテナントの作成後に受け取る応答の例を示します。

ポリシー管理

（注） configConfMos API が単一の設定オブジェクトを指定するために単一の XML 要素 <pair> を使用する各例では、同じ結果を得るために configConfMo API を代わりに使用できます。

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

• 「デバイス ポリシー」

• 「デバイス プロファイル」

• 「ゾーン」

• 「オブジェクト グループ」

• 「属性ディクショナリ」

• 「ポリシー」

• 「PolicySet」

• 「セキュリティ プロファイル」

デバイス ポリシー

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

• 「syslog ポリシー」

• 「SNMP ポリシー」

• 「LogProfile ポリシー」

syslog ポリシー

syslog ポリシー オブジェクトは、システム内で実行されるすべてのアクションを追跡します。また、デバイス ポリシーのロギング レベルを設定し、mysyslog を作成します。例 2-8 に、syslog ポリシー要求を示します。

例 2-8 syslog ポリシー要求

応答

SNMP ポリシー

次の例では、mysnmp という名前の SNMP ポリシーが作成されます。作成されたポリシーは、デバイス プロファイル リストでこの名前で利用できます。

要求

応答

LogProfile ポリシー

次の例では、debugLog という名前の LogProfile ポリシーに対してデバッグ レベルとロギング レベルが設定されます。

要求

応答

デバイス プロファイル

このアクションにより、myDeviceProfile という名前のデバイス プロファイルが作成されます。これにより、プロファイルが有効になり、プロファイルの内容が指定されます。

要求

応答

ゾーン

次の例では、trustedClients-0 と trustedServers-0 という名前の 2 つのゾーンが作成されます。また、値を持つ属性セットも割り当てられます。

要求

応答

オブジェクト グループ

次の例では、ftpPorts0 という名前のオブジェクト グループが作成され、属性セットが割り当てられます。

要求

応答

属性ディクショナリ

次の例では、さまざまな ID と名前を定義するディクショナリが設定されます。

要求

応答

ポリシー

次の例では、trustedHosts という名前のポリシーが作成され、使用できるルールが設定されます。

要求

応答

PolicySet

次の例では、myPolicySet0 が作成され、ポリシーが適用される順序が設定されます。

要求

応答

セキュリティ プロファイル

次の例では、vnsp-sp1 という名前のセキュリティ プロファイルが作成され、VNSP がそのセキュリティ プロファイルに割り当てられます。

要求

応答

リソース管理

リソース管理コンポーネントは、次の機能を実行します。

• コンピュータ ファイアウォールをデバイス ポリシーに割り当てます。

• 利用可能なファイアウォール インスタンスがないか問い合わせます。

• ファイアウォール インスタンスを管理対象オブジェクトに関連付けます。

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

• 「コンピュータ ファイアウォール」

• 「ファイアウォール インスタンスの問い合わせ」

• 「ファイアウォール インスタンスの関連付け」

コンピュータ ファイアウォール

次の例では、デバイス ポリシーに computeFirewall が割り当てられます。

要求

応答

ファイアウォール インスタンスの問い合わせ

次の例では、すべてのファイアウォール インスタンスとその属性の問い合わせが行われます。

要求

応答

ファイアウォール インスタンスの関連付け

次の例では、ファイアウォール インスタンスが管理対象オブジェクトに関連付けられ、firewall-0 が inst-1005 に割り当てられます。

要求

応答