Cisco APIC REST API ユーザ ガイド
APIC REST API の使用
APIC REST API の使用

APIC REST API の使用


(注)  


セキュリティ上の理由により、API 通信に対して HTTPS のみがデフォルト モードとして有効になっています。 必要に応じて、HTTP および HTTP-to-HTTPS のリダイレクションをイネーブルにできますが、安全性は低下します。 わかりやすくするために、このマニュアルではプロトコル コンポーネントとインタラクションの説明で HTTP に言及します。


この章の内容は、次のとおりです。

API の呼び出し

HTTP/1.1 か HTTPS POST、GET、または DELETE メッセージを Application Policy Infrastructure Controller (APIC)に送信することで、API 機能を呼び出すことができます。 POST メッセージの HTML 本文には、MO または API メソッドを記述する Javascript Object Notation(JSON)または XML データ構造が含まれます。 応答メッセージの HTML 本文には、要求されたデータ、要求されたアクションの確認、またはエラー情報を含む JSON または XML 構造が含まれます。


(注)  


応答構造のルート要素は imdata です。 この要素は応答用のコンテナにすぎず、管理情報モデル(MIM)のクラスではありません。

HTTP 要求メソッドとコンテンツ タイプの設定

API コマンドとクエリーは、次の項で説明されるように、サポートされている HTTP または HTTPS の要求メソッドとヘッダー フィールドを使用する必要があります。


(注)  


セキュリティ上の理由により、API 通信に対して HTTPS のみがデフォルト モードとして有効になっています。 必要に応じて、HTTP および HTTP-to-HTTPS のリダイレクションをイネーブルにできますが、安全性は低下します。 わかりやすくするために、このマニュアルではプロトコル コンポーネントとインタラクションの説明で HTTP に言及します。


要求メソッド

API は次のように HTTP POST、GET および DELETE の要求メソッドをサポートしています。

  • MO を作成または更新する API コマンド、またはメソッドを実行する API コマンドは、HTTP POST メッセージとして送信されます。

  • MO のプロパティおよびステータスを読み取る API クエリー、またはオブジェクトを検出する API クエリーは、HTTP GET メッセージとして送信されます。

  • MO を削除する API コマンドは、HTTP POST または DELETE メッセージとして送信されます。 ほとんどの場合、POST 操作でそのステータスを deleted に設定することで MO を削除できます。

PUT などの他の HTTP メソッドはサポートされません。


(注)  


DELETE メソッドはサポートされていますが、HTTP ヘッダーに Access-Control-Allow-Methods:POST,GET,OPTIONS のみが表示される場合があります。


コンテンツ タイプ

API は、API の要求または応答の HTML 本文で JSON または XML のデータ構造をサポートしています。 使用する形式を示す .json または .xml を URI パス名の末尾に付け加えることでコンテンツ タイプを指定する必要があります。 HTTP の [Content-Type] および [Accept] ヘッダーは API によって無視されます。

API コマンドまたはクエリー URI の作成

次の形式の Uniform Resource Identifier(URI)を使用して、HTTP または HTTPS メッセージを APIC に送信して API コマンドまたはクエリーを呼び出し、管理対象オブジェクト(MO)上で操作を実行できます。

{ http | https } ://host [:port] /api/mo/dn. { json | xml } [ ?options ]

オブジェクト クラス上での操作には次の形式を使用します。

{ http | https } ://host [:port] /api/class/className. { json | xml } [ ?options ]

次の例では、class fv:Tenant の MO に関与する API 操作用の URI の例を示します。

https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml

URI のコンポーネント

