Справочник по конфигурации модуля переопределения URL-адресов 2.0

Руслан Якушев

Этот раздел документации относится к модулю переопределения URL-адресов версии 2.0 для IIS 7

В этой статье представлен обзор функциональных возможностей модуля перезаписи URL-адресов 2.0 и описаны новые понятия конфигурации, используемые в этой версии. Подробные сведения о конфигурации перезаписи URL-адресов 1.1 см. в справочнике по конфигурации модуля переопределения URL-адресов.

Таблица содержимого

Общие сведения о функциях

Модуль перезаписи URL-адресов Майкрософт 2.0 для IIS — это добавочный выпуск, который включает все функции версии 1.1 и добавляет поддержку заголовков ответов и перезаписи содержимого. Модуль применяет регулярные выражения или шаблон wild карта s к http-ответу, чтобы найти и заменить части содержимого на основе логики перезаписи, выраженной правилами перезаписи исходящего трафика. В частности, модуль можно использовать для:

  • Замените URL-адреса, созданные веб-приложением в HTML-коде ответа, более понятным и понятным для поисковой системы.
  • Измените ссылки в разметке HTML, созданной веб-приложением за обратным прокси-сервером.
  • Измените существующие и задайте новые заголовки HTTP ответа.
  • Исправьте содержимое любого HTTP-ответа, включая JavaScript, CSS, RSS и т. д.

Предупреждение

При изменении заголовков ответов или содержимого ответа правилом перезаписи исходящего трафика следует соблюдать дополнительную осторожность, чтобы убедиться, что текст, вставленный в ответ, не содержит исполняемый код на стороне клиента, что может привести к уязвимостям в межсайтовых сценариях. Это особенно важно, если правило перезаписи использует ненадежные данные, такие как заголовки HTTP или строка запроса, для создания строки, которая будет вставлена в ответ HTTP. В таких случаях строка замены должна быть закодирована с помощью функции HtmlEncode , например:

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

Общие сведения о правилах исходящего трафика

Основная концепция конфигурации, используемая для перезаписи ответов, — это концепция правила исходящего трафика. Правило исходящего трафика используется для выражения логики сравнения или сопоставления содержимого ответа и того, что делать, если сравнение выполнено успешно.

Концептуально правило исходящего трафика состоит из следующих частей:

  • Предварительное условие — необязательное условие используется для проверка метаданных запроса перед началом оценки правил. Предварительное условие может состоять из нескольких условных проверка для метаданных запроса, и его можно использовать для фильтрации ответов, которые не должны быть перезаписаны, например изображения или видеофайлы.
  • Фильтры тегов — фильтры тегов используются для сузки поиска в ответе на набор известных или настраиваемых тегов. При фильтрации тегов содержимое указанных тегов сопоставляется с шаблоном правила, а не соответствует всему содержимому ответа в шаблоне.
  • Шаблон — шаблон правила используется для указания регулярного выражения или дикого карта шаблона, который будет использоваться для поиска в содержимом ответа.
  • Условия — коллекция необязательных условий используется для указания дополнительных логических операций для выполнения, если совпадение шаблонов найдено в содержимом ответа. В условиях можно проверка для определенных значений заголовков HTTP или переменных сервера.
  • Действие — действие используется для указания того, что делать, если совпадение шаблона найдено, и все условия правила были успешно оценены.

Выполнение правил

Процесс выполнения правил исходящего трафика отличается от того, который используется для правил входящего трафика. Набор правил для входящего трафика вычисляется только один раз на запрос, так как его входные данные — это только одна строка URL-адреса запроса. Набор правил исходящего трафика может оцениваться несколько раз на ответ, так как он применяется в нескольких местах в содержимом ответа HTTP. Например, если существует набор правил, как показано ниже:

Правило 1. Применяется к <тегу и <тегу> img>

Правило 2. Применимо к <тегу>

и HTML-ответ содержит эту разметку:

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

Затем модуль перезаписи URL-адресов 2.0 будет оценивать правило 1 по строке "/default.aspx". Если правило выполнено успешно, выходные данные правила 1 будут переданы Правилу 2. Если правило 2 выполнено успешно, выходные данные правила 2 будут использоваться для замены содержимого атрибута href в теге в <> ответе.

