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

作成者: Ruslan Yakushev

ドキュメントのこのセクションは、IIS 7 の URL 書き換えモジュール バージョン 2.0 に適用されます

この記事では、URL 書き換えモジュール 2.0 の機能の概要と、このバージョンで使用される新しい構成の概念について説明します。 URL 書き換えモジュール 1.1 の構成の詳細については、「URL 書き換えモジュール構成リファレンス」を 参照してください

目次

機能の概要

IIS 用 Microsoft URL 書き換えモジュール 2.0 は、バージョン 1.1 のすべての機能を含む増分リリースであり、応答ヘッダーとコンテンツの書き換えのサポートを追加します。 このモジュールは、HTTP 応答に正規表現またはワイルドカード パターンを適用して、送信書き換えルールで表される書き換えロジックに基づいてコンテンツ パーツを見つけて置き換えます。 具体的には、モジュールを使用して次のことができます。

  • 応答 HTML 内の Web アプリケーションによって生成された URL を、よりわかりやすい検索エンジンに置き換えます。
  • リバース プロキシの背後にある Web アプリケーションによって生成された HTML マークアップ内のリンクを変更します。
  • 既存の HTTP ヘッダーを変更し、新しい応答 HTTP ヘッダーを設定します。
  • JavaScript、CSS、RSS など、HTTP 応答の内容を修正します。

警告

応答ヘッダーまたは応答コンテンツが送信書き換えルールによって変更される場合は、応答に挿入されるテキストにクライアント側の実行可能コードが含まれないように注意する必要があります。これにより、クロスサイト スクリプティングの脆弱性が発生する可能性があるためです。 これは、書き換えルールで HTTP ヘッダーやクエリ文字列などの信頼されていないデータを使用して、HTTP 応答に挿入される文字列を構築する場合に特に重要です。 このような場合、置換文字列は HtmlEncode 関数を使用して HTML エンコードする必要があります。次に例を示します。

<action type="Rewrite" value="{HtmlEncode:{HTTP_REFERER}}" />

送信規則の概要

応答の書き換えに使用されるメイン構成の概念は、送信規則の概念です。 送信ルールは、応答コンテンツを比較または照合するロジックと、比較が成功した場合の対処方法を表すために使用されます。

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

  • 事前条件 - オプションの事前条件は、ルールの評価を開始する前に要求メタデータをチェックするために使用されます。 事前条件は、要求メタデータに対するいくつかの条件付きチェックで構成される場合があり、画像やビデオ ファイルなど、書き換えてはいけない応答を除外するために使用できます。
  • タグ フィルター - タグ フィルターは、既知のタグまたはカスタム定義タグのセットに対する応答内の検索を絞り込むために使用されます。 タグ フィルターでは、指定したタグのコンテンツのみがルール パターンと照合され、応答コンテンツ全体がパターンと照合されるのとは対照的です。
  • パターン – ルール パターンは、正規表現または応答コンテンツ内の検索に使用される野生カード パターンを指定するために使用されます。
  • Conditions – オプションの条件コレクションは、応答コンテンツ内でパターン一致が見つかった場合に実行する追加の論理操作を指定するために使用されます。 条件内で、HTTP ヘッダーまたはサーバー変数の特定の値をチェックできます。
  • アクション – このアクションは、パターンの一致が見つかり、すべてのルール条件が正常に評価された場合の対処方法を指定するために使用されます。

ルールの実行

送信規則を実行するプロセスは、受信規則に使用されるプロセスとは異なります。 入力は単一の要求 URL 文字列であるため、受信ルール セットは要求ごとに 1 回だけ評価されます。 送信ルール セットは、HTTP 応答コンテンツ内の複数の場所で適用されているため、応答ごとに何度も評価される場合があります。 たとえば、次のようなルールセットがある場合は、次のようになります。

ルール 1: タグと <img> タグに<>適用される

規則 2: タグに<>適用される

HTML 応答には、次のマークアップが含まれています。

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

その後、URL 書き換えモジュール 2.0 では、ルール 1 が "/default.aspx" 文字列に対して評価されます。 ルールが正常に実行された場合、ルール 1 の出力が Rule2 に渡されます。 ルール 2 が正常に実行された場合、ルール 2 の出力を使用して、応答のタグ内の href 属性の内容が<>置き換えられます。

その後、URL 書き換えモジュール 2.0 では、Rule1 が "/logo.jpg" 文字列に対して評価されます。 ルールが正常に実行された場合、その出力は、応答の img> タグ内の src 属性の内容を<置き換えるために使用されます。

ルールの継承

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

送信規則の構成

事前条件の収集

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

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

  • logicalGrouping="MatchAll" が使用されている場合、内部のすべての事前条件は true に評価されました。
  • logicalGrouping="MatchAny" が使用されている場合、少なくとも 1 つの事前条件が true に評価されました。

事前条件は、次のプロパティを指定することによって定義されます。

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

