Cisco ACE XML Gateway ユーザ ガイド
HTTP エラー応答のマッピング
HTTP エラー応答のマッピング
発行日;2012/02/01 | 英語版ドキュメント(2009/11/20 版) | ドキュメントご利用ガイド | ダウンロード ; この章pdf , ドキュメント全体pdf (PDF - 8MB) | フィードバック

目次

HTTP エラー応答のマッピング

概要

汎用 SOAP 障害オプション

SOAP 障害の名前空間設定の指定

例外通知電子メール アドレスの設定

グローバル例外の設定の指定

例外マッピング エディタのナビゲーション

グローバル例外の設定

サービス固有の例外動作の設定

ルート固有の例外処理

HTTP エラー応答のマッピング

この章では、ACE XML Gateway でサービス エラーを処理する方法について説明します。内容は次のとおりです。

「概要」

「汎用 SOAP 障害オプション」

「グローバル例外の設定の指定」

「サービス固有の例外動作の設定」

概要

HTTP エラー応答または例外は、要求が想定どおりに処理できなかったことを示すために、クライアントに送信されるメッセージです。例外は、要求、正常ではない要求、使用できないサービスや、その他多くの不十分なクレデンシャルを含む、多様な条件によって発生することがあります。一般的に、このようなエラーは、プロトコル仕様の一部として定義されています。

ACE XML Gateway の観点から、例外は、次の 2 つの方法の 1 つで生成されます。

内部的に、ACE XML Gateway そのものによって

外部的に、リモートに生成される、通常はバックエンド サーバまたはネットワークによって

異なるプロトコルを使用するサービスのユーザとプロバイダーの間を仲介するため、ACE XML Gateway では、1 つの形式の例外から別の形式の例外へと、同様に仲介できる必要があります。ACE XML Gateway ポリシーでは、たとえば、SOAP から一般的な HTTP または HTTP から MQSeries など、サポートするすべてのプロトコルの例外タイプ間でのデフォルトのマッピングが定義されます。

ただし、同じプロトコルを使用するクライアントおよびサービスでも、ACE XML Gateway によって実行される例外マッピングにより、クライアントによって受信された例外が正規化されます。

一部の場合、デフォルト例外マッピングを変更する必要が生じることがあります。これによって、(バックエンド システムの詳細を隠すことによって)セキュリティを改善でき、クライアントの例外処理が簡素化されます。

デフォルト例外マッピング以外に、例外の特定のタイプに対して、次の拡張機能を指定できます。

例外メッセージがマッピングされないか、ACE XML Gateway で変更される、リモート例外パススルー。

例外での応答処理。サービス固有のマッピングでは、応答として処理されるリモート生成の応答メッセージを使用できます。それ以外の場合、エラー応答では、サービスの応答に設定された処理および検証の仕様が回避されます。このオプションでは、XSLT の例外メッセージへの適用など、応答として例外にアクセスできます。

ここでは、これらのオプションの詳細について説明します。

汎用 SOAP 障害オプション

例外マッピング以外に、ACE XML Gateway では、SOAP 障害の名前空間設定や障害イベントの電子メール通知など、例外処理を他のいくつかの観点から設定できます。

SOAP 障害の名前空間設定の指定

Gateway からの通常の SOAP 障害メッセージは、次のように表示されます。

例 22-1 SOAP 障害

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Forbidden</faultstring>
<faultactor>internal-firewall</faultactor>
<detail xmlns:det="http://example.com/">
<det:detailmessage>Forbidden. You are not allowed
to access that resource.</det:detailmessage>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

ACE XML Gateway では、デフォルトで、 障害 要素の子要素が SOAP 名前空間で認定されていない SOAP 障害が生成されます。認定されていない 障害 要素は、Web Services-Interoperability(WS-I)仕様に準拠しています。

ACE XML Gateway では、オプションで、認定されている 障害 要素を生成できます。これらの名前空間設定を行うには、[System Management] > Gateway [Settings] ページにアクセスし、[SOAP XML Namespace Configuration] 設定を変更します。

SOAP 障害の生成方法に適用される設定には、次のものが含まれます。

[SOAP fault detail entry name]。SOAP 障害の detail 要素の 1 つ目の子である要素に使用される名前は、デフォルトで、 detailmessage です。

