この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
(注) | セキュリティを確保するために、API 通信のデフォルト モードとして HTTPS のみがイネーブルになります。HTTP、および HTTP から HTTPS へのリダイレクションは必要に応じてイネーブルにすることができますが、安全性は低くなります。わかりやすくするために、このマニュアルではプロトコル コンポーネントおよびインタラクションの説明において HTTP に言及しています。 |
この章の内容は、次のとおりです。
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)のクラスではありません。 |
API コマンドとクエリーは、次の項で説明されるように、サポートされている HTTP または HTTPS の要求メソッドとヘッダー フィールドを使用する必要があります。
(注) | セキュリティを確保するために、API 通信のデフォルト モードとして HTTPS のみがイネーブルになります。HTTP、および HTTP から 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 によって無視されます。
次の形式の 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 のコンポーネントは次のとおりです。
http:// または https://:HTTP または HTTPS を指定します。デフォルトでは、HTTPS だけがイネーブルです。必要に応じて、「GUI を使用した HTTP および HTTPS の設定」で説明するように、HTTP または HTTP-to-HTTPS のリダイレクションを明示的にイネーブルにし設定する必要があります。HTTP と HTTPS は共存できます。
host:APIC のホスト名または IP アドレスを指定します。
:port:APIC との通信に使用するポート番号を指定します。システムが 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 操作では、『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 操作では、リソースのパスは /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 操作では、『Cisco APIC Management Information Model Reference』に記載されているように、リソース パスは /class/ とその後に続くクラスの名前で構成されます。URI では、クラス名のコロンは削除されます。たとえば、次の URI はクラス aaa:User でのクエリーを指定します。
GET https://192.0.20.123/api/class/aaaUser.json
POST 操作の HTML 本文には、コマンドの実行に必要な必須情報を提供する JSON または XML のデータ構造を含める必要があります。GET または DELETE 操作ではデータ構造は送信されません。
データ構造は、ターゲット MO またはメソッドの属性と要素のセット全体を表す必要はありませんが、少なくとも URI に組み込まれたプロパティやパラメータを除く、MO を識別しコマンドを実行するのに必要な最低限のプロパティまたはパラメータのセットを提供する必要があります。
データ構造は、すべての子ノードが一意の DN を持ち一意である、単一ツリーです。重複するノードは許可されません。同じノードを二度含めることで、1 つのノードを 2 度変更することはできません。この場合、1 つのノードに変更をマージする必要があります。
データ構造では、パッケージ名の後のコロンはクラス名とメソッド名から除外されます。たとえば、クラス zzz:Object の MO のデータ構造では、クラス要素は zzzObject となります。
JSON の仕様では不適切な順序の要素も許可されますが、APIC REST API では、JSON の「attributes」要素が「children」配列またはその他の要素に先行することが必要です。
XML データ構造に子またはサブツリーが含まれない場合、オブジェクト要素は自己終了できます。
API の大文字小文字は区別されます。
URL に「api」を含んで API コマンドを送信する場合、API POST コマンドの HTML 本文の最大サイズは 1 MB です。
URL に「ppi」を含んでデバイス パッケージ ファイルをアップロードする場合、POST コマンドの HTML 本文の最大サイズは 10 MB です。
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 は秒単位のセッション タイムアウト時間を含むデータ構造と、セッションを表すトークンを返します。トークンは、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 へのすべての後続メッセージに含める必要があります。正常なセッション トークンとは異なり、チャレンジ トークンは、ブラウザによって自動的に提供される Cookie として保存されません。API コマンドとクエリーは、次の方法のいずれかを使用してチャレンジ トークンを提供する必要があります。
チャレンジ トークンは、API メッセージの URI 内の「challenge」パラメータとして送信されます。
チャレンジ トークンは、「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 へのすべての後続メッセージにはチャレンジ トークンを含める必要があります。次に示す例では「challenge」URI パラメータとして送信されています。
GET https://192.0.20.123/api/class/aaaUser.json?challenge=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 . . .
1 つ以上の条件文を次の形式でパラメータとしてクエリー URI に追加することで、API クエリーの結果をフィルタリングできます。
https://URI?condition[&condition[&...]]
複数の条件文は、アンパサンド(&)で結合されます。
(注) | 条件文にはスペースを含めることはできません。 |
オブジェクト属性およびオブジェクト サブツリーによってフィルタするオプションが使用可能です。
スコープ フィルタを適用して、API クエリーへの応答の範囲を制限できます。論理フィルタ式によって、クラス、プロパティ、カテゴリ、または認定に基づいてオブジェクトの第 1 レベルまたは 1 つ以上そのサブツリーまたは子への範囲を制限できます。
このステートメントは、クエリーの範囲を制限します。次のリストは使用可能な範囲について説明します。
このステートメントは、[query-target] オプションが [self] 以外の範囲で使用される場合に考慮されるオブジェクト クラスを指定します。スペースなしのカンマ区切りリストとして複数の希望するオブジェクト タイプを指定できます。
サブツリーの情報を要求するには、次のように query-target=subtree を target-subtree-class ステートメントと組み合わせ、特定のサブツリーを示します。
query-target=subtree&target-subtree-class=className
この例では、実行中のファームウェアに関する情報を要求しています。情報は、APIC ファームウェア ステータス コンテナ firmware:CtrlrFwStatusCont の firmware:CtrlrRunning サブツリー(子)オブジェクトに含まれています。
GET https://192.0.20.123/api/class/firmwareCtrlrFwStatusCont.json? query-target=subtree&target-subtree-class=firmwareCtrlrRunning
このステートメントは、応答に適用される論理フィルタを指定します。このステートメントは、単独で使用するか、または query-target ステートメントの後ろに適用できます。
返されたオブジェクトについて、このオプションは子オブジェクトが応答に含まれるかどうかを指定します。次のリストは使用可能なオプションについて説明します。
子オブジェクトが返される場合、このステートメントは、指定されたオブジェクト クラスの子オブジェクトだけが応答に含まれることを指定します。
子オブジェクトが返される場合、このステートメントは、子オブジェクトに適用される論理フィルタを指定します。
(注) | rsp-subtree-filter クエリー ステートメントに class.property オペランドが含まれる場合、指定したクラス名がプロパティとタイプを特定するために使用されます。返された結果はクラスでフィルタリングされず、同じ名前のプロパティを含む子オブジェクトを含む可能性がありますが、そのオブジェクトのプロパティがクエリー条件に一致する場合、別のクラスに属します。クラスでフィルタリングするには、追加のクエリー フィルタを使用する必要があります。 |
子オブジェクトが返される場合、このステートメントは、応答に含まれる追加のオブジェクトまたはオプションを指定します。スペースなしのカンマ区切りリストで次のカテゴリの 1 つ以上を指定できます。
[audit-logs]:応答には、管理対象オブジェクトのユーザによる変更の履歴を含むサブツリーが含まれます。
[event-logs]:応答には、イベントの履歴情報を含むサブツリーが含まれます。
[faults]:応答には、現在アクティブな障害を含むサブツリーが含まれます。
[fault-records]:応答には、障害履歴情報を含むサブツリーが含まれます。
[health]:応答には、現在の動作状態情報を含むサブツリーが含まれます。
[health-records]:応答には、動作状態履歴情報を含むサブツリーが含まれます。
[relations]:応答には、関係関連のサブツリーの情報が含まれます。
[stats]:応答には、統計関連のサブツリーの情報が含まれます。
[tasks]:応答には、タスク関連のサブツリーの情報が含まれます。
上記いずれかのカテゴリとともに、次のオプションのいずれかを指定してさらにクエリー結果を絞り込むこともできます。
[count]:応答には、一致するサブツリーの数が含まれますが、サブツリー自体は含まれません。
[no-scoped]:応答には、要求したサブツリーの情報のみが含まれます。 ターゲット MO の他の最上位の情報は応答に含まれていません。
[required]:応答には、指定したカテゴリと一致するサブツリーを持つ管理対象オブジェクトのみが含まれます。
たとえば、障害関連サブツリーを含めるには、リストに [faults] を指定します。障害関連サブツリーのみを返し他の最上位の MO 情報は返さないようにするには、次の例に示すようにリストに [faults,no-scoped] を指定します。
query-target=subtree&rsp-subtree-include=faults,no-scoped
(注) | 親オブジェクトがファブリック ノード(リーフ)にプッシュされるまで、一部のタイプの子オブジェクトは作成されません。そのような親オブジェクトがファブリック ノードにプッシュされるまで、rsp-subtree-include フィルタを使用した親オブジェクトでのクエリーは結果を返さない可能性があります。たとえば、クエリー オプション rsp-subtree-include=stats を含む fvAEPg のクラス クエリーは、テナントに適用され、ファブリック ノードにプッシュされたエンドポイントのグループだけの統計を返します。 |
このステートメントは、[rsp-subtree] オプションが no 以外の引数で使用される場合に応答に含むべきプロパティのタイプを指定します。
論理演算子および値の式を適用して、API クエリーへの応答をフィルタリングできます。
基本的な等式または不等式のテストは次のように表されます。
query-target-filter=[eq|ne](attribute,value)
カッコやカンマを使用して演算子と条件を組み合わせることで、より複雑なテストを作成できます。
query-target-filter=[and|or]([eq|ne](attribute,value),[eq|ne](attribute,value),...)
(注) | 範囲フィルタには最大で 20 の「(attribute,value)」フィルタ式を含めることができます。制限を超えると、API はエラーを返します。 |
このテーブルは、クエリーのフィルタ式で使用可能な論理演算子を示します。
演算子 | 説明 |
---|---|
eq |
等しい |
ne |
等しくない |
lt |
より小さい |
gt |
より大きい |
le |
以下 |
ge |
以上 |
bw |
間 |
not |
論理反転 |
および |
論理積 |
または |
論理和 |
xor |
論理排他的 OR |
true |
ブール値 TRUE |
false |
ブール値 FALSE |
anybit |
少なくとも 1 つのビットが設定されている場合は TRUE |
allbits |
すべてのビットが設定されている場合は TRUE |
wcard |
Wildcard |
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 クライアントへのプッシュ通知を生成します。
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 のプロパティを変更する場合に必要なのは、変更するプロパティとその新しい値を指定することだけです。他のプロパティは未変更のままになります。
ヒント | このマニュアルで示される API の例に加えて、API を使用する多くの一般的なタスクの詳細な例を『Cisco APIC Getting Started Guide』で確認できます。 |
APIC またはスイッチ管理コミュニケーション ポリシーに影響する MO を変更すると、ファブリック内の APIC やスイッチ Web インターフェイスで進行中の操作に短時間の中断が発生する場合があります。中断が生じる可能性がある設定変更には次のものがあります。
既存の MO を読み取ると、MO の Password プロパティがセキュリティ上の理由から空白として読み取られます。APIC へ再度 MO を書き込むと、password プロパティは空白として作成されます。
ヒント | パスワード情報を含む MO を保存する必要がある場合は、構成のエクスポート ポリシーを使用します。特定の MO を保存するには、ポリシーでターゲットの 識別名として MO を指定します。 |
API 操作を簡略化するために、オブジェクトにエイリアスまたはタグを割り当てることができます。API 操作では、識別名(DN)の代わりにエイリアスまたはタグ名でオブジェクトまたはオブジェクトのグループを参照できます。次のようにタグとエイリアスの使用には違いがあります。
タグ:タグを使用すると、わかりやすい名前で複数のオブジェクトをグループ化できます。複数のオブジェクトに同じタグ名を割り当て、1 つのオブジェクトに 1 つ以上のタグ名を割り当てることができます。
エイリアス:単一のテナントを示す場合、エイリアスは DN よりも簡単でわかりやすいものにすることができます。1 つのオブジェクトだけに固有のエイリアス名を割り当てることができます。システムは 2 番目のオブジェクトに同じエイリアス名を割り当てできないようにします。
(注) | すべてのオブジェクトがタグをサポートしているわけではありません。オブジェクトがタグ付け可能なかどうかを確認するには、『Cisco APIC Management Information Model Reference』でオブジェクト クラスを確認します。オブジェクト クラスのその階層にタグのインスタンスがあれば(tag:AInst または tag:AInst から派生したクラス)、そのクラスのオブジェクトにタグ付けすることができます。 |
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
API POST 操作の URI で、次の構文を使用してエイリアスを追加できます。
/api/alias/mo/dn. { json | xml } ?set=name
この構文で、name はエイリアスの名前、dn はエイリアスが割り当てられるオブジェクトの識別名です。
次に、ExampleCorp という名前のテナントにエイリアス tenant8 を割り当てる例を示します。
POST https://192.0.20.123/api/alias/mo/uni/tn-ExampleCorp.xml?set=tenant8
API POST 操作の URI で、次の構文を使用してエイリアスを削除できます。
/api/alias/mo/dn. { json | xml } ?clear=yes
次に、ExampleCorp という名前のテナントからエイリアスを削除する例を示します。
POST https://192.0.20.123/api/alias/mo/uni/tn-ExampleCorp.xml?clear=yes
(注) | ここに示す例では、タグに無関係な属性を削除するために応答が編集されています。 |
次に、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>