URL 書き換えモジュール 2.0 構成リファレンス

  • [アーティクル]

公開日: 2009 年 7 月 16 日 (作業者: ruslany (英語))

更新日: 2009 年 9 月 9 日 (作業者: ruslany (英語))

目次

  • 機能の概要
  • 送信規則の概要
    • 規則の継承
  • 送信規則の構成
    • 前提条件
    • タグ フィルター
      • 定義済みのタグ
      • カスタム タグ
    • 規則パターン
      • パターンの構文
      • パターンのプロパティ
    • 規則の条件
    • 規則アクション
      • Rewrite アクション
      • None アクション
  • 書き換えルールでの要求ヘッダーとサーバー変数の設定
    • 要求ヘッダーに関するメモ
  • 書き換えルールでの逆参照の使用
    • 複数の条件でのキャプチャ グループの追跡
  • 書き換えられた URL の IIS ログへのログ記録

機能の概要

IIS 7 用 Microsoft URL 書き換えモジュール 2.0 は、バージョン 1.1 の機能がすべて含まれている段階的なリリースで、送信応答の書き換えへのサポートが追加されています。 このモジュールを使用して、正規表現やワイルドカードの使用が可能な応答の書き換えロジックを表現したり、HTTP ヘッダーおよびサーバー変数に基づいて書き換えを判断したりできます。 具体的には、このモジュールを使用して以下の操作を実行できます。

  • 応答 HTML で、Web アプリケーションによって生成された URL をユーザーと検索エンジンにとって使いやすいものに置き換える。
  • リバース プロキシの背後にある Web アプリケーションによって生成された HTML マークアップのリンクを変更する。
  • JavaScript、CSS、RSS など、HTTP 応答のコンテンツを修正する。

送信規則の概要

応答の書き換えで使用される主な構成の概念は、送信規則の概念です。 送信規則は、応答のコンテンツと比較または照合する対象と、比較が正常に行われた場合の処理のロジックを表すために使用します。

概念的に、送信規則は次の部分で構成されます。

  • 前提条件 - オプションの前提条件を使用して、規則の評価を開始する前に要求メタデータを確認します。 前提条件には、要求メタデータに対する複数の条件付きチェックが含まれる場合があり、これを使用して、画像ファイルや動画ファイルなど書き換え不可の応答を除外することができます。
  • タグ フィルター - タグ フィルターを使用して、応答内での検索を一般的なタグ セットまたはカスタム定義のタグ セットに絞り込みます。 タグ フィルターを使用すると、応答のコンテンツ全体がパターンと照合されるのではなく、指定されたタグのコンテンツのみが規則パターンと照合されます。
  • パターン - 規則パターンを使用して、応答のコンテンツ内での検索に正規表現パターンまたはワイルドカード パターンのどちらを使用するかを指定します。
  • 条件 - オプションの条件コレクションを使用して、一致するパターンが応答のコンテンツ内で見つかった場合に実行する追加の論理演算を指定します。 条件内で、HTTP ヘッダーまたはサーバー変数に特定の値が含まれているかどうかを確認できます。
  • アクション - アクションを使用して、一致するパターンが見つかり、すべての規則条件が正常に評価された場合に実行する操作内容を指定します。**

規則の実行

送信規則は、実行プロセスにおいて受信規則とは異なります。 受信規則セットでは、単一の要求 URL 文字列が入力されるため、要求ごとに評価される回数は 1 回のみです。 送信規則セットでは、HTTP 応答のコンテンツ内の複数の場所に適用されるので、1 回の応答に対して評価される回数が多くなる場合があります。 たとえば、次の規則セットがあるとします。

規則 1 の適用対象: <a> タグおよび <img> タグ

規則 2 の適用対象: <a> タグ

HTML 応答に含まれるマークアップ:

<a href="/default.aspx"><img src="/logo.jpg" />Home Page</a>

この場合、URL 書き換えモジュール 2.0 により、規則 1 が "/default.aspx" 文字列に対して評価されます。 規則が正常に実行された場合、規則 1 の出力は規則 2 に渡されます。 規則 2 が正常に実行された場合、規則 2 の出力を使用して、応答内の <a> タグの href 属性のコンテンツを置き換えます。