[SOAP fault detail entry namespace]。 detail 要素の名前空間。 detail 要素は、デフォルトで、名前空間 http://reactivity.com/ によって認定されます。

これは、それぞれのユーザのケースに適合する名前空間に変更する必要があります。

[Use unqualified SOAP fault child elements]。 fault 要素の子名前空間から SOAP 名前空間プレフィクスを除外します。WS-I との互換性のため、このような要素では、名前空間プレフィクスを持つことができません。オプションは、デフォルトで、イネーブルです。ACE XML Gateway では、このオプションをディセーブルにすることによって、プレフィクスを追加できます。

例外通知電子メール アドレスの設定

ACE XML Gateway は、サービス要求の処理で例外が発生したときに、電子メール通知を送信するよう設定できます。一部のタイプのサービス トラフィックでエラー通知を設定し、一部では設定しないよう、仮想サービスによって例外通知をイネーブルにできます。

通知では、エラーによって影響を受けるメッセージが特定され、エラーの理由が示されます。メッセージは、システムでグローバルな固有識別情報であるメッセージ GUID によって特定されます。図 22-1 に、サンプルのエラー通知を示します。

通知には、エラーが発生した仮想サービスの ID についての情報が含まれます。[Policy Component Search by ID] オプションを使用すると、サブポリシーの場所に関係なく、その ID に基づいた仮想サービスを探すことができます。検索を実行するには、[Policy Manager] ページのフィールドで、16 進数の ID を入力します。詳細については、「ID によるポリシー コンポーネントの検索」を参照してください。

図 22-1 例外通知

 

例外の電子メール通知をイネーブルにするには、次の操作を実行します。


ステップ 1 [ACE XML Gateway Settings] ページで、[Exception Notifications] セクションを探します。

ステップ 2 [Exception Notifications] セクションで、次の手順でコントロールを設定します。

a. [Send e-mail for the first exception notification and every] フィールドで、通知間で発生する例外数を指定するため、間隔を入力します。デフォルト値は 1 で、各通知で電子メールを送信することを意味します。

b. [Send email regarding notifications to] フィールドで、このハンドラによる通知の送信先となる電子メール アドレスを入力します。

c. [Set the "From:" address] フィールドで、電子メールで [From:] アドレスとして表示される電子メール アドレスを入力します。

[Advanced ACE XML Gateway Settings] ページのコントロールの詳細については、ページの上部にあるヘルプ リンクをクリックします。

ステップ 3 [Save Changes] ボタンをクリックし、変更をコミットします。

[System Management] ページが再表示されます。


 

電子メールの宛先の設定後、特定のサービスに対して通知を送信するよう、電子メール通知を設定する必要があります。これを行うには、通知をイネーブルにする仮想サービス オブジェクトの [General Information Settings] で、[On Error] オプションの [log message body and send notification] を選択します。

グローバル例外の設定の指定

例外マッピングでは、ACE XML Gateway でサポートされるプロトコル間でエラー メッセージを仲介する方法が決められます。これでは、たとえば、標準 HTTP だけが使用されるクライアントによって解釈可能な例外を戻すなどの目的で、SOAP 形式でバックエンド サービスを使用できます。

マッピングでは、SOAP 障害の各タイプが、ターゲット プロトコルの例外と同等のタイプに関連付けられます。ACE XML Gateway は、適切なマッピングで事前に構成されています。ただし、一部の場合、特定の結果に到達するため、デフォルトのマッピングを変更する必要が生じることがあります。

例外マッピングは、特定のハンドラとサービス記述子のペアに対し、グローバルに、また、サービス レベルで、指定できます。ACE XML Gateway でエラーまたは他の例外条件が検出されると、サービス固有の(またはルートごとの)マッピングが、まずチェックされます。発生した例外に一致するルートでマッピングが定義されている場合、ACE XML Gateway により、マッピングで指定されたメッセージで応答されます。次に、ルートごとにマッピングがある場合、ACE XML Gateway により、現在定義されているグローバル例外マッピングが検索されます。

Exception Mapping エディタを使用すると、システムでサポートされるプロトコル間で、例外メディエーション マッピングを設定できます。また、例外応答のデフォルト コンテンツも変更できます。