После этого модуля перезаписи URL-адресов 2.0 будет оценивать rule1 со строкой "/logo.jpg". Если правило было выполнено успешно, его выходные данные будут использоваться для замены содержимого атрибута src в <теге img> в ответе.

Наследование правил

Если правила определены на нескольких уровнях конфигурации, модуль перезаписи URL-адресов оценивает набор правил, включающий распределенные правила из родительских уровней конфигурации, а также правила из текущего уровня конфигурации. Оценка выполняется в порядке родительского к дочернему, что означает, что родительские правила вычисляются сначала, а правила, определенные на последнем дочернем уровне, оцениваются последним.

Конфигурация правила исходящего трафика

Сбор предварительных условий

Предварительные условия используются для проверка, если правило должно оцениваться в отношении содержимого ответа. Коллекция условий определяется как именованной коллекции в <разделе preConditions>, и она может содержать одну или несколько проверка условий. Правило исходящего трафика ссылается на коллекцию предварительных условий по имени.

Коллекция предварительных условий имеет атрибут, называемый логическим группированием , который определяет, как вычисляются условия. Коллекция предварительных условий оценивается как true, если:

  • Все предварительные условия в пределах были оценены как true, при условии, что использовался логическийgrouping="MatchAll".
  • По крайней мере одно из предварительных условий было оценено как true, при условии, что использовалось логическое группирование="MatchAny".

Предопределенное условие определяется путем указания следующих свойств:

  • Входная строка — входные данные предварительного условия указывают, какой элемент следует использовать в качестве входных данных для оценки условия. Входные данные предварительного условия — это произвольная строка, которая может включать переменные сервера и обратные ссылки на предыдущие шаблоны условий.
  • Шаблон — шаблон предварительного условия можно указать с помощью синтаксиса регулярных выражений или с помощью синтаксиса wild карта. Тип шаблона, используемый в предварительном условии, зависит от значения флага patternSyntax, определенного для коллекции предварительных условий.

Кроме того, результат оценки предварительного условия можно отрицать с помощью атрибута negate .

Пример предварительного условия, который проверка, если тип контента ответа — text/html:

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

Фильтры тегов

Фильтры тегов используются для сузки поиска в содержимом ответа до набора известных или настраиваемых тегов HTML. Если правило перезаписи использует фильтры тегов, а не сопоставляет шаблон правила со всем ответом, модуль переопределения URL-адресов 2.0 ищет HTML-теги, перечисленные в фильтре тегов правила, а затем принимает содержимое атрибута URL-адреса этого тега и оценивает его по шаблону правила. Фильтры тегов задаются в атрибуте <filterByTags элемента сопоставления> правила исходящего трафика. Например:

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

Если http-ответ содержит тег привязки, например:

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

Затем шаблон правила переопределения будет вычисляться по строке: "/article.aspx?id=1".

Предварительно определенные теги

Модуль перезаписи URL-адресов 2.0 содержит набор предварительно определенных тегов, которые можно использовать с правилами исходящего трафика. В таблице ниже перечислены все предварительно определенные теги и атрибуты, значения которых будут использоваться в качестве входных данных для шаблона правила исходящего трафика:

Тег Атрибуты
а href
Площадь href
База href
Форма действие
Кадр 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.*)" />

Шаблон правила

Шаблон правила используется для указания соответствия входной строки правила. Входные данные правила отличаются в зависимости от конфигурации правила:

  • Если правило использует фильтры тегов, содержимое сопоставленного тега будет передано в качестве входных данных для сопоставления шаблонов.
  • Если правило не использует фильтры тегов, все содержимое ответа будет передано в качестве входных данных для сопоставления шаблонов.

Шаблон указывается в элементе <сопоставления> правила переопределения.

Сопоставление шаблонов полного ответа

