Route via MQ Native アサーション

Route via MQ Native アサーションは、CA API Gateway からの送信サービス メッセージの MQ ネイティブ移送の設定を可能にします。
Route via MQ Native
アサーションは、
Layer7 API Gateway
からの送信サービス メッセージの MQ ネイティブ移送の設定を可能にします。
適切な .jar ファイルがインストールされるまで、MQ ネイティブは動作できません。
このアサーションによって使用されるコンテキスト変数
Route via MQ Native アサーションにより、以下のコンテキスト変数が使用されます。
(1)
<prefix>
はメッセージのターゲットです。たとえば、メッセージ ターゲットがリクエストである場合、プレフィックスは、「request」です。メッセージ ターゲットが応答である場合、プレフィックスは「response」です。(2) Gateway が MQ メッセージを受信すると、「リクエスト」の MQ ネイティブ変数が設定されます(Route via MQ Native アサーションは、まだ実行される必要はありません)。
コンテキスト変数
説明
${
<
prefix
>
.mqnative.md.
<
field
>
}
メッセージ記述子フィールドの値を返します(大文字と小文字を区別)。
例:
${request.mqnative.md.expiry}
${request.mqnative.md.messageId}
${request.mqnative.md.correlationId}
byte[] タイプ記述子の値は、Base64 エンコード文字列として入力される必要があります。日付は
yyyy-MM-dd-HH.mm.ss.SSSSSS
形式である必要があります。
${
<
prefix
>.
mqnative.additionalheader
.
<folder name>.<name>
}
メッセージ ヘッダの値を返します。フォルダ名の指定はオプションです。
例:
${request.mqnative.additionalheader.folder.rfh2Field2}
${
<prefix>
.mqnative.property.
<name>
}
メッセージ プロパティの値を返します。
例:
${request.mqnative.property.folder.testStringProperty}
${
<prefix>
.
mqnative.additionalheadernames}
すべてのメッセージ ヘッダ名を取得する複数値を持つコンテキスト変数です。サフィックス
.length
を適用できます。
例:
${request.mqnative.additionalheadernames}
${
<prefix>.
mqnative.alladditionalheadervalues}
すべてのメッセージ ヘッダ値を取得する複数値を持つコンテキスト変数です。サフィックス
.length
を適用できます。
例:
${request.mqnative.alladditionalheadervalues}
${
<prefix>
.
mqnative.propertynames}
すべてのメッセージ プロパティ名を取得する複数値を持つコンテキスト変数です。サフィックス
.length
を適用できます。
例:
${request.mqnative.propertynames}
${
<prefix>
.
mqnative.allpropertyvalues}
すべてのメッセージ プロパティ値を取得する複数値を持つコンテキスト変数です。サフィックス
.length
を適用できます。
例:
${request.mqnative.allpropertyvalues}
定義済みの MQ ヘッダ プレフィックス
MQ メッセージ記述子、プロパティおよびヘッダ用のヘッダ名プレフィックスを、下記の表 に示します。
ヘッダ名プレフィックス
説明
mqnative.md
MQ メッセージ記述子用のヘッダ名プレフィックスです。
例:
mqnative.md.expiry
mqnative.md.messageId
mqnative.md.correlationId
mqnative.property
MQ メッセージ プロパティ用のヘッダ名プレフィックスです。
例:
mqnative.property.folder.propertyname
mqnative.additionalheader
MQ メッセージヘッダ用のヘッダ名プレフィックスです。
例:
mqnative.header.folder.headername
メッセージ記述子、プロパティ、および追加ヘッダをカスタマイズするには、Manage Transport Properties/Headers アサーションを使用します。MQ メッセージ記述子、MQ メッセージ プロパティおよび MQ 追加ヘッダから属性を削除するには、ヘッダ値を空のままにします。
ヘッダに含まれている不正なプレフィックスは無視されます。
アサーションの使用
  1. 以下のいずれかを実行します。
    • アサーションをポリシー作成ウィンドウに追加するには、「アサーションの追加」を参照してください。
    • 既存のアサーションの設定を変更するには、下記の手順 2 に進みます。
  2. アサーションを追加すると、[
    Native MQ Routing Properties
    ]ダイアログ ボックスが自動的に表示されます。アサーションを変更する場合は、ポリシー ウィンドウで[
    Route via MQ Native
    ]を右クリックして[
    MQ Native Routing Properties
    ]を選択するか、ポリシー ウィンドウでアサーションをダブルクリックします。このアサーションのプロパティが表示されます。これらのプロパティは以下の各タブに整理されています。
    Target
    Request
    Response
  3. 必要に応じて各タブを設定します。各タブの詳細な説明については、以下の該当するセクションを参照してください。
  4. 完了したら、[
    OK
    ]をクリックします。
