Pular para conteúdo

array-var: Variáveis do tipo array para NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-array-var

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-array-var

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_array_var_module.so;

Este documento descreve o nginx-module-array-var v0.6 lançado em 23 de maio de 2022.

location /foo {
    array_split ',' $arg_files to=$array;

    # use a diretiva set_quote_sql_str no módulo ngx_set_misc
    # para mapear para cada elemento no array $array:
    array_map_op set_quote_sql_str $array;

    array_map "name = $array_it" $array;

    array_join ' or ' $array to=$sql_condition;

    # bem, poderíamos alimentá-lo ao ngx_drizzle para conversar com o MySQL, por exemplo ;)
    echo "select * from files where $sql_condition";
}

Descrição

Este módulo fornece variáveis do tipo array para nginx.conf.

Nos bastidores, este módulo apenas "abusa" dos valores de string do nginx para manter ponteiros binários para estruturas de dados C (a estrutura ngx_array_t do núcleo do NGINX).

O tipo array dá ao nginx.conf capacidades maravilhosas de manipulação de listas de valores. Hoje em dia, no entanto, é altamente recomendado usar o módulo ngx_lua para ter todo o poder de script fornecido pela linguagem Lua no nginx.

Diretivas

array_split

sintaxe: array_split <separador> <assunto> to=$variavel_alvo

padrão: não

contexto: http, server, server if, location, location if

Divide o valor da string no argumento assunto com a string separadora especificada pelo argumento separador. O resultado é um valor do tipo array salvo na variável nginx especificada pela opção to=VAR.

Por exemplo,

array_split "," $arg_names to=$names;

dividirá os valores de string no argumento de consulta URI names em um valor do tipo array salvo na variável nginx personalizada $names.

Esta diretiva cria uma variável do tipo array. Variáveis do tipo array não podem ser usadas fora das diretivas oferecidas por este módulo. Se você quiser usar os valores em uma variável do tipo array em outros contextos, deve usar a diretiva array_join para produzir um valor de string normal.

array_join

sintaxe: array_join <separador> $array_var

padrão: não

contexto: http, server, server if, location, location if

Une os elementos na variável nginx do tipo array ($array_var) em um único valor de string com o separador especificado pelo primeiro argumento.

Por exemplo,

location /foo {
    array_split ',' $arg_names to=$names;
    array_join '+' $names;
    echo $names;
}

Então, a requisição GET /foo?names=Bob,Marry,John resultará no corpo da resposta

Bob+Marry+John

No exemplo acima, usamos a diretiva echo do módulo ngx_echo para exibir o resultado final.

array_map

sintaxe: array_map <template> $array_var

sintaxe: array_map <template> $array_var to=$new_array_var

padrão: não

contexto: http, server, server if, location, location if

Mapeia o template de string para cada elemento na variável nginx do tipo array especificada. Dentro do template de string, você pode usar a variável iteradora especial $array_it para referenciar o elemento atual do array que está sendo mapeado.

Por exemplo,

array_map "[$array_it]" $names;

mudará cada elemento na variável array $names colocando colchetes ao redor do valor da string de cada elemento. A modificação é feita no local neste caso.

Se você não quiser modificações no local, pode usar a opção to=$var para especificar uma nova variável nginx para armazenar os resultados. Por exemplo,

array_map "[$array_it]" $names to=$new_names;

onde os resultados são salvos em outra variável nginx (do tipo array) chamada $new_names, enquanto a variável $names permanece intacta.

Abaixo está um exemplo completo para isso:

location /foo {
    array_split ',' $arg_names to=$names;
    array_map '[$array_it]' $names;
    array_join '+' $names;
    echo "$names";
}

Então, a requisição GET /foo?names=bob,marry,nomas resultará no corpo da resposta

[bob]+[marry]+[nomas]

array_map_op

sintaxe: array_map_op <diretiva> $array_var

sintaxe: array_map_op <diretiva> $array_var to=$new_array_var

padrão: não

contexto: http, server, server if, location, location if

Semelhante à diretiva array_map, mas mapeia a diretiva de configuração nginx especificada em vez de um template de string para cada elemento na variável nginx do tipo array especificada. O resultado da aplicação da diretiva de configuração especificada torna-se o resultado do mapeamento.

A diretiva de configuração nginx que está sendo usada como iteradora deve ser implementada pelo submódulo set_var do Nginx Devel Kit (NDK) ndk_set_var_value. Por exemplo, as seguintes diretivas do set-misc-nginx-module podem ser invocadas dessa forma:

Esta é uma operação de ordem superior onde outras diretivas de configuração nginx podem ser usadas como argumentos para esta diretiva map_array_op.

Considere o seguinte exemplo,

array_map_op set_quote_sql_str $names;

Esta linha muda cada elemento na variável nginx do tipo array $names aplicando a diretiva set_quote_sql_str fornecida pelo módulo ngx_set_misc uma a uma. O resultado é que cada elemento no array $names foi escapado como valores literais de string SQL.

Você também pode especificar a opção to=$var se não quiser modificações no local dos arrays de entrada. Por exemplo,

array_map_op set_quote_sql_str $names to=$quoted_names;

salvará os elementos escapados em uma nova variável nginx (do tipo array) chamada $quoted_names, mantendo $names intacta.

O seguinte é um exemplo relativamente completo:

location /foo {
    array_split ',' $arg_names to=$names;
    array_map_op set_quote_sql_str $names;
    array_join '+' $names to=$res;
    echo $res;
}

Então, a requisição GET /foo?names=bob,marry,nomas resultará no corpo da resposta

'bob'+'marry'+'nomas'

Bem legal, não?

Aqui assumimos que você instalaria seu nginx em /opt/nginx/.

./configure --prefix=/opt/nginx \ --add-module=/path/to/ngx_devel_kit \ --add-module=/path/to/array-var-nginx-module

make -j2 make install ```

Baixe a versão mais recente do tarball de lançamento deste módulo da lista de arquivos do array-var-nginx-module, e o tarball mais recente do ngx_devel_kit da sua lista de arquivos.

Além disso, este módulo está incluído e ativado por padrão no pacote OpenResty.

Veja Também

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub para nginx-module-array-var.