さらに、条件前評価の結果は、否定属性を使用して否定できます。

応答コンテンツ タイプが text/html の場合にチェックする事前条件の例:

<preConditions>
    <preCondition name="IsHTML">
        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
    </preCondition>
</preConditions>

タグ フィルター

タグ フィルターを使用して、応答コンテンツ内の検索を一連の既知の HTML タグまたはカスタム定義 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 には、送信規則で使用できる定義済みのタグのセットが含まれています。 次の表に、事前に定義されたすべてのタグと属性を示します。その値は送信ルール パターンの入力として使用されます。

Tag 属性
A href
面グラフ href
ベース href
Form action
フレーム src、longdesc
Head プロファイル
iFrame src、longdesc
画像 src、longdesc、usemap
入力 src、usemap
リンク href
スクリプト 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 要素で filterByTags 属性が指定されていない場合、パターンは応答コンテンツ全体に適用されます。 応答コンテンツ全体に対する正規表現パターンの評価は CPU 負荷の高い操作であり、Web アプリケーションのパフォーマンスに影響を与える可能性があります。 完全な応答パターン マッチングによって発生するパフォーマンス オーバーヘッドを減らすには、いくつかのオプションがあります。

  • IIS ユーザー モードのキャッシュを使用し、outboundRules> 要素の <rewriteBeforeCache 属性を true に設定します。

    <outboundRules rewriteBeforeCache="true">
    

    チャンク転送エンコードを応答に使用する場合は、この設定を使用しないでください。

  • ルールの match 要素の occurrences 属性を使用します。 たとえば、あるルールを使用していくつかの HTML フラグメントをヘッド要素に<挿入し、そのルールに終了タグ </head> を検索するパターンがある場合は、occurrences="1" を設定>できます。 これにより、/head> タグが見つかった後、応答の再メインder の検索を停止するように書き換えモジュールに<指示されます。

    <match pattern="&lt;/head&gt;" occurrences="1" />
    

ルール パターンの構文

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

ECMAScript – Perl 互換 (ECMAScript 標準準拠) 正規表現構文。 これは、任意のルールの既定のオプションです。 これはパターン形式の例です: "^([_0-9a-zA-Z-]+/)?(wp-.*)"

ワイルドカードIIS HTTP リダイレクト モジュールで使用される Wildカード 構文。 これは、"/Scripts/*.js" という形式のパターンの例です。アスタリスク ("*") は、"任意の数の文字に一致し、バックリファレンスでキャプチャ" を意味します。 ルールにタグ フィルターがない場合は、wildカード パターン型を使用できないことに注意してください。

ExactMatch - 入力文字列内で正確な文字列検索が実行されます。

patternSyntax 属性のスコープはルールごとであり、現在のルールのパターンとそのルールの条件内で使用されるすべてのパターンに適用されます。

ルール パターンのプロパティ

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

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

ルールの条件

ルール条件を使用すると、現在の入力文字列以外の入力に基づいて、ルール評価用の追加ロジックを定義できます。 任意のルールに 0 個以上の条件を設定できます。 ルールの条件は、ルール パターンの一致が成功した後に評価されます。

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

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

条件は、次のプロパティを指定することによって定義されます。

  • 入力文字列 - 条件入力では、条件評価の入力として使用する項目を指定します。 条件入力は、サーバー変数と、以前の条件パターンやルール パターンへのバック参照を含めることができる任意の文字列です。

  • パターン – 条件入力で検索するパターン。 パターンは、正規表現構文を使用するか、またはワイルドカード構文を使用して指定できます。 条件で使用するパターンの種類は、この条件が 属するルールに対して定義されている patternSyntax フラグの値によって異なります。 この条件の種類には、パターン マッチングを制御する 2 つの関連属性があります。

    • pattern – この属性を使用して、実際のパターンを指定します。
    • ignoreCase – この属性を使用して、条件のパターン マッチングで大文字と小文字を区別するか、大文字と小文字を区別するかを制御します。

ルール アクション

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