その後、URL 書き換えモジュール 2.0 により、規則 1 が "/logo.jpg" 文字列に対して評価されます。 規則が正常に実行された場合、その出力を使用して、応答内の <img> タグの src 属性のコンテンツを置き換えます。

規則の継承

規則が複数の構成レベルで定義されている場合、URL 書き換えモジュールでは、親構成レベルの分散規則、および現在の構成レベルの規則が含まれる規則セットが評価されます。 評価は親から子の順に実行されます。つまり、親規則が最初に評価され、最後の子レベルで定義された規則が最後に評価されます。

送信規則の構成

前提条件コレクション

前提条件は、応答のコンテンツに対して規則を評価する必要があるかどうかを確認するために使用します。 前提条件コレクションは、<preConditions> セクション内で名前付きコレクションとして定義され、前提条件チェックを 1 つ以上含めることができます。 送信規則では、名前で前提条件コレクションを参照します。

前提条件コレクションには、条件の評価方法を制御する logicalGrouping という属性があります。 前提条件コレクションは次の場合に True として評価されます。

  • logicalGrouping='MatchAll' が使用されている場合は、コレクション内のすべての前提条件が True として評価されたとき。
  • logicalGrouping='MatchAny' が使用されている場合は、少なくとも 1 つの前提条件が True として評価されたとき。

前提条件は、次のプロパティを指定して定義されます。

  • 入力文字列 - 前提条件入力は、条件の評価で入力として使用する項目を指定します。 前提条件入力は任意の文字列で、サーバー変数および前の前提条件パターンへの逆参照を含むことができます。
  • パターン - 前提条件パターンは、正規表現構文またはワイルドカード構文を使用して指定できます。 前提条件で使用するパターンの種類は、前提条件コレクションに対して定義された patternSyntax フラグの値に依存します。

また、negate 属性を使用して、前提条件評価の結果を否定できます。

以下は、応答のコンテンツの種類が text/html であるかどうかを確認する前提条件の例です。

<preConditions> 
     <preCondition name=""HTML Only" logicalGrouping="MatchAll" patternSyntax="ECMAScript"> 
         <add input="{HTTP_CONTENT_TYPE}" pattern="^text/html$" /> 
     </preCondition> 
 </preConditions>

タグ フィルター

タグ フィルターは、応答のコンテンツ内での検索を一般的なタグ セットまたはカスタム定義の HTML タグ セットに絞り込むために使用されます。 書き換えルールでタグ フィルターを使用する場合、URL 書き換えモジュール 2.0 では、応答全体に対して規則パターンを照合するのではなく、規則のタグ フィルターで登録された HTML タグを検索し、そのタグの URL 属性のコンテンツを取得して、これを規則のパターンと照らし合わせて評価します。 タグ フィルターは、送信規則の <match> 要素の filterByTags 属性内で指定されます。 以下に例を示します。

<match filterByTags="A" pattern="^/(article\.aspx.*)" />

HTTP 応答に次のようなアンカー タグが含まれている場合、

<a href="/article.aspx?id=1">link</a>

書き換えルールのパターンは、文字列 "/article.aspx?id=1" に対して評価されます。

定義済みのタグ

URL 書き換えモジュール 2.0 には、送信規則と組み合わせて使用できる定義済みのタグ セットが含まれています。 以下の表は、定義済みのタグと属性の一覧です。これらの値は、送信規則パターンの入力として使用されます。

タグ 属性
A href
Area href
Base href
Form action
Frame src、longdesc
Head profile
IFrame src、longdesc
Img src、longdesc、usemap
Input src、usemap
Link href
Script src

カスタム タグ

定義済みのタグのコレクションに含まれていないタグの属性内で、書き換えを実行する必要がある場合は、カスタム タグのコレクションを使用して、書き換えが必要なタグ名と対応する属性を指定できます。 カスタム タグのコレクションは、<customTags> セクション内で名前付きコレクションとして定義されます。 送信規則では、名前でカスタム タグのコレクションを参照します。