URI のコンポーネントは次のとおりです。

  • http:// または https://:HTTP または HTTPS を指定します。 デフォルトでは、HTTPS だけがイネーブルです。 必要に応じて、「GUI を使用した HTTP および HTTPS の設定」で説明するように、HTTP または HTTP-to-HTTPS のリダイレクションを明示的にイネーブルにし設定する必要があります。 HTTP と HTTPS は共存できます。

  • hostAPIC のホスト名または IP アドレスを指定します。

  • :portAPIC との通信に使用するポート番号を指定します。 システムが HTTP(80)または HTTPS(443)に標準のポート番号を使用する場合は、このコンポーネントを省略できます。

  • /api/:メッセージが API に向けられることを指定します。

  • mo | class:操作のターゲットが MO またはオブジェクト クラスであるかどうかを指定します。

  • dn:対象の MO の識別名(DN)を指定します。

  • className:対象のクラスの名前を指定します。 この名前は、照会されたオブジェクトのパッケージ名と、対応するパッケージのコンテキストで照会されたクラスの名前を連結したものです。

    たとえば、クラス aaa:User は、URI 内の aaaUser の className をもたらします。

  • json | xml:コマンドまたは応答 HTML 本文のエンコード形式が JSON または XML かを指定します。

  • ?options:(任意)クエリーに1 つ以上のフィルタ、セレクタ、または修飾子を指定します。 複数のオプション ステートメントは、アンパサンド(&)で結合されます。

MO での API 操作用の URI

特定の MO を作成、読み取り、更新または削除する API 操作では、『Cisco APIC Management Information Model Reference』に記載するように、リソース パスは /mo/ とその後の MO の DM で構成されます。 たとえば、テナント オブジェクトの DN は、クラス fv:Tenant の参照定義で述べたように、uni/tn-[name] となります。 この URI は、ExampleCorp という名前の fv:Tenant オブジェクトでの操作を指定します。

https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml

または、POST 操作で、次の例のように、/api/mo に POST 送信してメッセージの本文に DN を提供することができます。

POST https://192.0.20.123/api/mo.xml

<fvTenant dn="uni/tn-ExampleCorp"/>

また、次の例のように、メッセージ本文に名前のみを提供して、/api/mo と残りの相対名コンポーネントに POST 送信することもできます。

POST https://192.0.20.123/api/mo/uni.xml

<fvTenant name="ExampleCorp"/>

ノード MO での API 操作用の URI

ファブリックの特定のノード デバイス上の MO にアクセスするための API 操作では、リソースのパスは /mo/topology/pod-number/node-number/sys/ とその後に続くノード コンポーネントで構成されます。 たとえば、ポッド 1 のノード 1 のシャーシ スロット b 内のボード センサーにアクセスするには、次の URI を使用します。

GET https://192.0.20.123/api/mo/topology/pod-1/node-1/sys/ch/bslot/board/sensor-3.json

クラスでの API 操作用の URI

クラスに関する情報を入手するための API 操作では、『Cisco APIC Management Information Model Reference』に記載されているように、リソース パスは /class/ とその後に続くクラスの名前で構成されます。 URI では、クラス名のコロンは削除されます。 たとえば、次の URI はクラス aaa:User でのクエリーを指定します。

GET https://192.0.20.123/api/class/aaaUser.json

API コマンド本文の作成

POST 操作の HTML 本文には、コマンドの実行に必要な必須情報を提供する JSON または XML のデータ構造を含める必要があります。 GET または DELETE 操作ではデータ構造は送信されません。

API コマンド本文を作成するためのガイドライン

  • データ構造は、ターゲット MO またはメソッドの属性と要素のセット全体を表す必要はありませんが、少なくとも URI に組み込まれたプロパティやパラメータを除く、MO を識別しコマンドを実行するのに必要な最低限のプロパティまたはパラメータのセットを提供する必要があります。

  • データ構造では、パッケージ名の後のコロンはクラス名とメソッド名から除外されます。 たとえば、クラス zzz:Object の MO のデータ構造では、クラス要素は zzzObject となります。

  • XML データ構造に子またはサブツリーが含まれない場合、オブジェクト要素は自己終了できます。

  • API の大文字小文字は区別されます。

MO での API 操作用の API コマンドの本文の作成

MO を作成、変更または削除するためのコマンドを作成するには、『Cisco APIC Management Information Model Reference』 にあるクラスの記述を使用して、オブジェクトのクラスの重要なプロパティと子を説明する JSON または XML のデータ構造を作成します。 コマンドの実行に必要でない属性または子は省略できます。

仮定のクラス zzz:Object の MO 用の JSON 構造は、次の構造に似ています。

{
  "zzzObject" : {
    "attributes" : {
      "property1" : "value1",
      "property2" : "value2",
      "property3" : "value3"
    },
    "children" :
    [{
        "zzzChild1" : {
          "attributes" : {
            "childProperty1" : "childValue1",
            "childProperty2" : "childValue1"
          },
          "children" : []
        }
      }
    ]
  }
}