[Target]タブの設定
Target
]タブは、使用する MQ ネイティブ キューを選択するために使用されます。
  1. MQ Native Queues
    ]ドロップダウン リストから、使用する接続を選択します。必要な接続が存在しない場合は、[
    New Queue
    ]をクリックして新しい接続を作成します。キューの定義の詳細については、「MQ ネイティブ キューの管理」を参照してください。
  2. 前の手順でテンプレート送信キューを MQ ネイティブ キューとして選択した場合は、[Dynamic Properties](動的プロパティ)セクションを完了します。動的プロパティは、設計時にではなく実行時に設定されるプロパティです。
    • Queue Name:
      動的なキュー名を入力します。コンテキスト変数を参照することもできます。
      動的なキュー名設定は、テンプレートとして指定されていて、キュー名が空になっている送信キューに対して有効化されます。詳細については、「MQ ネイティブ キューの管理」にある[MQ Connections Properties]の設定を参照してください。
    • Wait for Reply on specified queue:
      動的な応答キュー名を入力します。コンテキスト変数を参照することもできます。
      動的な応答キュー名設定は、テンプレートとして指定されていて、[Wait for Reply on specified queue]オプションが指定され、応答キュー名が空になっている送信キューに対して有効化されます。詳細については、「MQ ネイティブ キューの管理」にある[MQ Connections Properties]の設定と[Outbound Options]の設定を参照してください。
  3. メッセージの方向を、[
    Put to Queue
    ](デフォルト)または[
    Get from Queue
    ]に指定します。
    キュー名を動的に指定するには、
    キュー名
    のコンテキスト変数を上記の[Dynamic Properties]に必ず入力してください。
  4. 必要に応じて、[
    Advanced Options
    ]を指定します。これらのオプションは、キューに配置されているメッセージ、またはキューから送出されるメッセージに適用されます。
    • Open Options:
      ここで指定されたオプションを使用して、キューへの接続を確立します。MQOPEN API コールの定数フィールドの合計を表す値を入力します。[Open Options]は、接続ごとに設定します。これらのオプションは、Gateway が MQ Queue/Queue Manager への接続を開始するときにのみ適用されます。
      例:
      定数フィールドの MQOO_OUTPUT (16)および MQOO_FAIL_IF_QUIESCING (8192)を使用します。これらの値を合計し、結果の
      8208
      を[Open Options]フィールドに入力します。
      [Open Options]を指定しない場合、Gateway は(選択したメッセージ方向に応じて)
      io.mqRoutingPutOpenOptions
      または
      io.mqRoutingGetOpenOptions
      のいずれかのクラスタ プロパティを参照します。これらのクラスタ プロパティが定義されていない場合、Gateway は MqNativeConstants クラスのデフォルトを使用します。
    • Message Options:
      メッセージの方向に応じて、ここで指定したオプションを使用してメッセージをキューに配置するか、またはキューから取得します。MQGET API コールの定数フィールドの合計を表す値を入力します。
      例:
      定数フィールドの MQGMO_FAIL_IF_QUIESCING (8192)および MQGMO_NO_SYNCPOINT (4)を使用します。これらの値を合計し、結果の
      8196
      を[Message Options]フィールドに入力します。
      [Message Options]を指定しない場合、Gateway は(選択したメッセージ方向に応じて)
      io.mqRoutingPutMessageOptions
      または
      io.mqRoutingGetMessageOptions
      のいずれかのクラスタ プロパティを参照します。これらのクラスタ プロパティが定義されていない場合、Gateway は MqNativeConstants クラスのデフォルトを使用します。
    (1)定数フィールド値のリストについては、「MQ ネイティブ キューのプロパティ」を参照してください。
  5. Current WSS header handling
    ]セクションで、セキュリティ ヘッダの処理方法を指定します。
    オプション
    説明
    Don't modify the request Security header
    送信 SOAP リクエスト メッセージ内のセキュリティ ヘッダをそのまま残すように Gateway に指示します。ただし、Gateway がメッセージ処理中に暗号化されたマテリアルを復号化する必要があった場合、リクエストのセキュリティ ヘッダが変更されている可能性があります。
    保護されたサービスがリクエストの元のセキュリティ ヘッダの独自のチェックを必要とする場合、または、保護されたサービスがそのリクエスト メッセージ内のセキュリティ ヘッダの有無に無関係な場合、この設定を使用します。
    最高のパフォーマンスを得るために、可能な場合は必ずこの設定を使用して、リクエストあたりのメッセージ変更量を最小化してください。
    ポリシーが WS-Security を使用する場合は、セキュリティ ヘッダを変更しないでください。詳細については、「Add or Remove WS-Security アサーション」を参照してください。
    Remove Layer 7 actor and mustUnderstand attributes from processed Security header
    送信 SOAP メッセージ内のセキュリティ ヘッダから「mustUnderstand」属性および「Layer 7」アクタを削除するように Gateway に指示します。
    Layer 7 アクタの存在がバックエンド サービスに関する問題を引き起こす場合は、この設定を使用します。いくつかの場合において、このアクタが原因でバックエンド サービスがセキュリティ ヘッダを無視する可能性があります。これは、バックエンド サービスが、そのセキュリティ ヘッダが別のサービスに向けられていると認識するためです。また、バックエンド サービスがセキュリティをサポートせず、セキュリティ ヘッダ上で「mustUnderstand」がアサートされたリクエストを拒否する場合、この設定を使用します。
    別の方法として、セキュリティ ヘッダを完全に削除することも考えられますが、メッセージからこれらを削除するには追加の処理が必要となり、これはパフォーマンスの低下を招きます。また、ログ記録の目的で、セキュリティ ヘッダを原型のまま保持することが推奨されます。
    Remove processed Security header from request before routing
    保護されているサービスにリクエストを転送する前に Gateway によって処理されたすべてのセキュリティ ヘッダを削除するように Gateway に指示します。
    保護されているサービスが、転送された SOAP リクエスト内のセキュリティ ヘッダを予期していない場合、この設定を使用します。
  6. MQ 応答タイムアウト
    値のグローバル デフォルト(
    io.mqResponseTimeout
    クラスタ プロパティで定義)をこの 1 つのキューについてオーバーライドする場合は、[MQ response timeout]に応答タイムアウト値を入力します。値は
    0
    (ゼロ)より大きい必要があります。値はミリ秒単位で入力します。アサーションはこの期間応答を待機してからタイムアウトになります。
  7. (v10.1 CR1 で利用可能)
    以下のクラスタ プロパティ値でスレッド プールを作成するには、
    MQ PUT タイムアウト
    値をミリ秒単位で入力します。このスレッド プールは、IBM MQ サーバの PUT メッセージに PUT スレッドを提供します。タイムアウト値は
    0
    (ゼロ)より大きい必要があります。
    カスタム値を使用してスレッド プールを作成するには、以下のクラスタ プロパティの値を更新します。そうしない場合、スレッド プールはデフォルト値で作成されます。 