書き換えアクション

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

  • 条件とルール パターンへのバックリファレンス。 (詳細については、バックリファレンスの使用方法に関するセクションを参照してください)。
  • サーバー変数。 (詳細については、サーバー変数の使用方法に関するセクションを参照してください。

None アクション

アクションを実行する必要がないことを指定するために、アクションは使用されません。

書き換えルールからの応答ヘッダーへのアクセス

応答 HTTP ヘッダーの内容は、サーバー変数にアクセスする場合と同じ構文を使用して、書き換え規則内から取得できますが、特別な名前付け規則を使用します。 サーバー変数が "RESPON Standard Edition_" で始まる場合は、次の名前付け規則を使用して名前が決定される HTTP 応答ヘッダーの内容が格納されます。

  1. 名前内のすべてのアンダースコア ("_") 記号は、ダッシュ記号 ("-") に変換されます。
  2. "RESPON Standard Edition_" プレフィックスが削除されました

たとえば、次の事前条件を使用して、content-type ヘッダーのコンテンツを評価します。

<preCondition name="IsHTML">
    <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
</preCondition>

要求ヘッダーとサーバー変数の設定

URL 書き換えモジュール 2.0 の受信書き換え規則を使用して、要求ヘッダーとサーバー変数を設定できます。

許可されるサーバー変数の一覧

グローバル書き換えルールを使用して、要求ヘッダーとサーバー変数を設定したり、既存の要求ヘッダーやサーバー変数を上書きしたりできます。 分散書き換えルールでは、allowedServerVariables> サーバー変数の許可リストで定義されている要求ヘッダーとサーバー変数<のみを設定または上書きできます。 分散書き換え規則が、allowedServerVariables> コレクションにリストされていないサーバー変数または HTTP ヘッダーを<設定しようとすると、URL 書き換えモジュールによってランタイム エラーが生成されます。 allowedServerVariables> コレクションは<、既定では applicationHost.config ファイルに格納され、IIS サーバー管理者のみが変更できます。

受信書き換えルールを使用して要求ヘッダーとサーバー変数を設定する

ルール要素 <serverVariables> は、設定するサーバー変数と http ヘッダーのコレクションを定義するために使用されます。 これらは、ルール パターンが一致し、条件の評価が成功した場合にのみ設定されます (ルールの構成に応じて、すべての条件が一致するか、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>

注: 上記の例を機能させるには、allowedServerVariables> コレクションにX_REQUESTED_URL_PATHを<追加する必要があります。

<rewrite>
    <allowedServerVariables>
        <add name="X_REQUESTED_URL_PATH" />
    </allowedServerVariables>
</rewrite>

要求ヘッダーに関する注意

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

  1. 名前内のすべてのアンダースコア ("_") 記号は、ダッシュ記号 ("-") に変換されます。
  2. すべての文字は小文字に変換されます。
  3. "HTTP_" プレフィックスが削除されました

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

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

応答ヘッダーの設定

URL 書き換えモジュール 2.0 の送信書き換え規則を使用して、新規または既存の応答 HTTP ヘッダーを設定できます。 応答 HTTP ヘッダーは、サーバー変数の場合と同じ構文を使用し、「書き換え規則からの応答ヘッダーへのアクセス」で説明されている名前付け規則を使用して、送信規則内でアクセスされます。

送信書き換えルールの match> 要素の <serverVariable 属性に値がある場合は、この書き換えルールが対応する応答ヘッダーの内容に対して動作することを示します。 たとえば、次の規則は、応答ヘッダー "x-custom-header" を設定します

<outboundRules>
    <rule name="Set Custom Header">
        <match serverVariable="RESPONSE_X_Custom_Header" pattern="^$" />
        <action type="Rewrite" value="Something" />
    </rule>
</outboundRules>

書き換えルールのパターンは、指定された応答ヘッダーの内容に適用され、ルールのパターンとオプションの条件が正常に評価された場合、その応答ヘッダーの値が書き換えられます。

正規表現パターンと、書き換えルール内の既存の要求ヘッダーと応答ヘッダーに簡単にアクセスできることにより、応答 HTTP ヘッダーを書き換えるロジックを定義する際に多くの柔軟性が得られます。 たとえば、次の書き換えルールを使用して、リダイレクト応答の Location ヘッダーの内容を変更できます。

<outboundRules>
    <!-- This rule changes the domain in the HTTP location header for redirection responses -->
    <rule name="Change Location Header">
        <match serverVariable="RESPONSE_LOCATION" pattern="^http://[^/]+/(.*)" />
        <conditions>
            <add input="{RESPONSE_STATUS}" pattern="^301" />
        </conditions>
        <action type="Rewrite" value="http://{HTTP_HOST}/{R:1}"/>
    </rule>
</outboundRules>

書き換えルールでのバックリファレンスの使用

ルールまたは条件の入力の一部は、バックリファレンスでキャプチャできます。 これらを使用して、ルール アクション内に置換 URL を作成したり、ルール条件の入力文字列を作成したりできます。

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

バック参照の使用は、キャプチャに使用されたパターン構文に関係なく同じです。 バック参照は、書き換えルール内の次の場所で使用できます。

  • 条件入力文字列

  • ルール アクションでは、具体的には次の操作を行います。

    • 受信ルールの書き換えアクションとリダイレクト アクションの url 属性
    • 送信ルールの書き換えアクションの value 属性
    • CustomResponse アクションの statusLine と responseLine
  • 書き換えマップのキー パラメーター

条件パターンへのバックリファレンスは {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 では、キャプチャ グループのインデックス付け方法を変更できます。 条件>コレクションで <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 のログ記録を有効にするには、ルール <のアクション> 要素の logRewrittenUrl 属性を使用します。例:

<rule name="set server variables">
    <match url="^article/(\d+)$" />
    <action type="Rewrite" url="article.aspx?id={R:1}" logRewrittenUrl="true" />
</rule>