AquaLogic Service Bus Console の使い方
|
 |
 |
|
プロキシ サービスは、AquaLogic Service Bus サーバ上にローカルに実装されるサービスの定義です。アクションを使用すると、パイプラインやプロキシ サービスのルート ノードとブランチ ノードのメッセージ フローを設計およびコンフィグレーションできます。
ここでは、パイプラインのステージ、ルート ノード、ブランチ ノードへのアクションの追加、および AquaLogic Service Bus で使用できる各アクションについて説明します。内容は以下のとおりです。
[ステージ コンフィグレーションの編集] ページでは、アクションを追加できます。アクションとは、プロキシ サービス内のメッセージ フローでのメッセージの処理を定義するパイプライン ステージおよびルート ノードとブランチ ノードの要素です。メッセージ フローの詳細については、「メッセージ フローの概要」を参照してください。
注意 : アクションを追加する前に、パイプライン ペア ノードを作成し、ステージを追加する必要があります。詳細については、「パイプライン ペア ノードの追加」および「ステージの追加」を参照してください。
次の表は、AquaLogic Service Bus メッセージ フローについてコンフィグレーションできるアクションと、そのアクションについて説明する (コンフィグレーション方法も含む) トピックへのリンクを示しています。
表 16-1 AquaLogic Service Bus のアクション
|
|
|
|
|
|
アクションをコンフィグレーションしたら、[ステージ コンフィグレーションの編集] ページに戻って、次の手順に示すように、アクション、ブランチ ノード、エラー ハンドラの追加やアクションの更新などを行うことができます。
表 16-2 ステージ コンフィグレーションの編集時に使用するタスク
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
注意 : [保存] をクリックすると、メッセージ フローは現在のセッション内で更新されます。コンフィグレーションに対する変更が完了したら、左側のナビゲーション ペインで、[Change Center] の下にある [アクティブ化] をクリックします。セッションが終了し、コンフィグレーションが保存されます。または、セッション中の任意の時点で [破棄] をクリックして、現在のセッションでそれまでに行った変更内容を削除します。
注意 : アクションの詳細については、については、BEA AquaLogic Service Bus の『ユーザーズ ガイド』にある「AquaLogic Service Bus でのメッセージ フローの作成」で、アクションの使用例、設計パターン、ベスト プラクティスを参照してください。
更新アクションには、削除、名前変更、挿入、置換などのアクションがあります。これらのアクションは、次のように評価され、実行されます。
XQuery 式の結果をコンテキスト変数に割り当てるには、割り当てアクションを使用します。
割り当てアクションをコンフィグレーションするには、以下の手順を実行します。
削除アクションは、コンテキスト変数または XPath 式で指定したすべてのノードを削除するときに使用します。削除アクションは一連の更新アクションの 1 つです。詳細については、「更新アクション」を参照してください。
削除アクションをコンフィグレーションするには、以下の手順を実行します。
また、XPath 式で選択されたすべてのノードを削除するには、XPath オプションに関連付けられたラジオ ボタンを選択し、[XPath] をクリックします。[XPath 式エディタ] ページが表示されます。詳細については、「XPath 式エディタの使用」を参照してください。式を保存したら、[変数] フィールドにコンテキスト変数を入力します。コンテキスト変数の詳細については、「メッセージ コンテキスト」を参照してください。
値のシーケンスを反復処理してアクションのブロックを実行するには、For Each アクションを使用します。
For Each アクションをコンフィグレーションするには、以下の手順を実行します。
図 16-1 For Each アクションのコンフィグレーション オプション
value 変数、index 変数、total 変数、および XPath 式の値は、指定を省略可能です。つまり、アクションの設計時にこれらの値を指定していなくても、セッションをアクティブ化することができます。
注意 : For Each アクションでのコンテキスト変数のスコープについては、「For Each アクションでの変数のスコープ」と「ネストされた For Each アクション」を参照してください。
value コンテキスト変数は、For Each アクション内でのみ参照できます。For Each アクションの実行が終了 (正常に終了するか、またはエラーで終了) すると、value 変数はスコープから外れ、メッセージ コンテキストから削除されます。ただし、For Each アクションの実行が終了すると、index 変数と total カウント変数は、前回の値のままコンテキスト内に残ります。For Each アクションが正常に終了すると、index 変数と total カウント変数の値は同じ数値 (シーケンス内の項目の合計数) になります。
反復の処理中にエラーが発生した場合、index 変数の値が total カウント変数の値よりも小さくなります。ただし、最後の反復の処理中は、index は total カウントと同じ値になります。したがって、エラーが発生し、index の値と total の値が等しい場合は、最後の反復処理中か、For Each アクションの正常終了後のいずれかにエラーが発生したということだけを判断できます。
Do() ループでは、どの変数 (value、index、または total) を変更することもできます。
XPath の実行結果として返されるシーケンス内の値は、XPath が実行される変数 (上の図の例では body) のコンテンツへの参照であるため、For Each ループのアクションによって実行される value 変数に対するすべての更新は、body のコンテンツに反映されます。したがって、「挿入」と「更新アクション」で実行するよりも複雑なインプレース更新を実行できます。
たとえば、次の図のようにコンフィグレーションされた For Each アクションでは、注文書の品目のシーケンスを反復処理して、各項目の原価を 10% ずつ増やします。
図 16-3 For Each アクションのコンフィグレーションの例
各反復処理の開始時に、index 変数の値は、次の index の値で上書きされます。つまり、ループの動作と実行される反復処理の回数は、index 変数の値のループで行われる変更による影響を受けません。
ネストされた For Each アクションをコンフィグレーションできます。そのようなアクションをコンフィグレーションする場合は、可能な限りユニークな変数名を使用することをお勧めします。ネストされた For Each アクションの変数を再利用する場合は、変数のスコープを確認してください。前の節で説明したように、次のような注意点があります。
XQuery 式のブール結果に基づき、1 つまたは複数のアクションを条件付きで実行するには、If Then アクションを使用します。
If Then アクションをコンフィグレーションするには、以下の手順を実行します。
作成した条件は、then() 句に入る前に、標準の if...then ロジックに従って実行されるテストとして使用されます。詳細については、「XQuery 条件エディタの使用」を参照してください。
注意 : 条件アクションはネスト可能です。ただし、ステージ エディタでは、ネストは 4 累積レベルまでに制限されています。5 番目のレベルを追加しようとしても、そのネスト アクションは表示されません。累積レベルには、すべてのブランチ アクション (If... Then... 条件、パブリッシュ テーブル、ルート テーブル) が含まれます。たとえば、2 レベルの条件と、ルート テーブルを含むパブリッシュ テーブルを使用して、合計 4 レベルにすることができます。ただし、別の条件付きのアクションを追加 (最後のパブリッシュ テーブルに対して) しようとしても、そのアクションは表示されません。
XPath 式で選択したノードを基準に、指定した位置に XQuery 式を挿入するには、挿入アクションを使用します。挿入アクションは更新アクションの 1 つです。詳細については、「更新アクション」を参照してください。
挿入アクションをコンフィグレーションするには、以下の手順を実行します。
注意 : 有効なコンフィグレーションには、以下のコンフィグレーションが含まれます。
ログに記録するメッセージを作成し、ログに使用する一連の属性を定義するには、ログ アクションを使用します。このトピックには、以下の節があります。
ログ アクションを使用すると、プロキシ サービス内でステージが実行されるたびに、1 つまたは複数のメッセージを WebLogic Server ログに記録することができます。ログ アクションの 1 つまたは複数のインスタンスをメッセージ フローでコンフィグレーションすることができます。
ログ メッセージのコンテンツは、以下の 1 つまたは複数の要素で構成できます。
AquaLogic Service Bus では、非カタログ ロガー API を使用して、メッセージを WebLogic Server ログに書き込みます。AquaLogic Service Bus Console では、WebLogic Server Administration Console が提供するロギング コンフィグレーション機能をレプリケートしません。以下に示すような特定のログ ファイル コンフィグレーションが必要な場合は、WebLogic Server Administration Console を使用してコンフィグレーションを行ってください。
WebLogic Server のログについては、WebLogic Server ドキュメントの『ログ ファイルのコンフィグレーションとログ メッセージのフィルタ処理』を参照してください。
ログ アクションをコンフィグレーションするには、以下の手順を実行します。
メッセージのターゲット サービスを指定し、メッセージのパッケージおよびサービスへの送信方法をコンフィグレーションするには、パブリッシュ アクションを使用します。このトピックには、以下の節があります。
以下のサービス品質およびメッセージ コンテキスト情報のスコープは、パブリッシュ アクションとパブリッシュ テーブル アクションに適用されます。
パブリッシュ アクションまたはパブリッシュ テーブル アクションの結果としてメッセージが別のサービスにパブリッシュされると、プロキシ サービス着信転送と発信パブリッシュ アクションで JMS/XA 転送を使用している場合は、デフォルトのサービス品質 (QoS) は best effort になります。「best effort」では、メッセージ処理の信頼性が低く、メッセージの重複が防止されませんが、パフォーマンスは最適化されます。デフォルトの best effort サービス品質属性をオーバーライドするには、発信メッセージのコンテキスト変数 ($outbound) に qualityOfService を設定する必要があります。詳細については、「メッセージ コンテキスト」を参照してください。exactly once の信頼性については、「ルート ノードの追加」を参照してください。
サービス品質の詳細については、BEA AquaLogic Service Bus の『ユーザーズ ガイド』の「AquaLogic Service Bus でのメッセージ フローの作成」を参照してください。
各パブリッシュ トランスフォーメーションでは、メッセージ コンテキストのローカル コピーが独自に保持されます。パブリッシュ要求アクション内の事前定義されたコンテキスト変数に対する変更は、そのパブリッシュのエンドポイントまでに限定され、メッセージ フローによる以降の処理には影響しません。
操作手順を示すため、AquaLogic Service Bus が SOAP メッセージと添付 (SOAP、テキスト、バイナリの 3 つの部分) を受信するシナリオを想定した、パブリッシュ アクションでのメッセージ コンテキストの処理に関する質問とそれに対する回答を以下に示します。
保持されません。パブリッシュ アクションで発信メッセージに加えた変更は、パブリッシュされたメッセージにのみ反映されます。つまり、パブリッシュ アクションで行った変更は、メッセージ フローがパブリッシュ アクションを含むステージ以降のノードに進む前にロール バックされます。
ただし、パブリッシュ要求アクションの 1 つとして応答アクションをコンフィグレーションする場合は、このルールの例外です。この場合、メッセージ コンテンツはロール バックされません。つまり、パブリッシュされたメッセージとして送信されたメッセージは、応答アクションが実行された結果としてクライアントに返されたメッセージです。たとえば、次のように、ステージにコンフィグレーションされたアクションのシーケンスが割り当てと応答であるケースを考えます。
実行時にこのステージが実行されると、クライアントは応答メッセージで message_x を受け取ります。
ファイル システムに作成されるメッセージの種類は、以下のように発信サービスのタイプによって異なります。
<soap:Envelope>) をルートとする完全なマルチパート MIME メッセージが作成される(詳細については、「SOAP サービス」を参照)。$body のコンテンツをルートとする完全なマルチパート MIME メッセージが作成される(詳細については、「XML サービス (非 SOAP)」および「メッセージング サービス」を参照)。転送ヘッダを設定する必要はありません。サービス タイプに応じて、Content-Type が自動的に設定されます。詳細については、「attachments コンテキスト変数の初期化」を参照してください。
パブリッシュ アクションをコンフィグレーションするには、以下の手順を実行します。
パブリッシュ テーブルとは、切り替え式の条件テーブルに含まれる一連のルートであり、単一の XQuery 式の結果に基づいて各種ルートを選択できる簡単な構文です。メッセージのターゲット サービスを指定し、メッセージのパッケージおよびサービスへの送信方法をコンフィグレーションするには、パブリッシュ テーブル アクションを使用します。
デフォルトのサービス品質およびパブリック アクションのメッセージ コンテキストのスコープについては、「パブリッシュ アクションについて」を参照してください。
注意 : ステージ エディタでは、ネストは 4 累積レベルまでに制限されています。5 番目のレベルを追加しようとしても、そのネスト アクションは表示されません。累積レベルには、すべてのブランチ アクション (If... Then... 条件、パブリッシュ テーブル、ルート テーブル) が含まれます。たとえば、2 レベルの条件と、ルート テーブルを含むパブリッシュ テーブルを使用して、合計 4 レベルにすることができます。ただし、別の条件を追加 (最後のパブリッシュ テーブルに対して) すると、その条件は表示されません。
パブリッシュ テーブル アクションをコンフィグレーションするには、以下の手順を実行します。
指定したエラー コード (文字列) と説明を使用して例外を発生させるには、エラーを発生させるアクションを使用します。
エラーを発生させるアクションをコンフィグレーションするには、以下の手順を実行します。
エラー処理アクションの詳細については、「エラー メッセージと処理」を参照してください。
XPath 式で選択された要素のコンテンツを変更せずに要素名を変更するには、名前変更アクションを使用します。名前変更アクションは更新アクションの 1 つです。詳細については、「更新アクション」を参照してください。
名前変更アクションをコンフィグレーションするには、以下の手順を実行します。
詳細については、「XPath 式エディタの使用」を参照してください。
XPath 式で指定されたノードまたはノードのコンテンツを置き換えるには、置換アクションを使用します。ノードまたはそのコンテンツは、XQuery 式が返した値で置換されます。
置換アクションでは、単純な値や要素を置き換えることができます (XQuery 式は属性を返すことができません)。XPath で属性が指定される場合は、XQuery 式で単純な値に評価する必要があります。XQuery 式から何も返されない場合、指定されたノードが空になるか、指定された属性が削除されます。
置換アクションは更新アクションの 1 つです。詳細については、「更新アクション」を参照してください。
置換アクションをコンフィグレーションするには、以下の手順を実行します。
返信アクションは、要求パイプライン、応答パイプライン、またはエラー パイプラインで使用できます。成功時または失敗時の返信をコンフィグレーションできます。失敗の場合、SOAP サービスでは、HTTP 500 エラーが返されます。返信アクションでは、呼び出し元に即時に返信されるように指定します。
返信アクションをコンフィグレーションするには、以下の手順を実行します。
エラー処理アクションの詳細については、「エラー メッセージと処理」を参照してください。
パブリッシュ アクション要求アクションの 1 つとしての応答アクションの使用については、「パブリッシュ」の「メッセージ コンテキストのスコープ」を参照してください。
プロキシ サービスのメッセージ レポートを有効にするには、レポート アクションを使用します。
AquaLogic Service Bus には、メッセージ データを配信する機能があります。また、1 つまたは複数のレポート プロバイダにアラートを送信します。メッセージ データは、メッセージの本体またはメッセージに関連付けられた他の任意の変数 (ヘッダまたは inbound 変数など) から取り込むことができます。アラート データには、プロキシ サービスをモニタするためにコンフィグレーションできるサービス レベル アグリーメント (SLA) の違反または発生に関する情報が含まれます。レポート プロバイダに配信されるメッセージまたはアラート データは、メッセージのトラッキングや規定の監査などの機能に使用できます。
AquaLogic Service Bus JMS レポート プロバイダまたはユーザ定義のレポート プロバイダからレポート メッセージを受信するには、プロキシ サービスのメッセージ フローで、最初にレポート アクションを作成する必要があります。レポート アクションを使用すると、各メッセージから情報を抽出して、それをレポート データ ストリームに書き込むことができます。
アラート レポート用のレポート アクションをコンフィグレーションする必要はありません。アラート データは常にレポート データ ストリームで使用可能です。
レポート アクションをコンフィグレーションするには、以下の手順を実行します。
キー値のペアは、メッセージ コンテキスト変数やメッセージ ペイロードからキー識別子を抽出して、残りのメッセージを無視する場合に使用します。キーは、メッセージを識別する便利な手段となります。キーは、[レポート] モジュールでレポート インデックスとして表示されます。詳細については、「メッセージの表示と検索」および「メッセージの詳細の表示」を参照。
レポート アクションのコンフィグレーションおよび AquaLogic Service Bus ダッシュボードで報告されるデータの例については、「レポート アクションのコンフィグレーションおよび生成されるレポート データの例」を参照してください。
ステージのエラー ハンドラでレポート アクションをコンフィグレーションする例を示します。目的は、エラーが発生した場合に fault コンテキスト変数のコンテンツを報告することです。次の図に示すようにレポート アクションをコンフィグレーションします。
ここで、errorCode はキー名を表し、キー値は ./ctx:errorCode という XPath を使用して fault 変数から抽出されます。
実行時にこのレポート アクションが行われるたびに、レポート データ ストリームを通じてメッセージが報告されます。次の図は、図 16-4 に示すキーと値のペアでコンフィグレーションされたレポート アクションが 2 回実行された後の、AquaLogic Service Bus Console の [メッセージ レポートの概要] ページを示しています。
再開アクションはエラー ハンドラ内で使用します。実行時、このアクションによって、エラーが発生しなかった場合と同様にメッセージ フローの処理が続行されます。処理はエラー ハンドラがコンフィグレーションされているノードまたはステージの後から続行されます。以降のメッセージ フロー ロジックで要求される変数およびメッセージの状態に対応するようにコンテキスト変数とメッセージの状態を設定するために、エラー ハンドラに調整ロジックをコンフィグレーションすることが必要な場合があります。調整ロジックは再開アクションの前にコンフィグレーションします。
このアクションにパラメータはありません。このパラメータはエラー パイプラインでのみ使用できます。メッセージ フローの再開アクションを作成するには、以下の手順を実行します。
エラー処理アクションの詳細については、「エラー メッセージと処理」を参照してください。
AquaLogic Service Bus に登録済みのプロキシ サービスまたはビジネス サービスの同期 (ブロック) 呼び出しをコンフィグレーションするには、サービス コールアウト アクションを使用します。このトピックには、以下の節があります。
サービス コールアウトを使用すると、あるプロキシ サービスから別のサービスへのコールアウトを行うことができます。呼び出されるサービスの入力パラメータはプロキシ サービスのメッセージ コンテキストから作成され、呼び出されるサービスからの出力はメッセージ コンテキストにマッピングされます。コールアウトが行われるサービスは、以下の特性を持っている必要があります。
SOAP ドキュメント スタイル、XML (mime:mimeXml 本体とバインドしている HTTP)、および SOAP RPC スタイル (SOAP 1.1) の Web サービスのみサポートされます。SOAP RPC/リテラルがサポートされ、SOAP RPC/コード化は SOAP RPC/リテラルとして解釈されます。
注意 : コールアウトが行われているサービスのエンドポイントの URI は、WSDL の soap:address 要素で指定した URI と同じにすることができますが、異なる URI にすることもできます。
発信要求では、AquaLogic Service Bus バインディング レイヤを使用して、要求のペイロードをサービス タイプに基づいて正しく作成します。また、バインディング レイヤを通じて WS-Security がサポートされます。
サービス コールアウト アクションのコンフィグレーション時に指定する転送ヘッダに加え、以下のヘッダが AquaLogic Service Bus バインディング レイヤによって自動的に追加されます。
をクリックし、[新しいケースの挿入] を選択します。
Content-Type = text/xml + charset (HTTP/HTTPS サービスの場合)charset パラメータは、ビジネス サービスのコンフィグレーションに応じて設定されます。
サービス コールアウト アクションのコンフィグレーション時に Content-Type 転送ヘッダの値を指定すると、デフォルトの text/xml 値ではなく、指定した値が使用されます。
SOAPAction (SOAP ドキュメント スタイルまたは SOAP RPC スタイルの HTTP/HTTPS サービスの場合)サービスと操作を指定してコンテキストを入力し、コンテキスト変数を入力して呼び出し入力と出力パラメータにバインドします。
警告 : 入力変数にはコアのペイロード ドキュメントだけを指定します。SOAP パッケージは、AquaLogic Service Bus によって自動的に作成されます。そのため、入力ドキュメントを <soap-env:Body>...</soap-env:Body> でラッピングしないでください。
たとえば、この要求パラメータに使用される body 入力変数を作成する場合は、$body (soap-env:Body ラッパーが保持されます) ではなく、body/* (ラッパー soap-env:Body を削除します) という XPath を使用して、その変数のコンテンツを定義します。
ドロップダウン リストには、事前定義されたすべてのターゲット転送のヘッダ名が入力されます (たとえば、HTTP 転送の場合は Content-Type、JMS 転送の場合は JMSCorrelationID など)。[その他] フィールドにヘッダ名を入力し、そのヘッダ名がこのサービスの転送の事前定義されたヘッダでない場合、そのヘッダは転送仕様の定義のとおりユーザ ヘッダになります。
text/xml) または複雑な XQuery 式あるいは XSLT 式を使用できます。AquaLogic Service Bus 転送レイヤでは、すべてのヘッダの XML 表現を文字列値として定義するため、式の結果は、ヘッダの値が設定される前に文字列に変換されます。何も返さない式のヘッダの値は、空の文字列に設定されます。式を使用してヘッダを削除することはできません。
警告 : このアクションで指定できるすべての転送ヘッダとメタデータが実行時に使用されるわけではありません。つまり、特定のヘッダとメタデータの値は、上書きされる場合や、AquaLogic Service Bus ランタイムで無視される場合があります。特定の転送についてどのヘッダとメタデータを設定できるか、および実行時にどのヘッダとメタデータのセットが使用されるかについては、「ランタイムでの転送ヘッダの設定の使用方法について」を参照してください。
注意 : 指定する転送ヘッダに加え、その他のヘッダが AquaLogic Service Bus バインディング レイヤによって追加されます。詳細については、「転送ヘッダに関する注意事項」を参照してください。
変数とメッセージ コンテキストがサービス コールアウトでどのように使用されるかを示す例については、「サービス コールアウトのメッセージの作成方法」を参照してください。
サービス (SOAP ドキュメント スタイルのサービスの場合) に送信される SOAP メッセージの本体、またはサービス タイプが任意の XML の場合に送信される XML メッセージの本体を作成する変数は、実行時に評価されます。
警告 : 入力変数にはコアのペイロード ドキュメントだけを指定します。SOAP パッケージは、AquaLogic Service Bus によって自動的に作成されます。そのため、入力ドキュメントを <soap-env:Body>...</soap-env:Body> でラッピングしないでください。
たとえば、この要求パラメータに使用される body 入力変数を作成する場合は、$body (soap-env:Body ラッパーが保持されます) ではなく、body/* (ラッパー soap-env:Body を削除します) という XPath を使用して、その変数のコンテンツを定義します。
![[ヘッダを追加]](wwimages/transportheader_action3.gif "[ヘッダを追加]")
ctx:binary-content 要素が必要である。 ドロップダウン リストには、事前定義されたすべてのターゲット転送のヘッダ名が入力されます (たとえば、HTTP 転送の場合は Content-Type、JMS 転送の場合は JMSCorrelationID など)。[その他] フィールドにヘッダ名を入力し、そのヘッダ名がこのサービスの転送の事前定義されたヘッダでない場合、そのヘッダは転送仕様の定義のとおりユーザ ヘッダになります。
![[ヘッダを追加]](wwimages/servicecallout_anysoap.gif "[ヘッダを追加]")
text/xml) または複雑な XQuery 式あるいは XSLT 式を使用できます。AquaLogic Service Bus 転送レイヤでは、すべてのヘッダの XML 表現を文字列値として定義するため、式の結果は、ヘッダの値が設定される前に文字列に変換されます。何も返さない式のヘッダの値は、空の文字列に設定されます。式を使用してヘッダを削除することはできません。
警告 : このアクションで指定できるすべての転送ヘッダとメタデータが実行時に使用されるわけではありません。つまり、特定のヘッダとメタデータの値は、上書きされる場合や、AquaLogic Service Bus ランタイムで無視される場合があります。特定の転送についてどのヘッダとメタデータを設定できるか、および実行時にどのヘッダとメタデータのセットが使用されるかについては、「ランタイムでの転送ヘッダの設定の使用方法について」を参照してください。
注意 : 指定する転送ヘッダに加え、その他のヘッダが AquaLogic Service Bus バインディング レイヤによって追加されます。詳細については、「転送ヘッダに関する注意事項」を参照してください。
変数とメッセージ コンテキストがサービス コールアウトでどのように使用されるかを示す例については、「サービス コールアウトのメッセージの作成方法」を参照してください。
AquaLogic Service Bus がサービス コールアウト アクションを通じてサービスを呼び出す場合は、メッセージ コンテキストの変数の値を使用してメッセージのコンテンツが作成されます。発信メッセージのメッセージ コンテンツは、ターゲット サービスのタイプに応じて異なって処理されます。以下のトピックで説明されているように、メッセージ コンテンツの作成方法はターゲット サービスのタイプによって異なります。
SOAP ドキュメント スタイルのサービスの場合の特徴は以下のとおりです。
SOAP ドキュメント スタイルのサービスへのコールアウト時のメッセージの作成方法を説明するために、次の図のようにコンフィグレーションされたサービス コールアウト アクションを例として示します。
図16-6 SOAP ドキュメント スタイルのサービスのサービス コールアウト アクションのコンフィグレーション
また、実行時に要求ドキュメント変数 myreq が次の XML にバインドされていることを前提とします。
コード リスト 16-1 要求変数 (myreq) のコンテンツ
<sayHello xmlns="http://www.openuri.org/">
<intVal>100</intVal>
<string>Hello AquaLogic</string>
</sayHello>
実行時に、SOAP 要求ヘッダ変数 reqheader は次の SOAP ヘッダにバインドされます。
コード リスト 16-2 SOAP 要求ヘッダ変数 (reqheader) のコンテンツ
<soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing">
<wsa:Action>...</wsa:Action>
<wsa:To>...</wsa:To>
<wsa:From>...</wsa:From>
<wsa:ReplyTo>...</wsa:ReplyTo>
<wsa:FaultTo>...</wsa:FaultTo>
</soap:Header>
このシナリオ例では、外部サービスに送信されるメッセージの本体全体は、次のサンプル コードのようになります (myreq 変数と reqheader 変数のコンテンツは太字で示されています)。
コード リスト 16-3 サービス コールアウト アクションの結果としてサービスに送信されるメッセージ
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing">
<wsa:Action>...</wsa:Action>
<wsa:To>...</wsa:To>
<wsa:From>...</wsa:From>
<wsa:ReplyTo>...</wsa:ReplyTo>
<wsa:FaultTo>...</wsa:FaultTo>
</soap:Header>
<soapenv:Body>
<sayHello xmlns="http://www.openuri.org/">
<intVal>100</intVal>
<string>Hello AquaLogic</string>
</sayHello>
</soapenv:Body>
</soapenv:Envelope>
図 16-6 に示すサービス コールアウト アクションのコンフィグレーションに基づいて、サービスからの応答は myresp 変数に割り当てられます。外部サービスからの応答全体は、次のサンプル コードのようになります。
コード リスト 16-4 サービス コールアウト アクションの結果としてのサービスからの応答メッセージ
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.
org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<env:Header/>
<env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<m:sayHelloResponse xmlns:m="http://www.openuri.org/">
<result xsi:type="xsd:string">This message brought to you by Hello AquaLogic and the number 100
</result>
</m:sayHelloResponse>
</env:Body>
</env:Envelope>
このシナリオでは、myresp 変数に、次のサンプル コードに示す値が割り当てられます。
コード リスト 16-5 サービス コールアウト アクションの結果としての応答変数 (myresp) のコンテンツ
<m:sayHelloResponse xmlns:m="http://www.openuri.org/">
<result ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance">
This message brought to you by Hello AquaLogic and the number 100
</result>
</m:sayHelloResponse>
XML サービスへのコールアウト時のメッセージの作成方法を説明するために、次の図のようにコンフィグレーションされたサービス コールアウト アクションを例として示します。
図 16-7 XML サービスのサービス コールアウト アクションのコンフィグレーション
また、実行時に要求ドキュメント変数 myreq が次の XML にバインドされていることを前提とします。
<sayHello xmlns="http://www.openuri.org/">
<intVal>100</intVal>
<string>Hello AquaLogic</string>
</sayHello>
myreq 変数の値です。myresp に割り当てられた値は、次のサンプル コードのようになります。<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<env:Header/>
<env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<m:sayHelloResponse xmlns:m="http://www.openuri.org/">
<result xsi:type="xsd:string">This message brought to you by Hello AquaLogic and the number 100
</result>
</m:sayHelloResponse>
</env:Body>
</env:Envelope>
SOAP RPC スタイルのサービスの場合の特徴は以下のとおりです。
SOAP RPC スタイルのサービスへのコールアウト時のメッセージの作成方法を説明するために、以下のコンフィグレーションを持つ例を示します。
input1 Hello AquaLogic にバインドされたメッセージ コンテキスト変数 input2図 16-8 RPC スタイルのサービスのサービス コールアウト アクションのコンフィグレーション
このシナリオでは、サービスに対する発信メッセージの本体は、次のサンプル コードのようになります。
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<sayHello2 xmlns="http://www.openuri.org/">
<intVal>100</intVal>
<string >Hello AquaLogic</string>
</sayHello2>
</soapenv:Body>
</soapenv:Envelope>
呼び出しが行われたサービスが返す応答は、次のサンプル コードのようになります。
コード リスト 16-9 helloWorld サービスからの応答メッセージのコンテンツ
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<env:Header/>
<env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<m:sayHello2Response xmlns:m="http://www.openuri.org/">
<result xsi:type="n1:HelloWorldResult" xmlns:n1="java:">
<message xsi:type="xsd:string">
This message brought to you by Hello AquaLogic and the number 100
</message>
</result>
</m:sayHello2Response>
</env:Body>
</env:Envelope>
メッセージ コンテキスト変数 output1 には、次のサンプル コードに示す値が割り当てられます。
コード リスト 16-10 出力変数 (output1) のコンテンツ
<message ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-intance">
This message brought to you by Hello AquaLogic and the number 100</message>
<binary-content ref=.../> 参照 XML のインスタンスによって表されるバイナリ データとすることができます。<binary-content ref= ... /> 参照 XML のインスタンスが格納されます。たとえば、要求メッセージのコンテキスト変数 myreq が <hello>there</hello> という形式の XML ドキュメントにバインドされる場合、発信メッセージには厳密にこのペイロードが格納されます。応答メッセージのコンテキスト変数 (myresp) は、次のような参照要素にバインドされます。
<binary-content ref=" cid:1850733759955566502-2ca29e5c.1079b180f61.-7fd8"/>
エラー処理は、メッセージ フロー、パイプライン、ルート ノード、およびステージ レベルでコンフィグレーションできます。その方法については、「エラー メッセージと処理」を参照してください。サービス コールアウトの結果として外部サービスから受け取るエラーのタイプには、転送エラー、SOAP エラー、予期される応答に一致しない応答などが含まれます。
fault コンテキスト変数の設定は、返されるエラーのタイプごとに異なります。fault 変数のコンテンツに基づいて、ビジネス ロジックとエラー処理ロジックを構築できます。$fault の詳細については、「fault 変数」および「エラー コード」を参照してください。
外部サービスから転送エラーを受け取り、転送プロバイダから AquaLogic Service Bus にエラー応答ペイロードが返されない場合 (たとえば、HTTP 403 のエラー コードが返された場合)、サービス コールアウト アクションは例外をスローします。これにより、パイプラインでエラーが発生します。ユーザ コンフィグレーション エラー ハンドラの fault 変数は、次のサンプル コードと同様の形式のメッセージにバインドされます。
コード リスト 16-11 AquaLogic Service Bus の fault 変数のコンテンツ - 転送エラー、エラー応答ペイロードなし
<con:fault xmlns:con="http://www.bea.com/wli/sb/context">
<con:errorCode>BEA-380000</con:errorCode>
<con:reason>Not Found</con:reason>
<con:details>
.......
</con:details>
<con:location>
<con:node>PipelinePairNode1</con:node>
<con:pipeline>PipelinePairNode1_request</con:pipeline>
<con:stage>stage1</con:stage>
</con:location>
</con:fault>
転送エラーに関連付けられたペイロードがある場合 (たとえばビジネス サービスから HTTP 500 のエラー コードを受け取り、応答内に XML ペイロードがある場合)、カスタム エラー コード BEA-382502 のメッセージ コンテキスト エラーが生成されます。
サービスが HTTP または JMS 転送を使用している場合に、そのサービスからの応答の結果として BEA-382502 エラー応答コードがトリガされるには、次の条件が満たされる必要があります。
fault 内の ErrorResponseDetail 要素には、サービスから受信したエラー応答ペイロードが含まれます。次のリストに ErrorResponseDetail 要素の例を示します。
コード リスト 16-12 AquaLogic Service Bus の fault 変数のコンテンツ - 転送エラー、エラー応答ペイロードあり
<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context">
<ctx:errorCode>BEA-382502<ctx:errorCode>
<ctx:reason> Service callout has received an error response from the server</ctx:reason>
<ctx:details>
<alsb:ErrorResponseDetail xmlns:alsb="http://www.bea.com/...">
<alsb:detail> <![CDATA[
. ..
]]>
</alsb:detail>
</alsb:ReceivedFault>
</ctx:details>
<ctx:location>.. .</ctx:location>
</ctx:Fault>
注意 : サービス コールアウトで生成されるエラーの XML スキーマについては、「サービス コールアウトで生成されるエラー詳細の XML スキーマ」を参照してください。
外部サービスが SOAP エラーを返した場合、AquaLogic Service Bus ランタイムは、カスタム エラー コードとエラーの詳細を示す説明を含むコンテキスト変数 $fault を設定します。そのために、SOAP エラーの <SOAP-ENV:Fault> 要素の下にある 3 つの要素のコンテンツが抽出され、AquaLogic Service Bus の fault 要素の作成に使用されます。
サービスが次のエラーを返す場合のシナリオを例として示します。
コード リスト 16-13 サービス コールアウトから返される SOAP エラー
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring>Application Error</faultstring>
<detail>
<message>That's an Error!</message>
<errorcode>1006</errorcode>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<faultcode>、<faultstring>、<detail> の各要素が抽出され、<alsb:ReceivedFault> 要素でラッピングされます。コード リスト 16-13 の faultcode 要素には、QName (関連するすべてのネームスペース宣言が保持されます) が含まれます。
生成される <alsb:ReceivedFault> 要素およびカスタム エラー コードとエラー文字列は、fault コンテキスト変数のコンテンツの作成に使用されます。この例の場合は、次のサンプル コードと同様の形式になります。
コード リスト 16-14 AquaLogic Service Bus の fault 変数のコンテンツ - SOAP エラー
<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context">hat's an Error!
<ctx:errorCode>BEA-382500<ctx:errorCode>
<ctx:reason> service callout received a soap Fault response</ctx:reason>
<ctx:details>
<alsb:ReceivedFault xmlns:alsb="http://www.bea.com/...">
<alsb:faultcode
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">SOAP-ENV:Clien
</alsb:faultcode>
<alsb:faultstring>Application Error</alsb:faultstring>
<alsb:detail>
<message>T</message>
<errorcode>1006</errorcode>
</alsb:detail>
</alsb:ReceivedFault>
</ctx:details>
<ctx:location> </ctx:location>
</ctx:Fault>
注意 : ユニークなエラー コード BEA-382500 は、サービス コールアウト アクションが SOAP エラーの応答を受け取る場合のために予約されています。
プロキシ サービスのランタイムが予期していない応答メッセージがサービスから返された場合、メッセージ コンテキスト エラーが生成され、カスタム エラー コード BEA-382501 で初期化されます。エラーの詳細には応答の SOAP-Body 要素のコンテンツが含まれます。
サービス コールアウトで生成されるエラーの XML スキーマについては、コード リスト 16-15 を参照してください。
サービス コールアウトで生成されるエラー詳細の XML スキーマ定義を次のサンプル コードに示します。
コード リスト 16-15 サービス コールアウトで生成されるエラー詳細の XML スキーマ
<xs:complexType name="ReceivedFaultDetail">
<xs:sequence>
<xs:element name="faultcode" type="xs:QName"/>
<xs:element name="faultstring" type="xs:string"/>
<xs:element name="detail" minOccurs="0" >
<xs:complexType>
<xs:sequence>
<xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax" />
</xs:sequence>
<xs:anyAttribute namespace="##any" processContents="lax" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="UnrecognizedResponseDetail">
<xs:sequence>
<xs:element name="detail" minOccurs="0" type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ErrorResponseDetail">
<xs:sequence>
<xs:element name="detail" minOccurs="0" type="xs:string" />
</xs:sequence>
</xs:complexType>
実行時のサービス コールアウト アクションとルート ノードの違い
実行時にルート ノードでコンフィグレーションされたアクションとサービス コールアウト アクションの動作の違いは、主に以下のとおりです。
実行時にこのステージの実行がスキップされて、処理がメッセージ フローの次のステージに進むように指定するには、スキップ アクションを使用します。
このアクションにはパラメータがなく、要求パイプライン、応答パイプライン、エラー パイプラインで使用できます。メッセージ フローのスキップ アクションを作成するには、以下の手順を実行します。
メッセージのヘッダの値を簡単に設定するには、転送ヘッダ アクションを使用します。
転送ヘッダ アクションを使用すると、発信要求 (ルート アクションまたはパブリッシュ アクションでプロキシ サービスによって送信されるメッセージ) と着信応答 (プロキシ サービスがクライアントに返信する応答メッセージ) のヘッダの値を簡単に設定できます。このアクションでは、どのメッセージ コンテキストの場所を変更するかをランタイムに対して指定します。
変更するヘッダ セットを指定したら、ヘッダの値をコンフィグレーションします。ヘッダの値は、名前と値のペアの順序指定のないテーブルとして設定します。ランタイムでは、対応する XML の生成時に、ネームスペースを宣言し、適切な順序でヘッダ要素を配置します。
転送ヘッダ アクションをコンフィグレーションするには、以下の手順を実行します。
図 16-9 転送ヘッダ アクションのコンフィグレーション - 発信要求、着信応答
このフィールドは必須であり、発信要求 (ルート アクションまたはパブリッシュ アクションでプロキシ サービスによって送信されるメッセージ) と着信応答 (プロキシ サービスがクライアントに返信する応答メッセージ) のヘッダの値を設定するかどうかをランタイムに対して指定します。
転送ヘッダ アクションをコンフィグレーションするときに [発信要求] または [着信応答] を選択することによって、どのメッセージ コンテキストの場所を変更するかをランタイムに対して指定します。これらのヘッダ要素は、メッセージ コンテキストの以下の場所にあります。
$outbound/ctx:transport/ctx:request/tp:headers $inbound/ctx:transport/ctx:response/tp:headers このオプションを選択すると、転送ヘッダ アクションは、すべてのヘッダを着信メッセージと発信メッセージとの間で自動的にパススルーします。ソース ヘッダ セットのすべてのヘッダはターゲット ヘッダ セットにコピーされ、ターゲット ヘッダ セットの既存の値はすべて上書きされます。
このオプションとヘッダ固有のパススルー オプションの使用については、「グローバル パススルー オプションとヘッダ固有のコピー オプションについて」を参照してください。
図 16-11 転送ヘッダ アクションの個別コンフィグレーション オプション
ドロップダウン リストには、事前定義されたすべてのターゲット転送のヘッダ名が入力されます (たとえば、HTTP 転送の場合は Content-Type、JMS 転送の場合は JMSCorrelationID など)。[その他] フィールドにヘッダ名を入力し、そのヘッダ名がこのサービスの転送の事前定義されたヘッダでない場合、そのヘッダは転送仕様の定義のとおりユーザ ヘッダになります。
このオプションを選択すると、XQuery 式または XSLT 式を使用して、ヘッダの値を設定できます。単純な式 (たとえば、"text/xml") または複雑な XQuery 式あるいは XSLT 式を使用できます。
AquaLogic Service Bus 転送レイヤでは、すべてのヘッダの XML 表現を文字列値として定義するため、式の結果は、ヘッダの値が設定される前に文字列に変換されます。何も返さない式のヘッダの値は、空の文字列に設定されます。式を使用してヘッダを削除することはできません。
警告 : このアクションで指定できるすべてのヘッダの設定が実行時に使用されるわけではありません。特定の転送についてどのヘッダを設定できるか、および実行時にどのヘッダのセットが使用されるかについては、「ランタイムでの転送ヘッダの設定の使用方法について」を参照してください。
要求または応答のメタデータからヘッダが削除されるように指定します。
[着信要求からヘッダをコピー] (発信要求の転送ヘッダを設定する場合 - 図 16-10 を参照)
または
[発信応答からヘッダをコピー] (着信応答の転送ヘッダを設定する場合 - 図 16-10 を参照)
このヘッダが着信メッセージの同じ名前を持つ対応するヘッダから発信メッセージに、またその逆に直接コピーされるように指定します。たとえば、発信要求の SOAPAction ヘッダを設定する場合は、[着信要求からヘッダをコピー] を選択すると、ランタイムが $inbound の SOAPAction 要求ヘッダから値をコピーします。着信応答ヘッダの場合、コピーするヘッダのソースは、$outbound の応答ヘッダです。
ソース内に存在しないヘッダについてヘッダをコピー オプションが選択された場合、このオプションは無視され、このヘッダのターゲットではアクションが実行されません。つまり、このヘッダをコピー オプションでは、ソースに存在するヘッダだけがターゲットにコピーされます。
このオプションとグローバルな [パイプラインを介してすべてのヘッダを渡す] オプションの使用については、「グローバル パススルー オプションとヘッダ固有のコピー オプションについて」を参照してください。
前の節で説明したように、転送ヘッダ アクションのコンフィグレーション時には以下のオプションを使用できます。
警告 : 転送ヘッダは転送の種類に固有であるため、パススルー (またはコピー) オプションは、転送の種類が同じサービス間でヘッダをコピーする場合に限って使用することをお勧めします。転送の種類が異なるサービス間でヘッダを渡す (またはコピーする) と、渡すヘッダがターゲット転送で受け入れられない場合、エラーが発生することがあります。同じ理由で、ヘッダを設定のオプションを使用してヘッダ名を指定するときは注意が必要です。
[パイプラインを介してすべてのヘッダを渡す] を選択すると、実行時に転送ヘッダ アクションがすべてのヘッダを着信メッセージと発信メッセージとの間でパススルーするように指定されます。ソース ヘッダ セットのすべてのヘッダはターゲット ヘッダ セットにコピーされ、ターゲット ヘッダ セットの既存の値はすべて上書きされます。
ヘッダをコピー オプションを選択すると、実行時に転送ヘッダ アクションが、このオプションが関連付けられている特定のヘッダを着信メッセージと発信メッセージとの間でコピーするように指定されます。
これらのオプションは、自分のシナリオに最適な方法で使用します。どちらのオプションを使用しても、ソース ヘッダ セットのヘッダがターゲット ヘッダ セットにコピーされ、ターゲット セットの既存の値はすべて上書きされます。[パイプラインを介してすべてのヘッダを渡す] オプションは、ヘッダ固有のすべてのヘッダをコピー オプションの前に実行されます。つまり、特定の転送ヘッダ アクションのコンフィグレーションについて [パイプラインを介してすべてのヘッダを渡す] を選択した場合、特定のヘッダのヘッダをコピー オプションを選択する必要はありません。
ただし、[パイプラインを介してすべてのヘッダを渡す] を選択してすべてのヘッダをコピーした後で、特定のヘッダについて [ヘッダを削除] を選択して、個々のヘッダが削除されるようにアクションをコンフィグレーションすることはできます。
前のトピックでは、転送ヘッダ アクションの発信要求 (ルート アクションまたはパブリッシュ アクションでプロキシ サービスによって送信されるメッセージ) と着信応答 (プロキシ サービスがクライアントに返信する応答メッセージ) の転送ヘッダの値のコンフィグレーション方法について説明しました。通常、ヘッダの値は以下のように処理できます。
転送ヘッダ アクションを使用すると、$inbound または $outbound のヘッダを設定、削除、またはパススルーすることができます。これらのヘッダを設定または削除した後に、$inbound または $outbound をログに書き込むと、変更の影響を確認できます。ただし、メッセージが送信されるときに AquaLogic Service Bus バインディング レイヤによって $inbound または $outbound の一部のヘッダが変更または削除され、そのため基礎になる転送でこれらのヘッダの一部が無視されて、その転送固有の値が使用されることがあります。重要な違いは、バインディング レイヤによってヘッダに行われる変更は $inbound および $outbound に対して直接行われますが、転送による変更はメッセージの送信形式のみに影響するという点です。たとえば、発信の Content-Length ヘッダの値を指定することはできますが、そのヘッダはメッセージ送信時にバインディング レイヤによって $outbound から削除されます。そのため、変更は応答パスで確認できます (たとえば、$outbound をログに書き込むと、変更された値を確認できます)。$outbound に User-Agent ヘッダを設定した場合、HTTP 転送ではその設定が無視され、HTTP 転送固有の値が使用されます。ただし、$outbound の値は変更されません。
次の表は、実行時に無視または上書きされる転送ヘッダと、特定の転送ヘッダについて存在するその他の制限を示しています。
表 16-5 転送ヘッダ アクションで指定する転送ヘッダの値の制限
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|
|
|
|
|
|||
|
|
|||
|
|
|||
![[ヘッダを追加] メニュー項目](wwimages/transportheader_action4.gif "[ヘッダを追加] メニュー項目")
を使用してヘッダをテーブルから削除したりできます。ランタイムでは、対応する XML の生成時に、ネームスペースを宣言し、適切な順序でヘッダ要素を配置するため、テーブルのヘッダの順序を指定する必要はありません。JMSExpiration ヘッダを 1000 に設定し、送信時に GMT が 1,000,000 (System.currentTimeMillis() の結果) である場合、JMS メッセージの JMSExpiration プロパティの結果の値は 1,000,1000 になります。注意 : inbound コンテキスト変数と outbound コンテキスト変数を設定する場合や、AquaLogic Service Bus Test Console を使用してプロキシ サービスまたはビジネス サービスをテストする場合は、転送ヘッダとメタデータの設定のときと同じ制限が適用されます。詳細については、以下のトピックを参照してください。
XML スキーマ要素または WSDL リソースに対して、XPath 式で選択した要素を検証するには、検証アクションを使用します。検証アクションをコンフィグレーションするには、以下の手順を実行します。
注意 : 検証アクションはグローバル要素しか検証できません。AquaLogic Service Bus はローカル要素に対する検証に対応していません。
|
|
|
