この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章では、Configuration Web サービスを使用するために設定が必要な環境と、このサービスを使用する方法について説明します。
Configuration Web サービスは、HTTPS による REST インターフェイスとして実装されます。HTTP はサポートされていません。
Configuring REST Web サービスは、導入環境内のすべての ACS サーバで使用できます。ただし、ACS プライマリ インスタンスだけが、読み取り操作と書き込み操作をサポートするすべてのサービスを提供します。ACS セカンダリ インスタンスは、設定データに対して読み取りアクセスだけを提供します。
Monitoring and Report Viewer には、すべての REST アクティビティに対するメッセージと監査ログが表示されます。
ACS CLI での REST Web インターフェイスのイネーブル化
REST Web サービスを使用する前に、ACS で Web インターフェイスをイネーブルにする必要があります。ACS で Web インターフェイスをイネーブルにするには、ACS CLI から次のように入力します。
acs config-web-interface コマンドの詳細については、次の URL を参照してください。
http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control_system/5.3/command/
reference/cli_app_a.html#wp1887278
ACS CLI からの REST Web インターフェイスのステータス表示
Web インターフェイスのステータスを表示するには、ACS CLI から次のように入力します。
show acs-config-web-interface コマンドの詳細については、次の URL を参照してください。
http://www.cisco.com/en/US/docs/net_mgmt/cisco_secure_access_control_system/5.3/command/reference/cli_app_a.html#wp1890877
ACS Configuration REST サービスと連携動作するアプリケーションでは、REST サービスに対する認証のために任意の管理者アカウントを使用できます。使用するアカウントに対する許可は、REST クライアントによって実行されるすべてのアクティビティを許可するように設定する必要があります。
ACS の Rest PI は、ACS を設定するためのサービスを提供します。これは、設定機能ごとにまとめられています。ACS 5.3 では、ACS 設定の次の 2 つのサブセットがサポートされています。
• Identity Configuration オブジェクト
表 4-1 に、サポートされる Configuration オブジェクトを示します。
ID グループ オブジェクトは、ID グループ階層でノードを操作するために使用します。グループ名によって、階層内のノードのフル パスが定義されます。 新しいノードを追加する場合、ノードの名前(フル パスを含む)は、そのノードを追加すべき階層内の場所を指定していることに注意する必要があります。例を示します。
(注) 上位レベルの階層(親ノード)を作成してから、リーフ ノードを作成する必要があります。たとえば、階層 All Groups:US:WDC を作成するには、All Groups:US を作成してから、階層内で次のレベルの作成に進む必要があります。
AttributeInfo 構造は、属性名と属性値のペアの配列になっています。
属性名は、ユーザ ディクショナリを参照します。このディクショナリで、値の型などの属性の定義を検索できます。属性の値は、ディクショナリの定義に従う必要があります。
次に、2 つの属性があるユーザに対する Java での表現の例を示します。
REST インターフェイス スキーマは、ユーザ オブジェクト上のグループ名プロパティとして、ID グループに対するユーザの関連付けを示します。
REST インターフェイス スキーマは、基準およびその他のクエリー パラメータを定義するためのクエリー オブジェクトを公開しています。クエリー オブジェクトは、ユーザと ID グループで使用されます。
クエリー オブジェクトには、次の項目に適用されるパラメータが含まれます。
• 「ソート」
• 「ページング」
クエリー オブジェクトを使用すると、フィルタ後の結果セットを取得できます。次の基準に基づいて、ユーザまたは ID グループをフィルタリングできます。
• 単純な条件:プロパティ名、操作、および値が含まれます。 たとえば、name STARTS_WITH "A" とします。
• And 条件:単純な条件のセットが含まれます。 And 条件と一致するためには、すべての単純な条件が True に評価される必要があります。
次に「And」フィルタに対する XML ベースの例を示します。
次に「And」フィルタに対する Java ベースの例を示します。
次のページング パラメータで、クエリー オブジェクトを設定できます。
ページングは、ステートレスです。要求されたページは、要求ごとに新規計算されます。このため、オブジェクトが同時に追加または削除された場合、ページングによってオブジェクトがスキップされたり、オブジェクトが 2 回返されることがあります。
• コンテンツ:要求するメソッドに適用される場合は、ACS オブジェクトが含まれます。ACS オブジェクトは、XML で表現されます。
• オブジェクト タイプ:User、Identity Group など
• オブジェクト ID では、GET メソッドと DELETE メソッドが有効です。
• 操作名は、クエリーなどの CRUD 以外の操作で必要です。
表 4-2 には、各オブジェクトの URL を示します。
オブジェクトは、名前またはオブジェクト ID によって識別されます。基本オブジェクト キーは、オブジェクト名です。GET メソッドと DELETE メソッドでオブジェクト ID を使用することもできます。POST メソッドと PUT メソッドでは、ID を含むオブジェクト自体が取得されます。
• キーとしての名前:Rest/{package}/{ObjectType}/name/{name}
• キーとしてのオブジェクト ID:Rest//{package}/{ObjectType}/id/{id}
• オブジェクト タイプごとに 1 つのインスタンス。キーは不要: 例:REST/common/ACSVersion
|
|
|
---|---|---|
一部のメソッドでは、URL に追加のデータがあります。 表 4-3 を参照 |
||
一部のメソッドでは、URL に追加のデータがあります。 表 4-3 を参照 |
HTTP メソッドは、設定操作(CRUD:作成、読み取り、更新、および削除)にマッピングされます。
一般的な固有のメソッドは、URL 内で指定されず、HTTP 要求メソッドによって決定されます。その他の場合は、URL に設定操作を追加する必要があります。HTTP メソッドは、ACS 操作にマッピングされます。
• HTTP GET:1 つのオブジェクトまたは複数のオブジェクトを表示します。
• HTTP PUT:既存のオブジェクトを更新します。PUT は、外部のメソッド(CRUD 以外)を呼び出すためにも使用されます。
CRUD 以外の操作に対して HTTP PUT メソッドを使用する場合は、URL で要求する操作を指定します。これは、更新のための PUT メソッドからのメッセージを区別するためにも使用されます。キーワード「op」は、次のように URL に含まれます。
Rest/{package}/{ObjectType}/op/{operation}
例:/Rest/Identity/IdentityGroup/op/query
表 4-3 では、プライマリ ACS REST メソッドと、HTTP メッセージに対する各メソッドのマッピングについて説明します。
|
|
|
|
|
---|---|---|---|---|
/{ObjectType}/name/ |
||||
(注) 作成では、オブジェクト ID プロパティを設定しないでください。 | ||||
/{ObjectType}/name/ |
||||
update 2 |
||||
1.URL 内の名前は、フルネームです。ACS REST サービスでは、ワイルドカードまたは正規表現はサポートされていません。 2.Update メソッドは、要求の本体で提供されたオブジェクトで、オブジェクト全体を置き換えます。ただし、機密プロパティを除きます。 |
(注) 障害時の応答については、 ACS REST 結果を参照してください。
REST 要求に対する応答は、Web サービスによって返される HTTP ステータス コードとその他のデータを含む標準 HTTP 応答です。また、応答には、要求のタイプに従って、ACS REST 結果オブジェクトまたは ACS コンフィギュレーション オブジェクトが含まれることがあります。
応答の本体で予期されるオブジェクトのタイプを確認するには、HTTP ステータス コードをチェックする必要があります。
• 401 と 404 を除く 4xx HTTPS ステータス コードでは、REST 結果オブジェクトが返されます。
• 500 以外の 5xx ステータス コードでは、メッセージ コンテンツに、サーバ エラーについて説明するテキストが含まれます。
• 500 HTTP ステータス コードでは、REST 結果が返されます。
• 200 と 201 の HTTP ステータス コードでは、特定のメソッドまたはオブジェクト タイプごとにオブジェクトが返されます。
• 204 HTTP ステータス コードでは、オブジェクトは返されません。
ACS では、次のタイプのステータス コードは返されません。
HTTP ステータス コードは、HTTP 応答ヘッダー内と、REST 結果オブジェクト内で返されます。
表 4-4 には、ACS によって返される HTTP ステータス コードを示します。
|
|
|
|
---|---|---|---|
401 エラーとは異なり、認証による影響はありません。また、このエラーは、読み取り以外の要求がセカンダリ インスタンスに送信された場合にも表示されます。 |
|||
REST 要求に対する HTTP 応答には、要求したオブジェクトまたは REST 結果オブジェクトのいずれかが含まれます。詳細については、 表 4-3 を参照してください。ACS 結果には、次の項目が含まれます。
ACS は、GET メソッドおよびクエリー操作に対してオブジェクトを返します。返されるオブジェクトのタイプは、要求 URL によって決定されます。
GET メソッドが複数のオブジェクトを返す場合、これらのオブジェクトは応答に含まれます。返されるリストが長すぎる場合は、フィルタリング オプションまたはページング オプションを使用する必要があります。
WADL ファイルには、すべてのオブジェクトに対するオブジェクト構造(スキーマ)とメソッドが含まれます。
WADL ファイルは、主に文書化に役立ちます。WADL ファイルを使用して、クライアント アプリケーションを生成することはできません。
WADL ファイル構造は、W3C 仕様に従っています。詳細については、
http://www.w3.org/Submission/wadl/ を参照してください。
WADL ファイルをダウンロードするには、次の手順を実行します。
ステップ 1 ACS ユーザ インターフェイスで、[System Administration] > [Downloads] > [Rest Service] の順に進みます。
ステップ 2 ACS Rest Service WADL ファイルの下で、[Common] または [Identity] をクリックし、ローカル ドライブにファイルを保存します。
ACS には、ACS 5.3 REST インターフェイスでサポートされるオブジェクトの構造を記述した、3 つの XSD ファイルが付属しています。
– ResultResult、RestCreateResult
• クエリー オブジェクトの構造が記述された Query.xsd
スキーマ ファイルは、WADL ファイルのダウンロードと同じ方法でダウンロードできます。JAXB などの使用可能なツールとともにスキーマを使用して、スキーマ クラスを生成できます。
HTTP クライアントを開発し、またはサード パーティ HTTP クライアント コードを使用して、XSD ファイルから生成されたスキーマ クラスと統合できます。
(注) XML をコーディングするか、手動で作成するよりも、XSD ファイルから REST クライアント クラスを生成することを強く推奨します。
ACS にはクライアント アプリケーション用のコード例が用意されており、ACS REST インターフェイスと連携動作するアプリケーションの開発に役立ちます。コード例は、WADL ファイルおよびスキーマ ファイルと同じ方法でダウンロードできます。
コード例は、Apache HTTP Client( http://hc.apache.org/httpcomponents-client-ga/index.html )および XSD ファイルを利用した JAXB(xjc コマンド)で生成される Java コードに基づいています。次のコード例が含まれています。