Map Value アサーション

Map Value アサーションは、ポリシー内で値をマップするために使用されます。値をいくつかの正規表現と照合して、出力値を生成し、コンテキスト変数に格納します。結果は、値に一致する最初の行から取得されます。
gateway90
Map Value アサーションは、ポリシー内で値をマップするために使用されます。値をいくつかの正規表現と照合して、出力値を生成し、コンテキスト変数に格納します。結果は、値に一致する最初の行から取得されます。
このアサーションは、公開されているサービスに URL をマップする「message-received」グローバル ポリシー フラグメントで、組み込みマッピング サポートを使用した簡易表現では表せないより複雑なマッピングが必要な場合に、特に役に立ちます。
ステートメント切り替えの機能を提供するために、またはテーブルを入力値と出力値で定義する手段として、Map Value アサーションを使用できます。
ポリシー例
Map Value アサーションを「message-received」グローバル ポリシー フラグメント内で使用して、
Layer7 API Gateway
のサービス解決ロジックよりユーザ独自のロジックを優先させることができます。アサーション プロパティで以下のように設定されていると想定します。
  • Value to Map
    :
    ${request.url.query}
  • Mappings
    :
    Pattern
    :
    east
    ; Result:
    /east_uri
    Pattern
    :
    west
    ; Result:
    /west_uri
  • Output variable
    :
    uri
このアサーションは以下のように解釈されます。
  1. ${request.url.query} の値を調べます。
  2. この値が正規表現「east」に一致すれば、出力変数「url」を「east_url」に設定します。
  3. 一致しない場合、この値が正規表現「west」に一致すれば、出力変数「url」を「west_url」に設定します。
  4. どちらの正規表現も一致しない場合、アサーションは失敗し、出力変数「url」は設定されません。
「message-received」グローバル ポリシー フラグメント内で使用される場合、そのフラグメントは以下の処理に類似しています。
At least one assertion must evaluate to true
All assertions must evaluate to true
マップ { "east" => "/east_uri", "west" => "/west_uri" } を使用して ${request.url.query} から値をマップし、${uri} に出力
Resolve service
with URI ${uri}
Continue processing
実行時に、さまざまな値は以下のように解釈されます。
?east
-> /east_uri
?direction=west
-> /west_uri (サブストリングの一致)
?beast
-> /east_uri (サブストリングの一致。この例の正規表現では単語境界は識別されない)
?direction=west&otherdirection=east
-> /east_uri (最初の一致が優先される -- いずれかが成功するまで、テーブル内の最初の行から最後の行の順序で一致が試行される)
?direction=north
-> アサーションは失敗(一致する行がない)
キャプチャ グループ疑似変数
一致が成功した後に出力値が設定されている間は、「疑似変数」(${0}、${1}、{2} など)を使用できます。これらの変数には、一致した正規表現のキャプチャ グループが含まれています。これらの変数の 1 つの用途は、REST スタイルの呼び出し(ターゲット オブジェクト名が URL パスにエンコードされている)を SOAP スタイルの呼び出し(ターゲット オブジェクト名が XML ペイロードで識別される)に変換することです。
例 #1:
電話番号から抽出された疑似変数の簡単な例を以下に示します。マップする値は
${request.url.path}
です。
  • Value to map
    :
    ${phone}
  • Pattern
    : (\d{3})-(\d{3})-(\d{4})
キャプチャ グループ疑似変数について説明することが目的であるため、この例では、結果および出力変数については言及していないことに注意します。
実行時に、${phone} は「
800-555-1234
」の値を持ち、この値は上記のパターンと正常に一致します。この場合、以下の疑似変数が設定されます。
${0}
は、正規表現によって一致した文字列全体(つまり「(800) 555-1234」)に設定されます。
${1}
は、最初のキャプチャ グループ(つまり「800」)に設定されます。
${2}
は、2 番目のキャプチャ グループ(つまり「555」)に設定されます。
${3}
は、3 番目のキャプチャ グループ(つまり「1234」)に設定されます。
 