以下は、カスタム タグのコレクションの定義の例です。

<customTags> 
     <tags name=""My Tags"> 
         <tag name=""item" attribute="src" /> 
         <tag name=""element" attribute="src" /> 
     </tags> 
 </customTags>

このカスタム タグのコレクションは、以下の例に示されるように、送信規則から参照できます。

<match filterByTags="A, CustomTags" customTags="My Tags" pattern="^/(article\.aspx.*)" />

規則パターン

規則の入力文字列の一致対象を指定するには、規則パターンを使用します。 規則の入力は、次に示すように規則の構成によって異なります。

  • 規則でタグ フィルターが使用される場合は、一致したタグ属性のコンテンツがパターン マッチング用の入力として渡されます。
  • 規則でタグ フィルターが使用されない場合は、応答のコンテンツ全体がパターン マッチング用の入力として渡されます。

パターンは、書き換えルールの <match> 要素内で指定されます。

規則パターンの構文

規則パターンの構文は、規則の patternSyntax 属性を使用して指定できます。 この属性には、次のいずれかのオプションを設定できます。

ECMAScript - Perl 互換の (ECMAScript (英語) 標準に準拠した) 正規表現構文です。 これは、規則の既定のオプションです。 この形式のパターンは "^([_0-9a-zA-Z-]+/)?(wp-.*)" のようになります。

Wildcard - IIS 7.0 HTTP リダイレクト モジュールで使用されるワイルドカード (英語) です。 この形式のパターンは、"/Scripts/*.js" のようになります。アスタリスク ("*") は "任意の数の任意の文字と一致し、それらを逆参照でキャプチャする" ことを意味します。 規則にタグ フィルターがない場合は、ワイルドカード パターンの種類は使用できません。

ExactMatch - 入力文字列内で文字列の完全一致検索が実行されます。

patternSyntax 属性の範囲は規則ごとに異なります。つまり、現在の規則のパターン、およびその規則の条件内で使用されるすべてのパターンに適用されます。

規則パターンのプロパティ

パターンは、<match> 要素の negate 属性を使用して否定できます。 この属性を使用すると、入力文字列が指定されたパターンに一致しない場合のみ、規則アクションが実行されます。

既定では、大文字と小文字を区別しないパターン マッチが使用されます。 大文字と小文字の区別を有効にするには、規則の <match> 要素の ignoreCase 属性を使用します。

規則の条件

規則の条件では、現在の入力文字列以外の入力に基づく、規則評価の追加ロジックを定義できます。 規則には、0 個またはそれ以上の条件を指定できます。 規則の条件は、規則のパターン マッチが成功した後に評価されます。

条件は、書き換えルールの <conditions> コレクション内で定義されます。 このコレクションには、条件の評価方法を制御する logicalGrouping という属性があります。 規則に条件が設定されると、規則のパターンが一致し、次のように条件が評価された場合のみ、規則アクションが実行されます。

  • logicalGrouping='MatchAll' が使用されている場合は、すべての条件が True として評価されたとき。
  • logicalGrouping='MatchAny' が使用されている場合は、少なくとも 1 つの条件が True として評価されたとき。

条件は、次のプロパティを指定して定義されます。

  • 入力文字列 - 条件入力は、条件の評価で入力として使用する項目を指定します。 条件入力は任意の文字列で、サーバー変数および前の条件パターンや規則パターンへの逆参照を含むことができます。
  • パターン -  条件入力内で検索するパターンです。 パターンは、正規表現構文またはワイルドカード構文を使用して指定できます。 条件で使用するパターンの種類は、この条件が属する規則に対して定義された patternSyntax フラグの値に依存します。 この条件の種類には、パターン マッチングを制御する 2 つの関連属性があります。

規則アクション

書き換えルールのアクションは、入力文字列がルールのパターンに一致し、条件評価が成功した場合 (規則の構成によって、すべての条件が一致した場合、あるいは 1 つまたは複数の条件が一致した場合) に実行されます。 使用できるアクションには 2 種類あり、<action> 構成要素の "type" 属性を使用して、規則によって実行されるアクションを指定できます。 次のセクションでは、種類が異なるアクションと特定のアクションの種類に関連する構成オプションについて説明します。