例外マッピング エディタのナビゲーション

Exception Mapping エディタを参照するには、操作メニューで [Exception Mapping Defaults] リンクをクリックします。HTTP プロトコル例外マッピングは、ページに表示されます。別のプロトコルのマッピングを表示するには、[HTTP]、[SOAP]、[TIB/RV]、[MQ]、または [Other] の、[Mappings for handlers of type] リンクの 1 つをクリックし、そのタイプのハンドラに定義されている例外マッピングを参照します。

実行時の例外は、リモートまたは内部とラベルに記されていることに注意してください。リモート エラーは、バックエンド サーバまたはネットワークなどの、外部リソースによって生成されます。内部例外は、ACE XML Gateway そのものによって生成されます。

リモートに生成される例外で使用可能な特別設定オプションがあるため、これは重要な区別です。特に、例外を、標準応答メッセージを介して渡すか、または、標準応答メッセージとして処理することができます。この場合、通常の応答処理が適用されます。

グローバル例外の設定

ここでは、グローバル例外設定を指定する方法を説明します。グローバル設定は、特定の設定が存在しないすべてのハンドラに適用されます。

グローバルなデフォルト例外マッピングを変更するには、次の操作を実行します。


ステップ 1 ACE XML Manager で、 Administrator ユーザまたはコンソールの Routing ロールを持つ Privileged ユーザとして、操作メニューで [Exception Mapping Defaults] リンクをクリックします。

ステップ 2 ページの上部にある [HTTP]、[SOAP]、[TIB/RV]、[MQ]、または [Other] のリンクから該当するリンクをクリックし、例外マッピングを編集するハンドラ タイプを選択します。

たとえば、SOAP 1.1 Document ハンドラによって生成された例外をカスタマイズするには、または、SOAP 1.1 Document ハンドラへのサービス要求にマッピングするには、[SOAP] リンクをクリックします。

ステップ 3 例外マッピングを編集するため、リストが表示されているカテゴリ(Access、Network、Protocol、Runtime)から、例外のタイプを探します。一部のサービスでは、要求または応答の両方で例外マッピングを編集できます。

ステップ 4 編集する例外マッピングの横にある [Customize] ボタンをクリックします。

ステップ 5 リモートに生成される特定の例外タイプでは、次のオプションが使用可能です(サービスおよびハンドラのプロトコルによって、ラベルが異なることに注意してください)。

[Pass the entire error message through exactly as received from the service]。マッピングは実行されません。バックエンドからの例外は未変更で渡されます。このオプションが選択されている場合、ページの他の設定フィールドはグレー表示されます。

[Return the following SOAP Fault to the consumer]。これはデフォルト動作で、バックエンド サービスからの例外は、ページのマッピング設定で指定されているとおりに ACE XML Gateway で再生成されます。


) サービス固有のリモート例外では、バックエンド システムからの例外処理の追加オプションが標準要求としてあり、通常の応答に適用されるすべての設定は、たとえば、コンテンツ画面や XSLT 処理などを含む、例外メッセージに適用されます。詳細については、「サービス固有の例外動作の設定」を参照してください。


ステップ 6 戻すエラー コードを指定するには、[Map To Response Code] メニューから項目を選択します。

異なるハンドラに対する応答により、プロトコル固有の異なるオプションが用意されます。一部のプロトコルでは、複数の応答コード メニューが用意されています。たとえば、一部の SOAP ハンドラでは、HTTP 応答コード、SOAP 1.1 障害コード、および SOAP 1.2 障害コードに、例外をマッピングできます。

ステップ 7 オプションで、デフォルトの応答メッセージを編集できます。

一部のメッセージ本文のフィールドを使用すると、フィールド値で %s 変数を使用できます。ACE XML Gateway では、元のエラー メッセージのテキストの変数が、例外の発信元から受信したものに置き換えられます。

%s 変数を使用すると、LDAP システムからのエラー情報を渡すことができます。詳細については、「Active Directory LDAP クエリー検証の設定」を参照してください。エディタでは、ページの下部で、そのテキスト フィールドに %s 変数が使用可能かどうかを示す注意が表示されます。