Если атрибут filterByTags не указан в элементе сопоставления правила, шаблон будет применен ко всему содержимому ответа. Оценка шаблонов регулярных выражений во всем содержимом ответа является интенсивной операцией ЦП и может повлиять на производительность веб-приложения. Существует несколько вариантов снижения затрат на производительность, представленных в соответствии с шаблоном полного ответа:

  • Используйте кэширование пользовательского режима IIS и задайте атрибут перезаписиBeforeCache элемента <outboundRules> значение true:

    <outboundRules rewriteBeforeCache="true">
    

    Обратите внимание, что этот параметр не следует использовать, если для ответов используется кодирование фрагментированного переноса.

  • Используйте атрибут вхождения элемента сопоставления правила. Например, если вы используете правило для вставки фрагмента HTML в <головной> элемент, и это правило имеет шаблон, который ищет закрывающий тег - </head>, то можно задать вхождения="1". Это позволит модулю перезаписи прекратить поиск оставшейся части ответа после обнаружения тега </head> .

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

Синтаксис шаблона правила

Синтаксис шаблона правила можно указать с помощью атрибута patternSyntax правила. Этот атрибут можно задать для одного из следующих параметров:

ECMAScript — синтаксис регулярного выражения, совместимый с Perl (стандарт ECMAScript ). Это параметр по умолчанию для любого правила. Это пример формата шаблона: "^([_0-9a-zA-Z-]+/)? (wp-.*)"

Wild карта — синтаксис Wild карта используется в модуле перенаправления HTTP IIS. Это пример шаблона в этом формате: "/Scripts/*.js", где звездочка ("*") означает "соответствовать любому числу любых символов и записывать их в обратную ссылку". Обратите внимание, что тип шаблона wild карта нельзя использовать, если правило не имеет фильтров тегов.

ExactMatch — точный поиск строк выполняется в входной строке.

Область атрибута patternSyntax является правилом, то есть применяется к шаблону текущего правила и ко всем шаблонам, используемым в условиях этого правила.

Свойства шаблона правила

Шаблон можно отрицать с помощью атрибута <negate элемента match>. Если этот атрибут используется, действие правила будет выполняться только в том случае, если входная строка не соответствует указанному шаблону.

По умолчанию используется сопоставление шаблонов без учета регистра. Чтобы включить конфиденциальность регистра, можно использовать атрибут ignoreCase элемента сопоставления><правила.

Условия правила

Условия правила позволяют определить дополнительную логику для оценки правила, которая может быть основана на входных данных, отличных от текущей входной строки. Любое правило может иметь ноль или более условий. Условия правила оцениваются после успешного сопоставления шаблона правила.

Условия определяются в <коллекции условий> правила переопределения. Эта коллекция имеет атрибут, называемый логическим группированием , который определяет, как оцениваются условия. Если правило имеет условия, действие правила будет выполняться только в том случае, если шаблон правила соответствует и:

  • Все условия были оценены как true, при условии, что использовалось логическое группирование="MatchAll".
  • По крайней мере одно из условий было оценено как true, при условии, что использовался логическийgrouping="MatchAny".

Условие определяется путем указания следующих свойств:

  • Входные строки— условие указывает, какой элемент следует использовать в качестве входных данных для оценки условия. Входные данные условия — это произвольная строка, которая может включать переменные сервера и обратные ссылки на предыдущие шаблоны условий и (или) шаблонов правил.

  • Шаблон — шаблон для поиска в входных данных условия. Шаблон можно указать с помощью синтаксиса регулярного выражения или с помощью синтаксиса wild карта. Тип шаблона, используемый в условии, зависит от значения флага patternSyntax , определенного для правила, к которому принадлежит это условие. Этот тип условия имеет два связанных атрибута, которые управляют сопоставлением шаблонов:

    • шаблон — используйте этот атрибут для указания фактического шаблона.
    • ignoreCase — используйте этот атрибут для управления соответствием шаблонов условию, чувствительным к регистру или не учитывает регистр.

Действие правила

Действие перезаписи правила выполняется при совпадении входной строки с шаблоном правила и успешной оценкой условия (в зависимости от конфигурации правила все условия соответствуют или одному или нескольким условиям). Доступны два типа действий, а атрибут <типа элемента конфигурации действия> можно использовать для указания действия, которое должно выполнять правило. В следующих разделах описаны различные типы действий и параметры конфигурации, связанные с конкретными типами действий.