仮定のクラス zzz:Object の MO 用の XML 構造は、次の構造に似ています。

<zzzObject
  property1 = "value1",
  property2 = "value2",
  property3 = "value3">
    <zzzChild1
      childProperty1 = "childValue1",
      childProperty2 = "childValue1">
    </zzzChild1>
</zzzObject>

  

正常な操作では、MO の完全なデータ構造が返されます。

API セッションの認証と維持

API にアクセスする前に、設定したユーザの名前とパスワードで最初にログインする必要があります。

ログイン メッセージが受け入れられると、API は秒単位のセッション タイムアウト時間を含むデータ構造と、セッションを表すトークンを返します。 トークンは、HTTP 応答ヘッダーに Cookie としても返されます。 セッションを維持するために、セッション タイムアウト時間より長い期間他のメッセージが送信されなかった場合は API にログイン リフレッシュ メッセージを送信する必要があります。 トークンはセッションが更新されるたびに変わります。


(注)  


デフォルトのセッション タイムアウト時間は 300 秒、つまり 5 分です。


これらの API メソッドにより、セッション認証を管理することができます。

  • aaaLogin:POST メッセージとして送信され、このメソッドはユーザをログインし、セッションを開きます。 メッセージ本文には、名前とパスワードの属性を含む aaa:User オブジェクトが含まれ、応答にはセッション トークンと Cookie が含まれます。 複数の AAA ログイン ドメインが設定されている場合、ユーザ名の前に apic:domain\\ を追加する必要があります。

  • aaaRefresh:メッセージ本文なしの GET メッセージ、またはメッセージ本文が aaaLogin の POST メッセージとして送信され、このメソッドはセッション タイマーをリセットします。 レスポンスには、新しいセッション トークンと Cookie が含まれます。

  • aaaLogout:POST メッセージとして送信され、このメソッドはユーザをログアウトし、セッションを閉じます。 メッセージ本文には、name 属性を持つ aaa:User オブジェクトが含まれます。 応答には、空のデータ構造が含まれます。

  • aaaListDomains:GET メッセージとして送信され、このメソッドは有効な AAA ログイン ドメインのリストを返します。 ログインせずにこのメッセージを送信できます。

JSON または XML データ構造を指定して、この構文を使用して認証方式を呼び出すことができます。

{ http | https } ://host [:port] /api/methodName. { json | xml }

次に、JSON データ構造を使用するユーザ ログイン メッセージの例を示します。

POST https://192.0.20.123/api/aaaLogin.json

{
  "aaaUser" : {
    "attributes" : {
      "name" : "georgewa",
      "pwd" : "paSSword1"
    }
  }
}

次の例に、トークンと更新のタイムアウト時間を含む、ログイン成功時の応答の一部を示します。

