1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1739051 -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : VIncent Deffontaines -->
8 Licensed to the Apache Software Foundation (ASF) under one or more
9 contributor license agreements. See the NOTICE file distributed with
10 this work for additional information regarding copyright ownership.
11 The ASF licenses this file to You under the Apache License, Version 2.0
12 (the "License"); you may not use this file except in compliance with
13 the License. You may obtain a copy of the License at
15 http://www.apache.org/licenses/LICENSE-2.0
17 Unless required by applicable law or agreed to in writing, software
18 distributed under the License is distributed on an "AS IS" BASIS,
19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20 See the License for the specific language governing permissions and
21 limitations under the License.
23 <manualpage metafile="rewritemap.xml.meta">
24 <parentdocument href="./">Rewrite</parentdocument>
25 <title>Utilisation de RewriteMap</title>
28 <p>Ce document est un complément à la <a
29 href="../mod/mod_rewrite.html">documentation de référence</a> du
30 module <module>mod_rewrite</module>. Il décrit l'utilisation de la
31 directive <directive module="mod_rewrite">RewriteMap</directive>, et
32 fournit des exemples pour chacun des différents types de
33 <directive module="mod_rewrite">RewriteMap</directive>.</p>
35 <note type="warning">Notez que la plupart de ces exemples ne
36 fonctionneront pas en l'état dans le contexte de votre configuration
37 particulière ; vous devez donc vous attacher à les
38 comprendre, plutôt que de simplement les insérer dans votre
39 configuration par copier/coller.</note>
42 <seealso><a href="../mod/mod_rewrite.html">Documentation du module
43 mod_rewrite</a></seealso>
44 <seealso><a href="intro.html">Introduction à mod_rewrite</a></seealso>
45 <seealso><a href="remapping.html">Redirection et remise en
46 correspondance</a></seealso>
47 <seealso><a href="access.html">Contrôle d'accès</a></seealso>
48 <seealso><a href="vhosts.html">Serveurs virtuels</a></seealso>
49 <seealso><a href="proxy.html">Mise en cache</a></seealso>
50 <seealso><a href="advanced.html">Techniques avancées</a></seealso>
51 <seealso><a href="avoid.html">Quand ne pas utiliser mod_rewrite</a></seealso>
53 <section id="introduction">
54 <title>Introduction</title>
57 La directive <directive module="mod_rewrite">RewriteMap</directive>
58 définit une fonction externe qui peut être appelée depuis une
59 directive <directive module="mod_rewrite">RewriteRule</directive> ou
60 <directive module="mod_rewrite">RewriteCond</directive> pour
61 accomplir une réécriture trop compliquée, ou trop spécialisée pour
62 être effectuée à partir d'expressions rationnelles. Vous trouverez
63 ci-dessous les différents types disponibles pour la source de
64 données, ceux-ci étant par ailleurs énumérés dans la documentation de
65 référence de <directive module="mod_rewrite">RewriteMap</directive>.</p>
67 <p>La syntaxe de la directive <directive module="mod_rewrite">RewriteMap</directive> est la suivante
70 <highlight language="config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em></highlight>
72 <p>L'argument <a id="mapfunc" name="mapfunc"><em>MapName</em></a>
73 est un nom arbitraire que vous associez à la table de
74 correspondances, et que vous
75 pourrez utilisez par la suite dans les directives de réécriture. Les
76 recherches dans la table de correspondance s'effectuent en
77 respectant cette syntaxe :</p>
81 <code>${</code> <em>nom-map</em> <code>:</code>
82 <em>clé-recherche</em>
83 <code>}</code> <br/> <code>${</code> <em>nom-map</em> <code>:</code>
84 <em>clé-recherche</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
88 <p>Lorsque cette syntaxe est employée, la table de correspondances
89 <em>nom-map</em> est consultée et la clé <em>clé-recherche</em>
90 recherchée. Si la clé est trouvée, la fonction de recherche dans la
91 table de correspondance est remplacée par <em>SubstValue</em>, ou
92 par <em>DefaultValue</em> dans le cas contraire, ou par la chaîne
93 vide si aucune <em>DefaultValue</em> n'a été spécifiée.</p>
95 <p>Par exemple, vous pouvez définir une directive
96 <directive module="mod_rewrite">RewriteMap</directive> comme suit :</p>
97 <highlight language="config">RewriteMap examplemap "txt:/path/to/file/map.txt"</highlight>
98 <p>Vous pourrez par la suite utiliser cette table de correspondances
99 dans une directive <directive module="mod_rewrite">RewriteRule</directive> comme suit :</p>
100 <highlight language="config">RewriteRule "^/ex/(.*)" "${examplemap:$1}"</highlight>
102 <p>Il est possible de spécifier une valeur par défaut qui sera utilisée
103 si la recherche dans la table de correspondances est infructueuse :</p>
105 <highlight language="config">RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"</highlight>
107 <note><title>Contexte de répertoire et fichiers.htaccess</title>
109 Vous ne pouvez utiliser la directive <directive module="mod_rewrite">RewriteMap</directive> ni dans
110 les sections <directive module="core" type="section">Directory</directive>, ni dans les fichiers
111 <code>.htaccess</code>. Vous devez déclarer la table de correspondances
112 au niveau du serveur principal ou dans un contexte de serveur virtuel.
113 En revanche, si vous ne pouvez pas déclarer la table dans une section
114 <Directory> ou dans un fichier <code>.htaccess</code>, vous
115 pourrez y faire référence dans ces contextes, une fois cette table
120 <p>Les sections suivantes décrivent les différents types de tables de
121 correspondances <em>type-map</em> disponibles, et fournissent des
122 exemples pour chacun d'entre eux.</p>
126 <title>int: Fonction interne</title>
128 <p>Lorsque le type-map <code>int</code> est spécifié, la source est
129 une des fonctions RewriteMap internes disponibles. Les développeurs
130 de modules peuvent fournir des fonctions internes supplémentaires en
131 les enregistrant via l'API <code>ap_register_rewrite_mapfunc</code>.
132 Les fonctions fournies par défaut sont :
136 <li><strong>toupper</strong>:<br/>
137 Met tous les caractères de la clé en majuscules.</li>
138 <li><strong>tolower</strong>:<br/>
139 Met tous les caractères de la clé en minuscules.</li>
140 <li><strong>escape</strong>:<br/>
141 Protège les caractères spéciaux de la clé en les
142 transformant en leur code hexadécimal.</li>
143 <li><strong>unescape</strong>:<br/>
144 Retraduit les codes hexadécimaux de la clé en caractères
149 Pour utiliser une de ces fonctions, créez une
150 <code>RewriteMap</code> faisant référence à cette fonction int, et
151 utilisez-la dans votre règle <code>RewriteRule</code> :
154 <p> <strong>Redirige un URI vers son équivalent en minuscules</strong></p>
155 <highlight language="config">
157 RewriteMap lc int:tolower
158 RewriteRule "(.*)" "${lc:$1}" [R]
162 <p>Notez que cet exemple n'est fourni qu'à titre d'illustration,
163 et ne constitue en aucun cas une recommandation. Si vous voulez
164 rendre des URLs insensibles à la casse, vous devez plutôt vous
165 tourner vers <module>mod_speling</module>.
172 <title>txt: tables de correspondances au format texte</title>
174 <p>Lorsqu'un type-map <code>txt</code> est utilisé, la source-map
175 est un chemin du système de fichiers vers un fichier de
176 correspondances au format texte, contenant sur chaque ligne une
177 paire clé/valeur séparées par un espace. Il est possible d'insérer
178 des commentaires sous la forme de chaînes commençant par le caractère
181 <p>Voici un exemple d'entrées valides dans un fichier de
182 correspondances :</p>
185 # Ligne de commentaires<br />
186 <strong><em>clé</em> <em>valeur-substitution</em></strong><br />
187 <strong><em>clé</em> <em>valeur-substitution</em></strong> # commentaire<br />
190 <p>Lorsque la table de correspondance fait l'objet d'une recherche,
191 la valeur spécifiée est recherchée dans le premier champ, et si elle
192 est trouvée, la valeur de substitution est renvoyée.</p>
194 <p>Par exemple, nous pourrions utiliser un fichier de
195 correspondances pour traduire des noms de produits en identifiants
196 produits pour obtenir des URLs plus simples à mémoriser, en
197 utilisant la recette suivante :</p>
199 <p><strong>Product to ID configuration</strong></p>
200 <highlight language="config">
201 RewriteMap product2id "txt:/etc/apache2/productmap.txt"
202 RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
205 <p>Nous supposons ici que le script <code>prods.php</code> sait quoi
206 faire lorsqu'il reçoit un argument <code>id=NOTFOUND</code>, dans
207 le cas où le produit ne se trouve pas dans la table de
210 <p>Le fichier <code>/etc/apache2/map-produit.txt</code> contient ce
213 <example><title>Fichier de correspondances Produit - Identifiant</title>
215 ## map-produit.txt - Fichier de correspondances Produit - Identifiant<br />
220 CANNE-A-PECHE 043<br />
221 BALLON-BASKET 418<br />
225 <p>Ainsi, lorsqu'une requête pour
226 <code>http://example.com/produit/TELEVISION</code> arrive, la directive
227 <directive module="mod_rewrite">RewriteRule</directive> s'applique, et la
228 requête est transformée en interne en <code>/prods.php?id=993</code>.</p>
230 <note><title>Note: fichiers .htaccess</title>
231 L'exemple donné est conçu pour être utilisé dans un contexte de
232 serveur principal ou de serveur virtuel. Si vous voulez l'utiliser
233 dans un fichier <code>.htaccess</code>, vous devrez supprimer le
234 slash de début dans le modèle de réécriture afin que ce dernier
235 puisse correspondre à toute URL :
236 <highlight language="config">RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]</highlight>
239 <note><title>Recherches mises en cache</title>
241 Les clés de recherche sont mises en cache par httpd jusqu'à ce que
242 le <code>mtime</code> (date de modification) du fichier de
243 correspondances soit modifié, ou que le serveur httpd soit
244 redémarré, ce qui améliore les performances pour les tables de
245 correspondances consultées par de nombreuses requêtes.
251 <title>rnd: Fichier texte à valeurs de substitution multiples
252 choisies de manière aléatoire</title>
254 <p>Lorsque le type-map spécifié est <code>rnd</code>, la source est
255 un chemin du système de fichiers vers un fichier de correspondances
256 au format texte dont chaque ligne contient une clé, et une ou
257 plusieurs valeurs séparées par le caractère <code>|</code>. Si une
258 clé convient, une des valeurs correspondantes sera choisie de
259 manière aléatoire.</p>
261 <p>Par exemple, vous pouvez utiliser le fichier de correspondances
262 et les directives suivants pour implémenter une répartition de
263 charge aléatoire entre plusieurs serveurs d'arrière-plan, par
264 l'intermédiaire d'un mandataire inverse. Les images sont envoyées
265 vers un des serveurs de l'ensemble 'statique', tandis que tout le
266 reste est envoyé vers un des serveurs de l'ensemble 'dynamique'.</p>
268 <example><title>Fichier de correspondances</title>
270 ## map.txt -- table de réécriture<br />
273 statique www1|www2|www3|www4<br />
276 <p><strong>Directives de configuration</strong></p>
277 <highlight language="config">
278 RewriteMap servers "rnd:/path/to/file/map.txt"
280 RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
281 RewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]
285 <p>Ainsi, lorsqu'une image est demandée et que la première règle
286 convient, <directive module="mod_rewrite">RewriteMap</directive> recherche la chaîne
287 <code>statique</code> dans le fichier de correspondances qui
288 renvoie un des noms de serveurs spécifiés de manière aléatoire,
289 ce dernier étant utilisé dans la cible de la règle
290 <directive module="mod_rewrite">RewriteRule</directive>.</p>
292 <p>Si vous voulez qu'un des serveurs soit plus souvent sollicité que
293 les autres (par exemple s'il possède plus de mémoire, et peut donc
294 traiter d'avantage de requêtes), spécifiez-le plusieurs fois dans la
295 liste des serveurs.</p>
298 statique www1|www1|www2|www3|www4
304 <title>dbm: Fichier condensé DBM</title>
306 <p>Lorsque le type-map <code>dbm</code> est utilisé, la source est
307 un chemin du système de fichiers vers un fichier de données DBM
308 contenant des paires clé/valeur permettant d'effectuer la
309 correspondance. Le fonctionnement est identique à celui du type-map
310 <code>txt</code>, mais beaucoup plus rapide car un fichier DBM est
311 indexé, alors qu'un fichier texte ne l'est pas. L'accès à la clé
312 recherchée est donc plus rapide.</p>
314 <p>Vous pouvez éventuellement spécifier un type dbm particulier :</p>
316 <highlight language="config">
317 RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"
320 <p>Ce type peut être choisi parmi <code>sdbm</code>, <code>gdbm</code>,
321 <code>ndbm</code> ou <code>db</code>. Il est
322 cependant recommandé d'utiliser l'utilitaire <a
323 href="../programs/httxt2dbm.html">httxt2dbm</a> fourni avec le
324 serveur HTTP Apache, car il utilise la bibliothèque DBM appropriée,
325 à savoir celle qui a été utilisée lors de la compilation de httpd.</p>
327 <p>Pour créer un fichier dbm, créez tout d'abord un fichier de
328 correspondances au format texte comme décrit dans la section <a
329 href="#txt">txt</a>. Traitez ensuite ce fichier avec
330 <code>httxt2dbm</code> :</p>
333 $ httxt2dbm -i fichier-map.txt -o fichier-map.map
336 <p>Vous pouvez alors faire référence au fichier obtenu dans votre
337 directive <directive module="mod_rewrite">RewriteMap</directive> :</p>
338 <highlight language="config">
339 RewriteMap mapname "dbm:/etc/apache/mapfile.map"
343 <p>Notez qu'avec certains types dbm, plusieurs fichiers possédant le
344 même nom de base sont créés. Par exemple, vous pouvez obtenir deux
345 fichiers nommés <code>fichier-map.map.dir</code> et
346 <code>fichier-map.map.pag</code>. Ceci est tout à fait normal, et vous
347 ne devez utiliser que le nom de base <code>fichier-map.map</code> dans votre
348 directive <directive module="mod_rewrite">RewriteMap</directive>.</p>
351 <note><title>Mise en cache des recherches</title>
353 Les clés de recherche sont mises en cache par httpd jusqu'à ce que
354 le <code>mtime</code> (date de modification) du fichier de
355 correspondances soit modifié, ou que le serveur httpd soit
356 redémarré, ce qui améliore les performances pour les tables de
357 correspondances consultées par de nombreuses requêtes.
363 <section id="prg"><title>prg: Programme de réécriture externe</title>
365 <p>Lorque le type-map <code>prg</code> est spécifié, la source est
366 un chemin du système de fichiers vers un programme exécutable
367 destiné à effectuer la mise en correspondance. Il peut s'agir d'un
368 fichier binaire compilé, ou d'un programme en langage interprété
369 comme Perl ou Python.</p>
371 <p>Ce programme est lancé une fois au démarrage du serveur HTTP
372 Apache, puis communique avec le moteur de réécriture via
373 <code>STDIN</code> et <code>STDOUT</code>. En d'autres termes, pour
374 chaque recherche de correspondance, il reçoit un argument via
375 <code>STDIN</code>, et doit renvoyer en guise de réponse une chaîne
376 terminée par un caractère nouvelle-ligne sur <code>STDOUT</code>. Si
377 la recherche de correspondance est infructueuse, le programme doit
378 l'indiquer en retournant la chaîne de quatre caractères
379 "<code>NULL</code>".</p>
381 <p>Les programmes de réécriture externes ne sont pas lancés s'il
382 n'ont pas été définis dans un contexte où la directive <directive
383 module="mod_rewrite">RewriteEngine</directive> est définie à
386 <p>Cette fonctionnalité utilise le mutex <code>rewrite-map</code>
387 nécessaire à la fiabilité des communications avec le programme. Le
388 mécanisme de mutex et le fichier verrou peuvent être définis via la
389 directive <directive module="core">Mutex</directive>.</p>
391 <p>Voici un exemple simple qui remplace tous les tirets par des
392 caractères de soulignement dans l'URI de la requête.</p>
394 <p><strong>Configuration de la réécriture</strong></p>
395 <highlight language="config">
397 RewriteMap d2u "prg:/www/bin/dash2under.pl"<br />
398 RewriteRule "-" "${d2u:%{REQUEST_URI}}"
401 <p><strong>dash2under.pl</strong></p>
402 <highlight language="perl">
404 $| = 1; # Turn off I/O buffering
405 while (<STDIN>) {
406 s/-/_/g; # Remplace tous les tirets par des caractères de soulignement
411 <note><title>Mises en garde !</title>
413 <li>Votre programme doit être le plus
414 simple possible. Si le programme se bloque, httpd va attendre
415 indéfiniment une réponse de sa part, et par conséquent ne répondra plus
417 <li>Assurez-vous de bien désactiver la mise en tampon dans votre
418 programme. En Perl, ceci est effectué à la seconde ligne du script de
419 l'exemple - <code>$| = 1;</code> - La syntaxe sera bien entendu
421 d'autres langages. Si les entrées/sorties sont mises en tampon, httpd va
422 attendre une sortie, et va par conséquent se bloquer.</li>
423 <li>Rappelez-vous qu'il n'existe qu'une copie du programme lancé au
424 démarrage du serveur, et que toutes les requêtes vont devoir passer par
425 ce goulot d'étranglement. Ceci peut provoquer des ralentissements
426 significatifs si de nombreuses requêtes doivent être traitées, ou si le
427 script lui-même est très lent.</li>
435 <title>dbd ou fastdbd: requête SQL</title>
437 <p>Lorsque le type-map <code>dbd</code> ou <code>fastdbd</code> est
438 spécifié, la source est une requête SQL SELECT qui reçoit un
439 argument et renvoie une seule valeur.</p>
441 <p>Pour que cette requête puisse être exécutée,
442 <module>mod_dbd</module> doit être configuré pour attaquer la base
443 de données concernée.</p>
445 <p>Ce type-map existe sous deux formes. Avec le type-map
446 <code>dbd</code>, la requête est exécutée à chaque demande, tandis
447 qu'avec le type-map <code>fastdbd</code>, les recherches dans la
448 base de données sont mises en cache en interne. <code>fastdbd</code>
449 est donc plus efficace et donc plus rapide ; par contre, il ne
450 tiendra pas compte des modifications apportées à la base de données
451 jusqu'à ce que le serveur soit redémarré.</p>
453 <p>Si une requête renvoie plusieurs enregistrements, un de ceux-ci
454 sera sélectionné aléatoirement.</p>
456 <example><title>Exemple</title>
457 <highlight language="config">
458 RewriteMap ma-requete "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
463 <section id="summary">
464 <title>Résumé</title>
466 <p>La directive <directive module="mod_rewrite">RewriteMap</directive> peut apparaître
467 plusieurs fois. Utilisez une directive
468 <directive module="mod_rewrite">RewriteMap</directive> pour chaque fonction de mise en
469 correspondance pour déclarer son fichier de correspondances.</p>
471 <p>Bien que l'on ne puisse pas <strong>déclarer</strong> de fonction
472 de mise en correspondance dans un contexte de répertoire (fichier
473 <code>.htaccess</code> ou section <directive module="core"
474 type="section">Directory</directive>), il est
475 possible d'utiliser cette fonction dans un tel contexte.</p>