Действие перезаписи

Действие перезаписи заменяет текущую строку ввода правила строкой подстановки. Строка подстановки указывается в атрибуте <значения элемента действия> правила. Строка подстановки — это строка свободной формы, которая может включать в себя следующее:

  • Обратная ссылка на шаблоны условий и правил. (Дополнительные сведения см. в разделе об использовании обратных ссылок.)
  • Переменные сервера. (Дополнительные сведения см. в разделе об использовании переменных сервера.)

Действие None

Ни одно действие не используется для указания того, что действие не должно выполняться.

Доступ к заголовкам ответа из правил переопределения

Содержимое любого заголовка HTTP ответа можно получить из правила перезаписи с помощью того же синтаксиса, что и для доступа к переменным сервера, но с особым соглашением об именовании. Если переменная сервера начинается с "RESPONSE_", она сохраняет содержимое заголовка ответа HTTP, имя которого определяется с помощью следующего соглашения об именовании:

  1. Все символы подчеркивания ("_") в имени преобразуются в символы дефиса ("-").
  2. Префикс "RESPONSE_" удаляется

Например, для оценки содержимого заголовка типа контента используется следующее условие:

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

Настройка заголовков запросов и переменных сервера

Правила входящего переопределения в модуле переопределения URL-адресов 2.0 можно использовать для задания заголовков запросов и переменных сервера.

Список разрешенных переменных сервера

Правила глобальной перезаписи можно использовать для задания всех заголовков запросов и переменных сервера, а также перезаписи существующих. Правила распределенной перезаписи могут задавать и перезаписывать заголовки запросов и переменные сервера, определенные в списке разрешенных для переменных сервера, разрешенныхServerVariables<>. Если правило распределенной перезаписи пытается задать любую переменную сервера или заголовок HTTP, который не указан в <коллекции allowedServerVariables> , ошибка среды выполнения будет создана модулем переопределения URL-адресов. Коллекция <allowedServerVariables> по умолчанию хранится в файле applicationHost.config и может изменяться только администратором сервера IIS.

Использование правил переопределения входящего трафика для задания заголовков запросов и переменных сервера

Элемент правила <serverVariables> используется для определения коллекции переменных сервера и заголовков HTTP для задания. Они будут заданы только в том случае, если шаблон правила соответствует и оценка условия выполнена успешно (в зависимости от конфигурации правила все условия соответствуют или одному или нескольким условиям). Каждый элемент в <коллекции 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>

Примечание. Для работы приведенного выше примера необходимо добавить X_REQUESTED_URL_PATH в <коллекцию allowedServerVariables> :

<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 ответа доступны в правилах исходящего трафика с помощью того же синтаксиса, что и для переменных сервера и с помощью соглашения об именовании, как описано в разделе "Доступ к заголовкам ответа из правил перезаписи".

Если атрибут <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-адреса действия перезаписи и перенаправления в правилах входящего трафика
    • атрибут значения действия Переопределения в правилах исходящего трафика
    • statusLine и responseLine действия CustomResponse
  • В ключевом параметре для сопоставления перезаписи

Обратные ссылки на шаблоны условий определяются {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. Значение 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} будет содержать значение группы захвата из второго условия.

Если для trackAllCaptures задано значение true, то обратные ссылки на условие определяются {C:N}, где N — от 0 до общего числа групп отслеживания во всех условиях правила. {C:0} содержит всю соответствующую строку из первого соответствующего условия. Например, для этих двух условий:

<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} — "статья"
{C:2} — "23"
{C:3} - "abc"

Ведение журнала переопределенных URL-адресов в журналы IIS

Правило распределенного перезаписи входящего трафика можно настроить для записи URL-адресов, перезаписываемых в файлы журнала IIS, а не для ведения журнала исходных URL-адресов, запрошенных HTTP-клиентом. Чтобы включить ведение журнала перезаписных URL-адресов, используйте атрибут logRewrittenUrl элемента действия> правила<, например:

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