Utilisation de RewriteMap

Introduction

La directive RewriteMap d�finit une fonction externe qui peut �tre appel�e depuis une directive RewriteRule ou RewriteCond pour accomplir une r��criture trop compliqu�e, ou trop sp�cialis�e pour �tre effectu�e � partir d'expressions rationnelles. Vous trouverez ci-dessous les diff�rents types disponibles pour la source de donn�es, ceux-ci �tant par ailleurs �num�r�s dans la documentation de r�f�rence de RewriteMap.

La syntaxe de la directive RewriteMap est la suivante :

RewriteMap MapName MapType:MapSource

L'argument MapName est un nom arbitraire que vous associez � la table de correspondances, et que vous pourrez utilisez par la suite dans les directives de r��criture. Les recherches dans la table de correspondance s'effectuent en respectant cette syntaxe :

${ nom-map : cl�-recherche }
${ nom-map : cl�-recherche | DefaultValue }

Lorsque cette syntaxe est employ�e, la table de correspondances nom-map est consult�e et la cl� cl�-recherche recherch�e. Si la cl� est trouv�e, la fonction de recherche dans la table de correspondance est remplac�e par SubstValue, ou par DefaultValue dans le cas contraire, ou par la cha�ne vide si aucune DefaultValue n'a �t� sp�cifi�e.

Par exemple, vous pouvez d�finir une directive RewriteMap comme suit :

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

Vous pourrez par la suite utiliser cette table de correspondances dans une directive RewriteRule comme suit :

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

Il est possible de sp�cifier une valeur par d�faut qui sera utilis�e si la recherche dans la table de correspondances est infructueuse :

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

Les sections suivantes d�crivent les diff�rents types de tables de correspondances type-map disponibles, et fournissent des exemples pour chacun d'entre eux.

txt: tables de correspondances au format texte

Lorsqu'un type-map txt est utilis�, la source-map est un chemin du syst�me de fichiers vers un fichier de correspondances au format texte, contenant sur chaque ligne une paire cl�/valeur s�par�es par un espace. Il est possible d'ins�rer des commentaires sous la forme de cha�nes commen�ant par le caract�re '#'.

Voici un exemple d'entr�es valides dans un fichier de correspondances :

# Ligne de commentaires
cl� valeur-substitution
cl� valeur-substitution # commentaire

Lorsque la table de correspondance fait l'objet d'une recherche, la valeur sp�cifi�e est recherch�e dans le premier champ, et si elle est trouv�e, la valeur de substitution est renvoy�e.

Par exemple, nous pourrions utiliser un fichier de correspondances pour traduire des noms de produits en identifiants produits pour obtenir des URLs plus simples � m�moriser, en utilisant la recette suivante :

Product to ID configuration

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

Nous supposons ici que le script prods.php sait quoi faire lorsqu'il re�oit un argument id=NON-TROUVE, dans le cas o� le produit ne se trouve pas dans la table de correspondances.

Le fichier /etc/apache2/map-produit.txt contient ce qui suit :

Ainsi, lorsqu'une requ�te pour http://example.com/produit/TELEVISION arrive, elle est transform�e en interne en /prods.php?id=993.

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

rnd: Fichier texte � valeurs de substitution multiples choisies de mani�re al�atoire

Lorsque le type-map sp�cifi� est rnd, la source est un chemin du syst�me de fichiers vers un fichier de correspondances au format texte dont chaque ligne contient une cl�, et une ou plusieurs valeurs s�par�es par le caract�re |. Si une cl� convient, une des valeurs correspondantes sera choisie de mani�re al�atoire.

Par exemple, vous pouvez utiliser le fichier de correspondances et les directives suivants pour impl�menter une r�partition de charge al�atoire entre plusieurs serveurs d'arri�re-plan, par l'interm�diaire d'un mandataire inverse. Les images sont envoy�es vers un des serveurs de l'ensemble 'statique', tandis que tout le reste est envoy� vers un des serveurs de l'ensemble 'dynamique'.

Directives de configuration

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]
    

Ainsi, lorsqu'une image est demand�e et que la premi�re r�gle convient, RewriteMap recherche la cha�ne statique dans le fichier de correspondances qui renvoie un des noms de serveurs sp�cifi�s de mani�re al�atoire, ce dernier �tant utilis� dans la cible de la r�gle RewriteRule.

Si vous voulez qu'un des serveurs soit plus souvent sollicit� que les autres (par exemple s'il poss�de plus de m�moire, et peut donc traiter d'avantage de requ�tes), sp�cifiez-le plusieurs fois dans la liste des serveurs.

dbm: Fichier condens� DBM

Lorsque le type-map dbm est utilis�, la source est un chemin du syst�me de fichiers vers un fichier de donn�es DBM contenant des paires cl�/valeur permettant d'effectuer la correspondance. Le fonctionnement est identique � celui du type-map txt, mais beaucoup plus rapide car un fichier DBM est index�, alors qu'un fichier texte ne l'est pas. L'acc�s � la cl� recherch�e est donc plus rapide.