ステップ 8 [Save Changes] をクリックし、現在のポリシーに新しい例外マッピングをコミットします。


 

グローバル例外マッピングを変更してポリシーを導入した後、該当する例外タイプにより特化した設定がハンドラで発生しない場合、ACE XML Gateway では、編集した例外が検出されるたびに設定が使用されます。

サービス固有の例外動作の設定

このセクションで説明されているように、各ルートでは、特定のルートだけに対するグローバル例外設定を上書きするカスタム例外を定義できます。ただし、この機能は、基本仮想サービスではなく、拡張仮想サービス オブジェクト(つまり、別のハンドラおよびサービス記述子で構成されているもの)でだけ使用可能です。

ルート固有の例外処理

ルートに対してカスタム例外マッピングを設定するには、次の操作を実行します。


ステップ 1 Administrator ユーザまたは Routing ロールを持つ Privileged ユーザとして、ACE XML Manager Web コンソールにログインします。

ステップ 2 必要に応じ、編集するハンドラを用意するものに対して、アクティブなサブポリシーを設定します。

ステップ 3 操作メニューで [Virtual Services] リンクをクリックします。

ステップ 4 設定するハンドラの名前をクリックします。

ハンドラの情報ページが表示されます。

ステップ 5 ページの中ほどにある [Routes] セクションの [Custom Exceptions] ペインで、編集するリンクをクリックします。

ステップ 6 [Custom Route Exceptions] ページで、カスタマイズする例外の名前の横に表示されている [Customize...] ボタンをクリックします。

Web コンソールでは、例外をカスタマイズするエディタが表示されます。

ステップ 7 例外エディタのコントロールを使用して、指定した例外が検出された場合にハンドラによって戻されるカスタム応答を指定します。

この画面の内容は、編集する例外ハンドラによってさまざまです。ただし、サービスおよびハンドラのタイプによって、次のオプションが使用できます(サービスおよびハンドラのプロトコルによって、ラベルが異なることに注意してください)。

[Pass the entire error message through exactly as received from the service]。マッピングは実行されません。バックエンドからの例外は未変更で渡されます。このオプションが選択されている場合、ページの他の設定フィールドはグレー表示されます。

[Return the following SOAP Fault to the consumer]。デフォルト動作で、バックエンド サービスからの例外は、ページのマッピング設定で指定されているとおりに ACE XML Gateway で再生成されます。オプション ボタンが表示されない場合、これはデフォルト動作です。エディタにあるコントロールを使用して、特定の例外条件が検出されたときに、ハンドラによって戻される理由コード、理由、メッセージ本文を編集できます。

サービス レベルのカスタマイゼーションには、次に挙げる別のオプションが追加されています。

[Run response processing on SOAP Fault received from the service]。バックエンド サービスから通常の応答処理操作で受信した例外のサブジェクト。これにより、XSLT、変換の拡張、コンテンツ スクリーニングを含む通常の応答で使用できるいかなる機能によっても、応答を処理または検証できるようになります。

応答処理のために設定する場合、HTTP 応答コード "200 OK" でクライアントに障害応答が送信されます。ただし、SNMP トラップのエラー ロギングまたは実稼動など、ACE XML Gateway での SOAP 障害による他の副次的な影響はありません。

ステップ 8 [Save Changes] ボタンをクリックし、変更をコミットします。

カスタム例外ハンドラは、[Custom Route Exceptions] ページで強調表示されます。すでにカスタマイズされたハンドラでは、[Customize] ボタンの位置に [Edit] ボタンおよび [Reset] ボタンが表示され、これは次のように使用されます。

カスタム例外処理をさらに変更するには、[Edit] ボタンをクリックします。

この例外のデフォルト処理に戻すには、[Reset] ボタンをクリックします。要求を確認するように求めるダイアログボックスが表示されます。[OK] を選択すると、ACE XML Manager では、このハンドラのデフォルト例外処理動作に戻され、この変更が [Custom Route Exceptions] ページに反映されます。

ステップ 9 変更を加えずに [Custom Route Exceptions] ページを終了するには、[Done] ボタンをクリックします。

ハンドラ情報ページにある [Routes] セクションの [Custom Exceptions] ペインに、このルートに対して設定されているカスタム例外ハンドラの数が表示されます。