Rewrite アクション

Rewrite アクションでは、現在の規則入力文字列が代替文字列に置き換えられます。 代替文字列は、規則の <action> 要素の value 属性内で指定されます。 代替文字列は自由な形式の文字列で、次の情報を含めることができます。

  • 条件および規則パターンへの逆参照 (詳細については、逆参照の使用方法に関するセクションを参照してください)。
  • サーバー変数 (詳細については、サーバー変数の使用方法に関するセクションを参照してください)。

None アクション

アクションが実行されないように指定する場合は、None アクションを使用します。

書き換えルールでの要求ヘッダーとサーバー変数の設定

URL 書き換えモジュール 2.0 の書き換えルールを使用して、要求ヘッダーとサーバー変数を設定できます。 書き換えルールでは、任意の数の新しいサーバー変数と要求ヘッダーを設定できるだけでなく、既存のサーバー変数と要求ヘッダーを上書きすることもできます。 設定するサーバー変数と HTTP ヘッダーのコレクションを定義するには、ルールの要素 <serverVariables> を使用します。 サーバー変数と要求ヘッダーは、規則パターンが一致し、条件評価が成功した場合 (規則の構成によって、すべての条件が一致した場合、あるいは 1 つまたは複数の条件が一致した場合) にのみ設定されます。 serverVariables コレクションの各項目は、次の内容で構成されています。

  • 名前 - 設定するサーバー変数の名前を指定します。
  • 値 - サーバー変数の値を指定します。 値は、自由な形式の文字列で、次の情報を含めることができます。
    • 条件および規則パターンへの逆参照 (詳細については、逆参照の使用方法に関するセクションを参照してください)。
    • サーバー変数 (詳細については、サーバー変数の使用方法に関するセクションを参照してください)。
  • 置換 フラグ - サーバー変数の値が既に存在する場合は、この値を上書きするかどうかを指定します。 既定では、置換機能は有効になっています。

規則により、要求された URL が書き換えられ、名前 X_REQUESTED_URL_PATH でサーバー変数が設定されている例を次に示します。

<rule name=""Rewrite to index.php" stopProcessing="true"> 
     <match url="(.*)\.htm$" /> 
     <serverVariables> 
         <set name=""X_REQUESTED_URL_PATH" value="{R:1}" /> 
     </serverVariables> 
     <action type="Rewrite" url="index.php?path={R:1}" /> 
 </rule>

要求ヘッダーに関するメモ

要求ヘッダーは、サーバー変数と同じメカニズムを使用して設定されますが、特別な名前付け規則があります。 <serverVariables> コレクションのサーバー変数名が "HTTP_" で始まる場合、HTTP 要求ヘッダーは次の名前付け規則に従って設定されます。

  1. 名前のアンダースコア記号 ("_") はすべてダッシュ記号 ("-") に変換されます。
  2. 文字はすべて小文字に変換されます。
  3. 接頭辞 "HTTP_" は削除されます。

たとえば、要求にカスタムの x-original-host ヘッダーを設定する場合は次の構成を使用します。

<set name=""HTTP_X_ORIGINAL_HOST" value="{HTTP_HOST}" />

書き換えルールでの逆参照の使用

逆参照で、ルールまたは条件入力の一部をキャプチャできます。 これらを使用して、ルール アクション内で代替 URL を構築したり、ルールの条件の入力文字列を構築したりできます。

ルールに使用されるパターン構文の種類に応じて、逆参照の生成方法は異なります。 ECMAScript パターン構文を使用する場合、逆参照をキャプチャする必要があるパターンの部分をかっこで囲むことによって逆参照を作成できます。 たとえば、07/article.html という文字列から逆参照する場合、パターン ([0-9]+)/([a-z]+)\.html では、07 と article がキャプチャされます。 "ワイルドカード" パターン構文を使用する場合、アスタリスク記号 (*) をパターンで使用すると、常に逆参照が作成されます。