[Request]タブの設定
Request
]タブは、メッセージ ソースの選択、および必要となる MQ メッセージのプロパティの設定に使用されます。このタブは、[
Target
]タブ内のメッセージ方向が[
Put to Queue
]である場合のみ使用可能です。
  1. メッセージ ソースをドロップダウン リストから選択します([
    Request
    ](デフォルト)または[
    Response
    ])。
  2. Request
    ]タブのプロパティを以下のように設定します。
    設定
    説明
    MQ Message Descriptors
    Pass through MQ message descriptors
    ソース メッセージ内のすべての MQ 記述子のパス スルーを許可するには、このチェック ボックスをオンにします。(元のリクエストが MQ メッセージである場合にのみ、パス スルーする MQ メッセージ プロパティが存在します。)
    記述子のデフォルト値を結果メッセージへパス スルーするには、このチェック ボックスをオフにします。
    Customize message descriptors
    8.0 より前のバージョンに存在していたメッセージ記述子のカスタマイズ方法については、「MQ メッセージのカスタマイズ」を参照してください。バージョン 8.0 で作成されたメッセージ記述子については、Manage Transport Properties/Headers アサーションを使用して、カスタマイズされた値を追加することが推奨されています。
    プロパティ
    Pass through
    メッセージ ソースからのすべてのメッセージ プロパティをパス スルーするには、このチェック ボックスをオンにします。
    MQ メッセージ プロパティのパス スルーを望まない場合は、このボックスをクリアします。
    Copy to Additional Headers
    MQ メッセージ プロパティをメッセージの追加ヘッダにコピーするには、このチェック ボックスをオンにします。
    コピー動作を実行しないようにするには、このチェック ボックスをオフにします。
    Additional Headers
    Pass through
    メッセージ ソースからのすべての MQ 追加ヘッダをパス スルーするには、このチェック ボックスをオンにします。
    カスタマイズされた MQ 追加ヘッダのパス スルーを望まない場合は、このボックスをクリアします。
    Copy to Properties
    追加ヘッダの名前と値のペアをメッセージ プロパティにコピーするにはこのチェック ボックスをオンにします。
    コピー動作を実行しないようにするには、このチェック ボックスをオフにします。
    Set Additional Header as
    ドロップダウン リストから追加ヘッダの形式を選択します。
    • Original:
      このオプションは、元のプライマリ ヘッダ形式(MQRFH または MQRFH2)を保持します。ヘッダには、元のプライマリ ヘッダからの値が自動的に入力されます。
    • MQRFH:
      メッセージ内のすべての追加ヘッダは MQRFH ヘッダに置換されます。MQRFH ヘッダには、元のプライマリ ヘッダからの値が自動的に入力されます。
    • MQRFH2:
      プライマリ追加ヘッダは、メッセージ内の MQRFH2 ヘッダに置換されます。MQRFH2 ヘッダには、元のプライマリ ヘッダからの値が自動的に入力されます。
      MQRFH
      および
      MQRFH2
      が追加のヘッダとして選択されている場合、このヘッダに続くデータの形式を定義するには、
      Manage Transport Properties/Headers アサーション
      を使用してプロパティ mqnative.MQRFH.formatField を追加します。
