Использование RewriteMap

Этот документ дополняет mod_rewrite справочную документацию. В нём описывается использование директивы RewriteMap и приводятся примеры каждого из различных типов RewriteMap.

Введение

Директива RewriteMap определяет внешнюю функцию, которую можно вызвать в контексте директив RewriteRule или RewriteCond для выполнения переписывания, слишком сложного или специализированного, чтобы его можно было выполнить только с помощью регулярных выражений. Источником этого поиска может быть любой из типов, перечисленных в разделах ниже и в справочной документации RewriteMap.

Синтаксис директивы RewriteMap выглядит следующим образом:

RewriteMap MapName MapType:MapSource

MapName — произвольное имя, присваиваемое карте и используемое в последующих директивах. Аргументы передаются карте с помощью следующего синтаксиса:

${ MapName : LookupKey }
${ MapName : LookupKey | DefaultValue }

При появлении такой конструкции выполняется обращение к карте MapName и поиск ключа LookupKey. Если ключ найден, конструкция функции карты заменяется на SubstValue. Если ключ не найден, она заменяется на DefaultValue или пустую строку, если значение DefaultValue не указано.

Например, можно определить RewriteMap следующим образом:

RewriteMap examplemap "txt:/path/to/file/map.txt"

Затем эту карту можно использовать в RewriteRule следующим образом:

RewriteRule "^/ex/(.*)" "${examplemap:$1}"

Можно указать значение по умолчанию на случай, если в карте ничего не найдено:

RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"

В следующих разделах описаны различные типы MapType и приведены примеры каждого из них.

int: внутренняя функция

При использовании типа MapType int в качестве MapSource указывается одна из доступных внутренних функций RewriteMap. Авторы модулей могут предоставлять дополнительные внутренние функции, регистрируя их через API ap_register_rewrite_mapfunc. По умолчанию доступны следующие функции:

• toupper:
  Преобразует ключ в верхний регистр.
• tolower:
  Преобразует ключ в нижний регистр.
• escape:
  Преобразует специальные символы в ключе в шестнадцатеричные коды.
• unescape:
  Преобразует шестнадцатеричные коды в ключе обратно в специальные символы.

Чтобы использовать одну из этих функций, создайте RewriteMap со ссылкой на функцию int, а затем используйте её в RewriteRule:

Перенаправление URI на его версию в нижнем регистре

RewriteMap lc int:tolower
RewriteRule "(.*)" "${lc:$1}" [R]

txt: текстовые карты

При использовании типа MapType txt в качестве MapSource указывается путь в файловой системе к текстовому файлу карты, содержащему по одной паре ключ/значение, разделённой пробелом, на строку. При необходимости строка может содержать комментарий, начинающийся с символа «#».

Корректный файл текстовой карты переписывания должен иметь следующий синтаксис:

# Comment line
MatchingKey SubstValue
MatchingKey SubstValue # comment

При вызове RewriteMap аргумент ищется в первом поле каждой строки; если он найден, возвращается соответствующее значение подстановки.

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

Конфигурация преобразования названий товаров в идентификаторы

RewriteMap product2id "txt:/etc/apache2/productmap.txt"
RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

Предполагается, что скрипт prods.php знает, что делать, если он получил аргумент id=NOTFOUND, означающий, что товар не найден в карте поиска.

Файл /etc/apache2/productmap.txt содержит следующее:

##
## productmap.txt - Product to ID map file
##

television 993
stereo 198
fishingrod 043
basketball 418
telephone 328

Таким образом, при запросе http://example.com/product/television применяется RewriteRule, а запрос внутренне преобразуется в /prods.php?id=993.

RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

rnd: случайный выбор из текстовой карты

При использовании типа MapType rnd в качестве MapSource указывается путь в файловой системе к текстовому файлу карты. Каждая строка содержит ключ и одно или несколько значений, разделённых |. При совпадении ключа одно из этих значений выбирается случайным образом.

Например, с помощью следующего файла карты и директив можно организовать случайную балансировку нагрузки между несколькими серверами приложений через обратный прокси-сервер. Изображения отправляются на один из серверов в пуле «static», а все остальные запросы — на один из серверов в пуле «dynamic».

##
## map.txt -- rewriting map
##