疑似変数 ${0} ~ ${3} は、マッピング結果が設定されている間だけ存在します。これらの値は、ポリシー内の後続のアサーション内では使用できません。
 
例 #2:
マッピング内で疑似変数を使用する、より複雑な例を以下に示します。
  • Pattern
    :
    ^/users/(\w+)/paystub/(\d+)
  • Result
    (1 行に表示):
<info><action>getPaystub</action><user>${1}</user> <stubid>${2}<stubid></info>
  • Pattern
    :
    ^/users/(\w+)/vacations/(\d+)/(\d+)
  • Result
    (1 行に表示):
<info><action>getVacation<action><user>${1}</user><year>${2} </year><month>${3}</month></info>
実行時に以下のようなリクエストが URL に到達した場合、
/users/bob/paystub/123
出力変数は以下のように設定されます。
<info><action>getPaystub</action><user>bob</user><stubid>123</stubid></info>
ここで使用される疑似変数は以下のとおりです。
${1}
は、最初のキャプチャ グループ(つまり「bob」)に設定されます。
${2}
は、2 番目のキャプチャ グループ(つまり「123」)に設定されます。
同様に、実行時に以下のようなリクエストが URL に到達した場合、
/users/sue/vacations/2012/3
出力変数は以下のように設定されます。
<info><action>getVacation</action><user>sue</user><year>2012</year><month>3</month></info>
ここで使用される疑似変数は以下のとおりです。
${1}
は、最初のキャプチャ グループ(つまり「sue」)に設定されます。
${2}
は、2 番目のキャプチャ グループ(つまり「2012」)に設定されます。
${3}
は、3 番目のキャプチャ グループ(つまり「3」)に設定されます。
アサーションの使用
  1. 以下のいずれかを実行します。
    • アサーションをポリシー作成ウィンドウに追加するには、「アサーションの追加」を参照してください。
    • 既存のアサーションの設定を変更するには、下記の手順 2 に進みます。
  2. ポリシー ウィンドウで[
    Map Value
    ]を右クリックして[
    Map Value Properties
    ]を選択するか、ポリシー ウィンドウでアサーションをダブルクリックします。このアサーションのプロパティが表示されます。 
  3. 以下のようにダイアログ ボックスを設定します。
    設定
    説明
    Value to Map
    下記で定義するマッピングと比較する表現を入力します。リテラル表現またはコンテキスト変数を指定できます。
    Mappings
    マップされる正規表現のリストを定義します。
    マッピングを追加する方法
    1. Add Mapping
      ]をクリックします。
    2. 上記で指定した値と比較する正規表現を[
      Pattern
      ]に入力します。コンテキスト変数を参照することもできます。
      参照しているコンテキスト変数が存在しない(たとえば、ミススペルのため)場合、デフォルトではその変数は空の文字列として扱われ、任意の入力に一致するパターンになる可能性があります。そのような問題をポリシーの作成中に把握するには、クラスタ プロパティ
      template.strictMode
      を true に設定します。
    3. マッピングが成功した場合に出力変数に配置される結果を[
      Result
      ]に入力します。コンテキスト変数、および特別な正規表現であるキャプチャ グループ疑似変数を参照できます。詳細については、前述の「キャプチャ グループ疑似変数」を参照してください。
    4. OK
      ]をクリックします。
    マッピングを編集する方法
    1. 編集するマッピングを選択します。
    2. Edit Mapping
      ]をクリックします。
    3. 必要に応じて、パターンまたは結果を変更します。
    4. OK
      ]をクリックします。
    マッピングを削除する方法
    1. 削除するマッピングを選択します。
    2. Remove Mapping
      ]をクリックします。その行がすぐに削除されます。
    マッピングの順序を変更する方法
    1. マッピングを選択します。
    2. 必要なだけ、[
      Move Up
      ]または[
      Move Down
      ]をクリックします。最初に一致する行の結果が出力変数に配置されます。
    Output Variable
    成功した一致の結果が格納される単一値コンテキスト変数を指定します。
    表示される検証メッセージの説明については、「コンテキスト変数の検証」を参照してください。 
  4. OK
    ]をクリックします。