Vous pouvez �ventuellement sp�cifier un type dbm particulier :

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

Ce type peut �tre choisi parmi sdbm, gdbm, ndbm ou db. Il est cependant recommand� d'utiliser l'utilitaire httxt2dbm fourni avec le serveur HTTP Apache, car il utilise la biblioth�que DBM appropri�e, � savoir celle qui a �t� utilis�e lors de la compilation de httpd.

Pour cr�er un fichier dbm, cr�ez tout d'abord un fichier de correspondances au format texte comme d�crit dans la section txt. Traitez ensuite ce fichier avec httxt2dbm :

Vous pouvez alors faire r�f�rence au fichier obtenu dans votre directive RewriteMap :

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

int: Fonction interne

Lorsque le type-map int est sp�cifi�, la source est une des fonctions RewriteMap internes disponibles. Les d�veloppeurs de modules peuvent fournir des fonctions internes suppl�mentaires en les enregistrant via l'API ap_register_rewrite_mapfunc. Les fonctions fournies par d�faut sont :

• toupper:
  Met tous les caract�res de la cl� en majuscules.
• tolower:
  Met tous les caract�res de la cl� en minuscules.
• escape:
  Prot�ge les caract�res sp�ciaux de la cl� en les transformant en leur code hexad�cimal.
• unescape:
  Retraduit les codes hexad�cimaux de la cl� en caract�res sp�ciaux.

Pour utiliser une de ces fonctions, cr�ez une RewriteMap faisant r�f�rence � cette fonction int, et utilisez-la dans votre r�gle RewriteRule :

Redirige un URI vers son �quivalent en minuscules

RewriteMap lc int:tolower
RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
    

prg: Programme de r��criture externe

Lorque le type-map prg est sp�cifi�, la source est un chemin du syst�me de fichiers vers un programme ex�cutable destin� � effectuer la mise en correspondance. Il peut s'agir d'un fichier binaire compil�, ou d'un programme en langage interpr�t� comme Perl ou Python.

Ce programme est lanc� une fois au d�marrage du serveur HTTP Apache, puis communique avec le moteur de r��criture via STDIN et STDOUT. En d'autres termes, pour chaque recherche de correspondance, il re�oit un argument via STDIN, et doit renvoyer en guise de r�ponse une cha�ne termin�e par un caract�re nouvelle-ligne sur STDOUT. Si la recherche de correspondance est infructueuse, le programme doit l'indiquer en retournant la cha�ne de quatre caract�res "NULL".

Les programmes de r��criture externes ne sont pas lanc�s s'il n'ont pas �t� d�finis dans un contexte o� la directive RewriteEngine est d�finie � on.

Cette fonctionnalit� utilise le mutex rewrite-map n�cessaire � la fiabilit� des communications avec le programme. Le m�canisme de mutex et le fichier verrou peuvent �tre d�finis via la directive Mutex.

Voici un exemple simple qui remplace tous les tirets par des caract�res de soulignement dans l'URI de la requ�te.

Configuration de la r��criture

RewriteMap d2u prg:/www/bin/dash2under.pl

RewriteRule - ${d2u:%{REQUEST_URI}}
    

dash2under.pl

    #!/usr/bin/perl
    $| = 1; # Turn off I/O buffering
    while (<STDIN>) {
        s/-/_/g; # Remplace tous les tirets par des caract�res de soulignement
        print $_;
    }
    

dbd ou fastdbd: requ�te SQL

Lorsque le type-map dbd ou fastdbd est sp�cifi�, la source est une requ�te SQL SELECT qui re�oit un argument et renvoie une seule valeur.

Pour que cette requ�te puisse �tre ex�cut�e, mod_dbd doit �tre configur� pour attaquer la base de donn�es concern�e.

Ce type-map existe sous deux formes. Avec le type-map dbd, la requ�te est ex�cut�e � chaque demande, tandis qu'avec le type-map fastdbd, les recherches dans la base de donn�es sont mises en cache en interne. fastdbd est donc plus efficace et donc plus rapide ; par contre, il ne tiendra pas compte des modifications apport�es � la base de donn�es jusqu'� ce que le serveur soit red�marr�.

Si une requ�te renvoie plusieurs enregistrements, un de ceux-ci sera s�lectionn� al�atoirement.

RewriteMap ma-requete "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
    

R�sum�

La directive RewriteMap peut appara�tre plusieurs fois. Utilisez une directive RewriteMap pour chaque fonction de mise en correspondance pour d�clarer son fichier de correspondances.

Bien que l'on ne puisse pas d�clarer de fonction de mise en correspondance dans un contexte de r�pertoire (fichier .htaccess ou section <Directory>), il est possible d'utiliser cette fonction dans un tel contexte.