static www1|www2|www3|www4
dynamic www5|www6

Директивы конфигурации

RewriteMap servers "rnd:/path/to/file/map.txt"

RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1"  [NC,P,L]
RewriteRule "^/(.*)"                "http://${servers:dynamic}/$1" [P,L]

Итак, когда запрашивается изображение и срабатывает первое из этих правил, RewriteMap выполняет поиск строки static в файле карты. В результате случайным образом выбирается одно из указанных имён хостов, которое затем используется в целевом адресе RewriteRule.

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

static www1|www1|www2|www3|www4

dbm: хеш-файл DBM

При использовании типа MapType dbm в качестве MapSource указывается путь в файловой системе к файлу базы данных DBM, содержащему пары ключ/значение для карты. Это работает так же, как карта txt, но значительно быстрее, поскольку DBM индексируется, а текстовый файл — нет. Благодаря этому нужный ключ находится быстрее.

При необходимости можно указать конкретный тип DBM:

RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"

Типом может быть sdbm, gdbm, ndbm или db. Однако рекомендуется использовать утилиту httxt2dbm, поставляемую с Apache HTTP Server: она выберет подходящую библиотеку DBM, соответствующую той, с помощью которой был собран сам httpd.

Чтобы создать файл DBM, сначала создайте текстовый файл карты, как описано в разделе txt. Затем выполните httxt2dbm:

$ httxt2dbm -i mapfile.txt -o mapfile.map

После этого полученный файл можно указать в директиве RewriteMap:

RewriteMap mapname "dbm:/etc/apache/mapfile.map"

prg: внешняя программа переписывания

При использовании типа MapType prg в качестве MapSource указывается путь в файловой системе к исполняемой программе, реализующей поведение карты. Это может быть скомпилированный двоичный файл или программа на интерпретируемом языке, например Perl или Python.

Эта программа запускается один раз при запуске Apache HTTP Server, а затем взаимодействует с механизмом переписывания через STDIN и STDOUT. То есть для каждого поиска по функции карты она получает один аргумент через STDIN и должна вернуть через STDOUT одну строку ответа, завершённую символом новой строки. Если соответствующего значения нет, программа карты должна вернуть четырёхсимвольную строку «NULL».

Внешние программы переписывания не запускаются, если они определены в контексте, где для RewriteEngine не установлено значение on.

По умолчанию внешние программы переписывания выполняются от имени пользователя и группы, запустивших httpd. В системах UNIX это можно изменить, передав имя пользователя и имя группы третьим аргументом в RewriteMap в формате username:groupname.

Эта возможность использует мьютекс rewrite-map, необходимый для надёжного взаимодействия с программой. Механизм мьютекса и файл блокировки можно настроить с помощью директивы Mutex.

Ниже показан простой пример, который заменяет все дефисы в URI запроса символами подчёркивания.

Конфигурация переписывания

RewriteMap d2u "prg:/www/bin/dash2under.pl" apache:apache
RewriteRule "-" "${d2u:%{REQUEST_URI}}"

dash2under.pl

#!/usr/bin/perl
$| = 1; # Turn off I/O buffering
while (<STDIN>) {
    s/-/_/g; # Replace dashes with underscores
    print $_;
}

dbd или fastdbd: SQL-запрос

При использовании типа MapType dbd или fastdbd в качестве MapSource указывается SQL-оператор SELECT, который принимает один аргумент и возвращает одно значение.

Для выполнения этого оператора необходимо настроить mod_dbd, указав правильную базу данных.

Этот тип MapType имеет две разновидности. При использовании dbd запрос выполняется при каждом обращении к карте, а при использовании fastdbd результаты запросов к базе данных кэшируются. Поэтому, хотя fastdbd работает эффективнее и, следовательно, быстрее, изменения в базе данных не будут учтены до перезапуска сервера.

Если запрос возвращает несколько строк, используется случайная строка из набора результатов.

RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"

Итоги

Директива RewriteMap может встречаться несколько раз. Для каждой функции отображения используйте отдельную директиву RewriteMap, чтобы объявить соответствующий файл карты переписывания.

Хотя объявлять карту в контексте отдельного каталога (в файлах .htaccess или блоках <Directory>) нельзя, её можно использовать в контексте отдельного каталога.