[译]nginx map(ngx_http_map_module)

ngx_http_map_module用于创建一个变量，该变量的值依赖于其他变量的值。(The ngx_http_map_module module creates variables whose values depend on values of other variables.)

• 配置样例

map $http_host $name {
    hostnames;

    default       0;

    example.com   1;
    *.example.com 1;
    example.org   2;
    *.example.org 2;
    .example.net  3;
    wap.*         4;
}

map $http_user_agent $mobile {
    default       0;
    "~Opera Mini" 1;
}

• 指令

Syntax: map string $variable { ... }
Default:    -
Context:    http

创建一新的变量。该变量的值，根据第一个参数中的一个或者多个来源变量的值来决定。(Creates a new variable whose value depends on values of one or more of the source variables specified in the first parameter.)

1. 在0.9.0之前，第一个参数只能被指定为字符型变量。(Before version 0.9.0 only a single variable could be specified in the first parameter.)
2. 因为变量是在被使用时才赋值，所以，仅仅声明变量，不会增加额外的请求处理的成本，即使是大量的声明。(Since variables are evaluated only when they are used, the mere declaration even of a large number of “map” variables does not add any extra costs to request processing.)

map block中的参数，指定了一种来源变量和目标变量之间的映射关系(Parameters inside the map block specify a mapping between source and resulting values.)
来源变量可以由字符串或者正则表达式(0.9.6)来表示(Source values are specified as strings or regular expressions (0.9.6).)

正则表达式可以由_{开始，表示对于区分大小写，也可以由}开始表示不区分大小写(1.0.4)。正则表达式可以包括名字捕获和位置捕获，它们可以在随后的关于目标变量的指令中用到。但是，不能在map的block中使用，否则会出现nginx: [emerg] unknown variable。(A regular expression should either start from the “~” symbol for a case-sensitive matching, or from the “~” symbols (1.0.4) for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable.)

如果一个来源变量名匹配XXX，应该加\前缀。(If a source value matches one of the names of special parameters described below, it should be prefixed with the “\” symbol.)

目标变量可以是字符串或者其他变量(0.9.0)。(The resulting value can be a string or another variable (0.9.0).)

指令还支持3中特殊参数：(The directive also supports three special parameters:)

默认(default value)

如果来源变量一个指令都没有匹配到，则设置目标变量为默认值。如果没有指定默认值，则目标变量会被赋值为一个空字符串。(sets the resulting value if the source value matches none of the specified variants. When default is not specified, the default resulting value will be an empty string.)

主机名(hostnames)

说明来源变量可以是带前缀或者后缀的主机名。(indicates that source values can be hostnames with a prefix or suffix mask:)

*.example.com 1;
example.*     1;

以下的两条记录(The following two records)

example.com   1;
*.example.com 1;

可以合并成一条： (can be combined:)

.example.com  1;

包含(include file)

包括一个包含映射关系的文件。可以有多个inclusion。(includes a file with values. There can be several inclusions.)

如果匹配多个，比如同时匹配mask和正则表达式，那么会选择mask作为匹配结果。(If the source value matches more than one of the specified variants, e.g. both a mask and a regular expression match, the first matching variant will be chosen, in the following order of priority:)

1. 没有掩码的字符串变量(string value without a mask)
2. 最长前缀匹配(longest string value with a prefix mask, e.g. “*.example.com”)
3. 最长前缀匹配(longest string value with a suffix mask, e.g. “mail.*”)
4. 第一个匹配的正则表达式(first matching regular expression (in order of appearance in a configuration file))
5. 默认变量(default value)