[Response]タブの設定
Response
]タブは、応答メッセージ プロパティの設定、および必要となるすべての詳細プロパティの設定に使用されます。
Response
]タブのプロパティを以下のように設定します。
設定
説明
Message Target
メッセージ ソースをドロップダウン リストから選択します([
Request
]、[
Response
](デフォルト)または[
Message Variable
])。
Target Variable
ターゲットがコンテキスト変数である場合、[
Target Variable
]フィールドでメッセージ変数を指定します。新しい変数を定義するか、または既存のものを使用できます。入力したコンテキスト変数名に関する即時のフィードバックを表す検証メッセージが表示されます。表示される検証メッセージの説明については、「コンテキスト変数の検証」を参照してください。
MQ Message Descriptors
Pass through all message descriptors
ソース メッセージ内のすべての MQ 記述子のパス スルーを許可するには、このチェック ボックスをオンにします。(元のリクエストが MQ メッセージである場合にのみ、パス スルーする MQ メッセージ プロパティが存在します。)
記述子のデフォルト値を結果メッセージへパス スルーするには、このチェック ボックスをオフにします。
Customize message descriptors
8.0 より前のバージョンに存在していたメッセージ記述子のカスタマイズ方法については、「MQ メッセージのカスタマイズ」を参照してください。バージョン 8.0 で作成されたメッセージ記述子については、Manage Transport Properties/Headers アサーションを使用して、カスタマイズされた値をそのプロパティおよびヘッダに追加することが推奨されています。
プロパティ
Pass through
メッセージ ソースからのすべてのメッセージ プロパティをパス スルーするには、このチェック ボックスをオンにします。
カスタマイズされたメッセージ プロパティのパス スルーを望まない場合は、このボックスをクリアします。
Copy to Additional Headers
プライマリ ヘッダの名前と値のペアをメッセージ ヘッダにコピーするにはこのチェック ボックスをオンにします。
コピー動作を実行しないようにするには、このチェック ボックスをオフにします。
Additional Headers
Pass through
メッセージ ソースからのすべてのメッセージ プロパティをパス スルーするには、このチェック ボックスをオンにします。
カスタマイズされたメッセージ プロパティのパス スルーを望まない場合は、このボックスをクリアします。
Copy to Properties
プライマリ ヘッダの名前と値のペアをメッセージ プロパティにコピーするにはこのチェック ボックスをオンにします。
コピー動作を実行しないようにするには、このチェック ボックスをオフにします。
Set Additional Header as
ドロップダウン リストから追加ヘッダを選択します。
  • Original:
    このオプションは、元のプライマリ ヘッダ形式を MQRFH または MQRFH2 のまま保持します。ヘッダには、元のプライマリ ヘッダからの値が自動的に入力されます。
  • MQRFH:
    メッセージ内のすべての追加ヘッダは MQRFH ヘッダに置換されます。MQRFH ヘッダには、元のプライマリ ヘッダからの値が自動的に入力されます。
  • MQRFH2:
    このプライマリ追加ヘッダは、メッセージ内の MQRFH2 ヘッダに置換されます。MQRFH2 ヘッダには、元のプライマリ ヘッダからの値が自動的に入力されます。
    MQRFH
    および
    MQRFH2
    が追加のヘッダとして選択されている場合、このヘッダに続くデータの形式を定義するには、
    Manage Transport Properties/Headers アサーション
    を使用してプロパティ mqnative.MQRFH.formatField を追加します。
Override maximum message size
メッセージに許可する最大サイズをオーバーライドするには、このチェック ボックスをオンにします。
io.mqMessageMaxBytes
クラスタ プロパティで設定されている値を使用するには、このチェック ボックスをオフにします。
  • Restrict messages to:
    メッセージに許可する最大サイズを入力します(バイト単位)。
  • Allow unlimited message size (not recommended):
    無制限のサイズのレスポンス メッセージを許可するには、このオプションを選択します。