逆参照をキャプチャするパターン構文に関係なく、逆参照の使用方法は同じです。 逆参照は、書き換えルール内の次の場所で使用できます。

  • 条件入力文字列
  • ルール アクション (具体的には次の場所で使用されます)
    • 受信規則内の Rewrite アクションおよび Redirect アクションの url 属性
    • 送信規則内の Rewrite アクションの value 属性
    • CustomResponse アクションの statusLine および responseLine
  • 書き換えマップに対する key パラメーター

条件パターンへの逆参照は {C:N} (N は 0 から 9) で指定され、ルール パターンへの逆参照は {R:N} (N は 0 から 9) で指定されます。どちらの種類の逆参照の場合も、{R:0} および {C:0} には、一致した文字列が含まれます。

たとえば、次のパターンがあるとします。

^(www\.)(.*)$

文字列 www.foo.com について、逆参照すると、次のようにインデックスが作成されます。

{C:0} - www.foo.com
{C:1} - www.
{C:2} - foo.com

複数の条件でのキャプチャ グループの追跡

既定では、ルール アクション内で、ルール パターンおよびそのルールの最後に一致した条件に対して逆参照を使用できます。 たとえば、次のルールがあるとします。

<rule name=""Back-references with trackAllCaptures set to false"> 
  <match url='^article\.aspx' > 
  <conditions> 
     <add input="{QUERY_STRING}" pattern="p1=([0-9]+)" /> 
     <add input="{QUERY_STRING}" pattern="p2=([a-z]+)" />   
  </conditions> 
  <action type='Rewrite' url="article.aspx/{C:1}" /> <!-- rewrite action uses 
back-references to the last matched condition --> 
 </rule>

逆参照 {C:1} には、クエリ文字列パラメーター p2 の値となる 2 番目の条件のキャプチャ グループの値が常に含まれます。 p1 の値は、逆参照として使用できません。

URL 書き換えモジュール 2.0 では、キャプチャ グループのインデックス作成方法を変更できます。 <conditions> コレクションで trackAllCaptures 設定を有効にすると、一致するすべての条件のキャプチャ グループを逆参照して使用できます。 たとえば、次のルールがあるとします。

<rule name=""Back-references with trackAllCaptures set to true"> 
  <match url='^article\.aspx' > 
  <conditions trackAllCaptures="true"> 
     <add input="{QUERY_STRING}" pattern="p1=([0-9]+)" /> 
     <add input="{QUERY_STRING}" pattern="p2=([a-z]+)" />   
  </conditions> 
  <action type='Rewrite' url="article.aspx/{C:1}/{C:2}" /> <!-- rewrite action 
uses back-references to both conditions --> 
 </rule>

逆参照 {C:1} には、最初の条件のキャプチャ グループの値が含まれます。逆参照 {C:2} には、2 番目の条件のキャプチャ グループの値が含まれます。

trackAllCaptures を True に設定すると、条件キャプチャへの逆参照は {C:N} (N は 0 から すべてのルールの条件全体のキャプチャ グループの総数) で指定されます。 {C:0} には、最初の一致条件の一致文字列全体が含まれています。 たとえば、次の 2 つの条件があるとします。

<conditions 
trackAllCaptures="true"> 
     <add input="{REQUEST_URI}" pattern="^/([a-zA-Z]+)/([0-9]+)/$" /> 
     <add input="{QUERY_STRING}" pattern="p2=([a-z]+)" />   
  </conditions>

{REQUEST_URI} に "/article/23/" が含まれ、{QUERY_STRING} に "p1=123&p2=abc" が含まれている場合、条件を逆参照すると、次のようにインデックスが作成されます。

{C:0} - "/article/23/"
{C:1} - "article"
{C:2} - "23"
{C:3} - "abc"

書き換えられた URL の IIS ログへのログ記録

HTTP クライアントによって要求された元の URL をログ記録する代わりに、書き換えられた URL を IIS ログ ファイルにログ記録するようにモジュールを構成できます。 書き換えられた URL のログ記録を有効にするには、権限を昇格したコマンド プロンプトで次のコマンドを実行します。

reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp\Rewrite /v LogRewrittenUrl /t REG_DWORD /d 1

関連コンテンツ

記事