RESPONSE:
{
  "imdata" : [{
      "aaaLogin" : {
        "attributes" : {
          "token" : 
             "GkZl5NLRZJl5+jqChouaZ9CYjgE58W/pMccR+LeXmdO0obG9NB
             Iwo1VBo7+YC1oiJL9mS6I9qh62BkX+Xddhe0JYrTmSG4JcKZ4t3
             bcP2Mxy3VBmgoJjwZ76ZOuf9V9AD6Xl83lyoR4bLBzqbSSU1R2N
             IgUotCGWjZt5JX6CJF0=",
          "refreshTimeoutSeconds" : "300",
          "lastName" : "Washington",
          "firstName" : "George"
        },
        "children" : [{
    ...
[TRUNCATED]
    ...
}

前の例では、refreshTimeoutSeconds 属性はセッション タイムアウト時間が 300 秒であることを示します。

次に、有効なログイン ドメインのリストを要求する例を示します。

GET https://192.0.20.123/api/aaaListDomains.json

RESPONSE:
{
  "imdata": [{
    "name": "ExampleRadius"
  },
  {
    "name": "local",
    "guiBanner": "San Jose Fabric"
  }]
}

前の例では、応答データは 2 つの予想されるログイン ドメイン「ExampleRadius」および「local」を示します。次に、ExampleRadius ログイン ドメインに対するユーザ ログイン メッセージの例を示します。

POST https://192.0.20.123/api/aaaLogin.json

{
  "aaaUser" : {
    "attributes" : {
      "name" : "apic:ExampleRadius\\georgewa",
      "pwd" : "paSSword1"
    }
  }
}

API セッションに必要なチャレンジ トークン

API セッションのセキュリティをより強力にするために、セッションがチャレンジ トークンを使用するように要求することができます。 ログイン時にこの機能を要求すると、API によりトークン文字列が返されるのでそれを API へのすべての後続メッセージに含める必要があります。 正常なセッション トークンとは異なり、チャレンジ トークンは、ブラウザによって自動的に提供される Cookie として保存されません。 API コマンドとクエリーは、次の方法のいずれかを使用してチャレンジ トークンを提供する必要があります。

  • チャレンジ トークンは、API メッセージの URI 内の「url-token」パラメータとして送信されます。

  • チャレンジ トークンは、「APIC-challenge」を使用した HTTP または HTTPS ヘッダーの一部です。

チャレンジ トークンを要求するセッションを開始するには、次の例に示すように、ログイン メッセージに URI パラメータ ステートメント ?gui-token-request=yes を加えます。

POST https://192.0.20.123/api/aaaLogin.json?gui-token-request=yes

応答メッセージの本文には、形式の属性 "urlToken":"token" が含まれ、token はチャレンジ トークンを表す文字の長い文字列です。 このセッション中の API へのすべての後続メッセージにはチャレンジ トークンを含める必要があります。次に示す例では「url-token」URI パラメータとして送信されています。

GET https://192.0.20.123/api/class/aaaUser.json?url-token=fa47e44df54562c24fef6601dc...

次の例では、チャレンジ トークンが HTTP ヘッダーの「APIC-challenge」フィールドとしてどのように送信されるかを示します。

GET //api/class/aaaUser.json
 HTTP/1.1 
 Host: 192.0.20.123 
 Connection: keep-alive 
 Accept: text/html,application/xhtml+xml,application/xml,application/json 
 APIC-challenge: fa47e44df54562c24fef6601dcff72259299a077336aecfc5b012b036797ab0f 
.
.
.

API クエリー結果のフィルタリング

1 つ以上の条件文を次の形式でパラメータとしてクエリー URI に追加することで、API クエリーの結果をフィルタリングできます。

https://URI?condition[&condition[&...]]

複数の条件文は、アンパサンド(&)で結合されます。


(注)  


条件文にはスペースを含めることはできません。


オブジェクト属性およびオブジェクト サブツリーによってフィルタするオプションが使用可能です。

クエリー スコープ フィルタの適用

スコープ フィルタを適用して、API クエリーへの応答の範囲を制限できます。 論理フィルタ式によって、クラス、プロパティ、カテゴリ、または認定に基づいてオブジェクトの第 1 レベルまたは 1 つ以上そのサブツリーまたは子への範囲を制限できます。

query-target={self | children | subtree}

このステートメントは、クエリーの範囲を制限します。 次のリストは使用可能な範囲について説明します。

  • [self]:(デフォルト)MO 自体のみを考慮し、子またはサブツリーは考慮しません。

  • [children]:MO の子のみを考慮し、MO 自体は考慮しません。

  • [subtree]:MO 自体およびそのサブツリーを考慮します。

target-subtree-class=mo-class1[,mo-class2]...

このステートメントは、[query-target] オプションが self 以外の範囲で使用される場合に考慮されるオブジェクト クラスを指定します。 スペースなしのカンマ区切りリストとして複数の希望するオブジェクト タイプを指定できます。

サブツリーの情報を要求するには、次のように query-target=subtreetarget-subtree-class と組み合わせ、特定のサブツリーを示します。

query-target=subtree&target-subtree-class=className

この例では、実行中のファームウェアに関する情報を要求しています。 情報は、APIC ファームウェア ステータス コンテナ firmware:IfcFwStatusCont の firmware:IfcRunning サブツリー(子)オブジェクトに含まれています。

GET https://192.0.20.123/api/class/firmwareIfcFwStatusCont.json?
    query-target=subtree&target-subtree-class=firmwareIfcRunning

query-target-filter=filter-expression

このステートメントは、応答に適用される論理フィルタを指定します。 このステートメントは、単独で使用するか、または query-target ステートメントの後ろに適用できます。

rsp-subtree={no | children | full}

返されたオブジェクトについて、このオプションは子オブジェクトが応答に含まれるかどうかを指定します。 次のリストは使用可能なオプションについて説明します。

  • [no]:(非デフォルト)応答には子が含まれていません。

  • [children]:応答には子だけが含まれます。

  • [full]:応答には、子を含め構造全体が含まれます。

rsp-subtree-class=mo-class

子オブジェクトが返される場合、このステートメントは、指定されたオブジェクト クラスの子オブジェクトだけが応答に含まれることを指定します。

rsp-subtree-filter=filter-expression

子オブジェクトが返される場合、このステートメントは、子オブジェクトに適用される論理フィルタを指定します。

rsp-subtree-include=category1[,category2...][option]

子オブジェクトが返される場合、このステートメントは、応答に含まれる追加のオブジェクトまたはオプションを指定します。 スペースなしのカンマ区切りリストで次のカテゴリの 1 つ以上を指定できます。

  • [audit-logs]:応答には、管理対象オブジェクトのユーザによる変更の履歴を含むサブツリーが含まれます。

  • [event-logs]:応答には、イベントの履歴情報を含むサブツリーが含まれます。

  • [faults]:応答には、現在アクティブな障害を含むサブツリーが含まれます。

  • [fault-records]:応答には、障害履歴情報を含むサブツリーが含まれます。

  • [health]:応答には、現在の動作状態情報を含むサブツリーが含まれます。

  • [health-records]:応答には、動作状態履歴情報を含むサブツリーが含まれます。

  • [relations]:応答には、関係関連のサブツリーの情報が含まれます。

  • [stats]:応答には、統計関連のサブツリーの情報が含まれます。

  • [tasks]:応答には、タスク関連のサブツリーの情報が含まれます。

上記いずれかのカテゴリとともに、次のオプションのいずれかを指定してさらにクエリー結果を絞り込むこともできます。

  • [count]:応答には、一致するサブツリーの数が含まれますが、サブツリー自体は含まれません。

  • [no-scoped]:応答には、要求したサブツリーの情報のみが含まれます。 ターゲット MO の他の最上位の情報は応答に含まれていません。

  • [required]:応答には、指定したカテゴリと一致するサブツリーを持つ管理対象オブジェクトのみが含まれます。

たとえば、障害関連サブツリーを含めるには、リストに [fault] を指定します。 障害関連サブツリーのみを返し他の最上位の MO 情報は返さないようにするには、次の例に示すようにリストに [fault,no-scoped] を指定します。

query-target=subtree&rsp-subtree-include=fault,no-scoped

クエリー フィルタ式の作成

論理演算子および値の式を適用して、API クエリーへの応答をフィルタリングできます。

基本的な等式または不等式のテストは次のように表されます。

query-target-filter=[eq|ne](attribute,value)

カッコやカンマを使用して演算子と条件を組み合わせることで、より複雑なテストを作成できます。

query-target-filter=[and|or]([eq|ne](attribute,value),[eq|ne](attribute,value),...)

使用可能な論理演算子

このテーブルは、クエリーのフィルタ式で使用可能な論理演算子を示します。

演算子 説明
eq

等しい

ne

等しくない

lt

より小さい

gt

より大きい

le

以下

ge

以上

bw

not

論理反転

および

論理積

または

論理和

xor

論理排他的 OR

true

ブール値 TRUE

false

ブール値 FALSE

anybit

少なくとも 1 つのビットが設定されている場合は TRUE

allbits

すべてのビットが設定されている場合は TRUE

wcard

ワイルドカード

pholder

プロパティ ホルダー

passive

パッシブ ホルダー

次の例では、姓が「Washington」に等しいクラス aaaUser のすべての管理対象オブジェクトが返されます。

GET https://192.0.20.123/api/class/aaaUser.json?
      query-target-filter=eq(aaaUser.lastName,"Washington")

次の例では、fabEncap プロパティが「vxlan-12780288」であるエンドポイント グループが返されます。

GET https://192.0.20.123/api/class/fvAEPg.xml?
    query-target-filter=eq(fvAEPg.fabEncap,"vxlan-12780288")

次の例は、現在のヘルス スコアが 50 未満のテナント オブジェクトすべてを示します。

GET https://192.0.20.123/api/class/fvTenant.json?
    rsp-subtree-include=health,required
        &
        rsp-subtree-filter=lt(healthInst.cur,"50")

次の例では、テナント ExampleCorp 下のすべてのエンドポイント グループとそれらの障害が返されます。

GET https://192.0.20.123/api/mo/uni/tn-ExampleCorp.xml?
    query-target=subtree
        &
        target-subtree-class=fvAEPg
            &
            rsp-subtree-include=faults

次の例では、名前が「infra」または「common」でない aaa:Domain オブジェクトが返されます。

GET https://192.0.20.123/api/class/aaaDomain.json?
    query-target-filter=
        and(ne(aaaDomain.name,"infra"),
            ne(aaaDomain.name,"common"))

クエリー結果の並べ替えとページ付け

大量のデータを返す API クエリーを送信するときは、返されたデータを並べ替えてページ付けし、必要な情報が簡単に検索できるようにすることができます。

結果の並べ替え

order-by 演算子をクエリー URI に追加することで、クエリー応答をクラス内の 1 つ以上のプロパティによって並べ替えることができ、次の構文を使用して順序の方向を指定できます。

order-by=classname.property [ | { asc | desc } ] [ ,classname.property [ | { asc | desc } ] ] [ ,... ]

昇順(asc)または降順(desc)を指定するにはオプションのパイプ区切り文字('|')を使用します。 順序が指定されていない場合、デフォルトは昇順となります。

複数のプロパティ(姓や名など)によってマルチレベルのソートを実行できますが、すべてのプロパティを同じ MO にする必要があるか、または同じ抽象クラスから継承する必要があります。

次の例で、ユーザを姓で並べ替え、次に名で並べ替える方法を示します。

GET https://192.0.20.123/api/class/aaaUser.json?order-by=aaaUser.lastName|asc,aaaUser.firstName|asc

結果のページ付け

page-size 演算子をクエリー URI に追加することで、次の構文を使用してクエリーの結果をオブジェクトのグループ(ページ)に分けることができます。 オペランドは各グループ内のオブジェクトの数を指定します。

page-size=number-of-objects-per-page

page 演算子をクエリー URI に追加することで、次の構文を使用して単一のグループが返されるように指定できます。 ページは、番号 0 から始まります。

page=page-number

次に、1 ページあたり 15 個の障害インスタンスを降順で最初のページのみを返すように指定する方法を示します。

GET https://192.0.20.123/api/class/faultInfo.json?order-by=faultInst.severity|desc&page=0&page-size=15


(注)  


ページ付けされているかどうかにかかわらず、すべてのクエリーが新しい結果のセットを生成します。 単一ページだけを返すクエリーを実行すると、クエリー応答には集計結果の総数が含まれますが、送信されないページは保存されず、後続のクエリーによって取得できません。 後続のクエリーは新しい結果のセットを生成し、そのクエリーで要求されたページを返します。


クエリー結果へのサブスクライブ

API クエリーを実行するときは、実行中の API セッション中に発生するそのクエリーの結果の今後の変更へのサブスクリプションを作成するオプションがあります。 ユーザまたはシステムにより開始されたアクションによって、MO が作成、変更、または削除されると、イベントが生成されます。 そのイベントがアクティブなサブスクライブ済みのクエリーの結果を変更すると、APIC はサブスクリプションを作成した API クライアントへのプッシュ通知を生成します。

WebSocket のオープン

API サブスクリプション機能は、WebSocket プロトコル(RFC 6455)を使用して API クライアントとの双方向接続を実行し、その接続によって API はクライアントに要求されていない通知メッセージを送信できます。 この通知チャネルを確立するには、まず API との WebSocket 接続をオープンする必要があります。 複数の APIC インスタンスとの複数のクエリー サブスクリプションをサポートするのに必要なのは単一の WebSocket 接続のみです。 WebSocket 接続は API セッション接続に依存し、API セッションが終了すると閉じます。

WebSocket 接続は通常、次の例に示すように、HTML5 対応ブラウザで JavaScript 方式によって開きます。

var Socket = new WebSocket(https://192.0.20.123/socket%TOKEN%);

URI では、%TOKEN% が現在の API セッション トークン(Cookie)です。 次に、トークン付きの URI の例を示します。

https://192.0.20.123/socketGkZl5NLRZJl5+jqChouaZ9CYjgE58W/pMccR+LeXmdO0obG9NB
Iwo1VBo7+YC1oiJL9mS6I9qh62BkX+Xddhe0JYrTmSG4JcKZ4t3bcP2Mxy3VBmgoJjwZ76ZOuf9V9AD6X
l83lyoR4bLBzqbSSU1R2NIgUotCGWjZt5JX6CJF0=

WebSocket 接続の確立後は、API セッションの更新時に API セッション トークンを再送信する必要はありません。

サブスクリプションの作成

クエリーにサブスクリプションを作成するには、オプション ?subscription=yes でクエリーを実行します。 次の例では、JSON 形式で fv:Tenant クラスのクエリーにサブスクリプションを作成します。

GET https://192.0.20.123/api/class/fvTenant.json?subscription=yes

クエリー応答には、サブスクリプションの識別子、subscriptionId が含まれ、サブスクリプションを更新し、このサブスクリプションから今後の通知を識別するために使用できます。

{
  "subscriptionId" : "72057611234574337",
  "imdata" : [{
      "fvTenant" : {
        "attributes" : {
          "instanceId" : "0:0",
          "childAction" : "",
          "dn" : "uni/tn-common",
          "lcOwn" : "local",
          "monPolDn" : "",
          "name" : "common",
          "replTs" : "never",
          "status" : ""
        }
      }
    }
  ]
}

受信通知

サブスクリプションからのイベント通知では、サブスクリプション ID と MO の説明を含むデータ構造が提供されます。 この JSON の例では、新しいユーザが名前「sysadmin5」で作成されています。

{
  "subscriptionId" : ["72057598349672454", "72057598349672456"],
  "imdata" : [{
      "aaaUser" : {
        "attributes" : {
          "accountStatus" : "active",
          "childAction" : "",
          "clearPwdHistory" : "no",
          "descr" : "",
          "dn" : "uni/userext/user-sysadmin5",
          "email" : "",
          "encPwd" : "TUxISkhH$VHyidGgBX0r7N/srt/YcMYTEn5248ommFhNFzZghvAU=",
          "expiration" : "never",
          "expires" : "no",
          "firstName" : "",
          "intId" : "none",
          "lastName" : "",
          "lcOwn" : "local",
          "name" : "sysadmin5",
          "phone" : "",
          "pwd" : "",
          "pwdLifeTime" : "no-password-expire",
          "pwdSet" : "yes",
          "replTs" : "2013-05-30T11:28:33.835",
          "rn" : "",
          "status" : "created"
        }
      }
    }
  ]
}

複数のアクティブなサブスクリプションが 1 つのクエリーに対し存在できるため、通知には例に示すように複数のサブスクリプション ID を含めることができます。


(注)  


通知は、JSON または XML 形式でサポートされています。


サブスクリプションの更新

イベント通知を受信し続けるには、API セッション中に各サブスクリプションを定期的に更新する必要があります。 サブスクリプションを更新するには、次の例のように、subscriptionId に相当するパラメータ id を使用して、HTTP GET メッセージを API 方式 subscriptionRefresh に送信します。

GET https://192.0.20.123/api/subscriptionRefresh.json?id=72057611234574337

サブスクリプションが期限切れになっていなければ、API はリフレッシュ メッセージに空の応答を返します。


(注)  


サブスクリプションのタイムアウト時間は 1 分です。 通知が失われないようにするには、サブスクリプションのリフレッシュ メッセージを少なくとも 60 秒ごとに送信する必要があります。


オブジェクトとプロパティの作成、変更、および削除

管理対象オブジェクト(MO)またはそのプロパティで API 操作を実行する前に、Web ベースのマニュアルである『Cisco APIC Management Information Model Reference』でオブジェクトのクラス定義を確認する必要があります。 管理情報モデル(MIM)は、次のようなルールを定義するスキーマとして機能します。

  • MO を接続できる親オブジェクトのクラス

  • MO に接続できる子オブジェクトのクラス

  • MO に接続できるクラス タイプの子オブジェクトの数

  • ユーザが MO を作成、変更、または削除できるかどうか、またそのために必要な権限レベル

  • オブジェクト クラスのプロパティ(属性)

  • データ タイプとプロパティの範囲

API コマンドを送信すると、APIC は MIM スキーマに適合するかどうかコマンドを確認します。 API コマンドが MIM スキーマに違反している場合、APIC はコマンドを拒否し、エラー メッセージを返します。 たとえば、MO を作成できるのは、コマンド URI で指定したパスで作成が許可される場合、またはユーザがそのオブジェクト クラスに必要な権限レベルを持っている場合のみです。 有効なデータのみで MO のプロパティを設定でき、プロパティは作成できません。

MO を作成する API コマンドを作成するときに必要なのは新しい MO を一意的に定義するためにコマンドの URI とデータ構造に十分な情報を盛り込むことだけです。 MO の作成時にプロパティ設定を省略すると、MIM が指定している場合はプロパティがデフォルト値で入力され、それ以外は空白のままになります。

MO のプロパティを変更する場合に必要なのは、変更するプロパティとその新しい値を指定することだけです。 他のプロパティは未変更のままになります。


(注)  


APIC またはスイッチ管理コミュニケーション ポリシーに影響する MO を変更すると、ファブリック内の APIC やスイッチ Web インターフェイスで進行中の操作に短時間の中断が発生する場合があります。 中断が生じる可能性がある設定変更には次のものがあります。

  • ポート番号などの管理ポート設定の変更

  • HTTPS のイネーブル化またはディセーブル化

  • HTTPS へのリダイレクションの状態の変更

  • キー リングなどの PKI の変更



ヒント


このマニュアルで示される API の例に加えて、API を使用する多くの一般的なタスクの詳細な例を『Cisco APIC Getting Started Guide』で確認できます。


タグの使用

API 操作を簡略化するために、オブジェクトにタグを割り当てることができます。 タグを使用すると、わかりやすい名前で複数のオブジェクトをグループ化できます。 複数のオブジェクトに同じタグ名を割り当て、1 つのオブジェクトに 1 つ以上のタグ名を割り当てることができます。 API 操作では、識別名(DN)の代わりにタグ名でオブジェクトまたはオブジェクトのグループを参照できます。

タグの追加

API POST 操作の URI で、次の構文を使用して 1 つ以上のタグを追加できます。

/api/tag/mo/dn. { json | xml } ?add= [, name, ...] [, name, ...]

この構文で、name はタグの名前、dn はタグが割り当てられるオブジェクトの識別名です。

次に、ExampleCorp という名前のテナントにタグのテナントと組織を割り当てる例を示します。

POST https://192.0.20.123/api/tag/mo/uni/tn-ExampleCorp.xml?add=tenants,orgs

タグの削除

API POST 操作の URI で、次の構文を使用して 1 つ以上のタグを削除できます。

/api/tag/mo/dn. { json | xml } ?remove=name [, name, ...]

次に、ExampleCorp という名前のテナントからタグの組織を削除する例を示します。

POST https://192.0.20.123/api/tag/mo/uni/tn-ExampleCorp.xml?remove=orgs

API DELETE 操作の URI で、次の構文を使用してタグのすべてのインスタンスを削除できます。

/api//tag/name. { json | xml }

次に、すべてのオブジェクトからタグの組織を削除する例を示します。

DELETE https://192.0.20.123/api/tag/orgs.xml

タグ使用の追加例


(注)  


ここに示す例では、タグに無関係な属性を削除するために応答が編集されています。


次に、ExampleCorp という名前のテナントに割り当てられたすべてのタグを検索する例を示します。

GET https://192.0.20.123/api/tag/mo/uni/tn-ExampleCorp.xml

RESPONSE:
<imdata>
    <tagInst
         dn="uni/tn-ExampleCorp/tag-tenants" 
         name="tenants" 
    />
    <tagInst
         dn="uni/tn-ExampleCorp/tag-orgs"  
         name="orgs" 
    />
</imdata>

次に、タグ「tenants」を持つすべてのオブジェクトを検索する例を示します。

GET https://192.0.20.123/api/tag/tenants.xml

RESPONSE:
<imdata>
    <fvTenant
        dn="uni/tn-ExampleCorp" 
        name="ExampleCorp"
    />
</imdata>