Rules Engine para Edge Application
O Rules Engine é uma capacidade do Edge Application que controla a execução de comportamentos através de operadores lógicos. Através do Rules Engine, você pode construir uma arquitetura que proporciona melhor performance para seus usuários consumindo menos recursos e processando na origem.
1. Como funciona
Cada requisição de uma aplicação construída com o Azion Real-Time Manager (RTM) é processada numa sequência fixa de duas fases: primeiro a Request Phase, depois a Response Phase.
Em cada fase de processamento, você pode definir um conjunto de regras para tratar a requisição de acordo com as necessidades da sua aplicação ou negócio. Uma vez selecionada a fase em que a sua regra será executada, você pode criar uma nova regra.
As regras são concebidas para seguir uma lógica condicional se-então. Cada regra é composta de Criteria (se), que são os critérios que definirão o conjunto de condições que devem ser cumpridas para a execução de Behaviors (então), ou comportamentos.
Você pode utilizar variáveis, operadores de comparação e operadores lógicos para desencadear os comportamentos desejados para a sua aplicação. Se as condições forem cumpridas, os comportamentos de cada regra são executados até que todas as regras sejam processadas.
Aviso: alguns comportamentos podem terminar a execução das regras. Se uma sequência de regras incluir tal comportamento, quaisquer regras ou comportamentos que sejam adicionados após o finalizador não serão executados.
Antes de criar uma regra, você deve ativar o módulo Application Acceleration, que expande a usabilidade do Rules Engine, pois habilita funcionalidades de computação serverless à Edge Application. Caso o módulo não seja ativado, somente algumas variáveis e comportamentos estarão disponíveis para o Rules Engine.
Para criar regras para sua aplicação, siga estes passos:
- Accesse o RTM.
- No canto superior esquerdo, acesse Products menu > Edge Application.
- Clique na aplicação para a qual você deseja criar regras.
- Na aba Main Settings, ative o módulo Application Acceleration.
- Selecione a aba Rules Engine.
- Clique no botão Add Rule.
Ao criar uma regra, você será solicitado a selecionar uma das duas fases de processamento disponíveis: Request Phase ou Response Phase.
1.1. Request Phase
Na Request Phase, você pode controlar como a requisição de seu usuário é processada de acordo com suas regras de negócio e definir quais origens devem tratar da requisição caso o conteúdo não seja armazenado em cache.
Você pode usar qualquer variável relacionada aos dados enviados por seu usuário na requisição como variáveis para as regras da Request Phase. Como a resposta ainda não foi processada pela requisição, você não tem acesso às variáveis relacionadas ao conteúdo que será entregue a seu usuário nesta fase.
É nessa fase que você define como a Azion deve gerenciar o cache de sua aplicação. Se sua aplicação não permitir nenhum tipo de cache, as condições para ignorar o cache podem ser definidas.
1.2. Response Phase
Na Response Phase, sua aplicação trata do conteúdo que será entregue a seus usuários. Todo o processamento na Response Phase é dinâmico e é realizado individualmente para cada usuário.
2. Criteria
A seção Criteria do Rules Engine é onde você define os critérios para a execução da regra. Critérios são compostos de:
- variáveis
- operadores de comparação
- argumentos, quando aplicável
A inclusão de argumentos em um critério depende dos operadores de comparação escolhidos, e seus formatos estão descritos nas seções variáveis e operadores de comparação. Operadores lógicos servem para incrementar a quantidade de comparações que a regra irá executar.
Por exemplo, o seguinte critério identifica se um usuário está usando um navegador web desktop para acessar sua aplicação através de uma expressão regular como argumento:
| Variável | Operador de comparação | Argumento | |
|---|---|---|---|
| If | ${http_user_agent} |
matches | (Chrome|Mozilla) |
2.1. Variáveis
| Variável | Descrição | Fases em que pode ser utilizada |
|---|---|---|
${arg_name} |
Argumento name enviado pelo usuário na linha de requisição (query string). Por exemplo, para a requisição GET /path?Search=test, a variável ${arg_search} assumirá o valor test. |
Request Phase Response Phase |
${args} |
Todos os argumentos enviados pelo usuário na linha de requisição (query string). Por exemplo: para a requisição GET /path?Search=test, a variável assumirá o valor Search=test. |
Request Phase Response Phase |
${cookie_name} |
Valor do cookie name. Por exemplo, para o cookie_icl_current_language=pt-br, a variável ${cookie_icl_current_language} assumirá o valor pt-br. |
Request Phase Response Phase |
${device_group} |
Grupo do dispositivo do usuário. Os grupos de dispositivos são customizados pelo User Agent na aba Device Groups do Real-Time Manager. | Request Phase Response Phase |
${geoip_city_continent_code} |
Código de continente com 2 letras, utilizando a base de geolocalização geoip_city. Por exemplo: EU para Europa, NA para América do Norte. |
Request Phase Response Phase |
${geoip_city_country_code} |
Código de país com 2 letras, utilizando a base de geolocalização geoip_city. Por exemplo: RU para Rússia, BR para Brasil. |
Request Phase Response Phase |
${geoip_city} |
Nome da cidade por extenso, utilizando a base de geolocalização geoip_city. Por exemplo: Sao Paulo, London. |
Request Phase Response Phase |
${geoip_continent_code} |
Código de continente com 2 letras. Por exemplo: EU para Europa, NA para América do Norte. |
Request Phase Response Phase |
${geoip_city_country_name} |
Nome do país por extenso, utilizando a base de geolocalização geoip_city. Por exemplo: United States, Brazil. |
Request Phase Response Phase |
${geoip_country_code} |
Código de país com 2 letras, utilizando a base de geolocalização geoip_country. Por exemplo: RU para Rússia, BR para Brasil. |
Request Phase Response Phase |
${geoip_country_name} |
Nome do país por extenso, utilizando a base de geolocalização geoip_country. Por exemplo: United States, Brazil. |
Request Phase Response Phase |
${geoip_region_name} |
Nome do país por extenso, utilizando a base de geolocalização geoip_region. Por exemplo: Ontario, Sao Paulo etc. |
Request Phase Response Phase |
${geoip_region} |
Código da região com 2 letras. Por exemplo: RS para Rio Grande do Sul, ON para Toronto etc. |
Request Phase Response Phase |
${host} |
Em ordem de precedência: o host name da linha de requisição, ou o valor do campo de cabeçalho Host da requisição, ou o nome do servidor atendendo a requisição. | Request Phase Response Phase |
${http_name} |
O valor do campo de cabeçalho name da requisição. O argumento name deve ser convertido para letras minúsculas e os hífens devem ser convertidos para underscore. Por exemplo: ${http_accept} assumirá o valor da campo de cabeçalho Accept da requisição HTTP. |
Request Phase Response Phase |
${remote_addr} |
O endereço IP do cliente que está realizando a requisição HTTP. | Request Phase Response Phase |
${remote_user} |
O username fornecido pela autenticação básica, quando houver. | Request Phase Response Phase |
${request} |
A linha completa da requisição. | Request Phase Response Phase |
${request_body} |
Os argumentos de um POST, enviados no body da requisição. | Request Phase Response Phase |
${request_method} |
O método HTTP da requisição. Por exemplo: GET. |
Request Phase Response Phase |
${request_uri} |
A URI completa da requisição, com argumentos (query string). | Request Phase Response Phase |
${scheme} |
O scheme da requisição: http ou https. |
Request Phase Response Phase |
${sent_http_name} |
O valor do campo de cabeçalho de resposta name. O argumento name deve ser convertido para letras minúsculas e os hífens devem ser convertidos para underscore. Por exemplo: ${sent_http_content_length} assumirá o valor do cabeçalho Content-Length. |
Response Phase |
${status} |
O status code da resposta. | Response Phase |
${upstream_addr} |
O endereço IP e porta da origem consultada para obtenção da resposta. Caso múltiplas origens sejam consultadas durante o processamento da requisição, os endereços serão separados por vírgula. Por exemplo: 192.168.1.1:80, 192.168.1.2:80. Se um redirect interno de um grupo de servidores para outro ocorrer, iniciado por um X-Accel-Redirect ou por uma página de erro, os endereços dos diferentes grupos serão separados por “:”. Por exemplo: 192.168.1.1:80, 192.168.1.2:80 : 192.168.10.1:80, 192.168.10.2:80. |
Response Phase |
${upstream_cookie_name} |
Valor do cookie name enviado pela origem através do campo de cabeçalho Set-Cookie. Caso múltiplas origens sejam consultadas durante o processamento da requisição, apenas os cookies da última origem são armazenados. | Response Phase |
${upstream_http_name} |
Valor do campo de cabeçalho name enviado pela origem. O argumento name deve ser convertido para letras minúsculas e os hífens devem ser convertidos para underscore. Caso múltiplas origens sejam consultadas durante o processamento da requisição, apenas os cabeçalhos da última origem são armazenados. Por exemplo: ${upstream_http_server} assumirá o valor do campo de cabeçalho Server enviado pela última origem consultada. |
Response Phase |
${upstream_status} |
Status Code da resposta da origem enviada para o RTM. Caso múltiplas origens sejam consultadas durante o processamento da requisição, os status codes serão separados por vírgula. Se um redirect interno de um grupo de servidores para outro ocorrer, iniciado por um “X-Accel-Redirect” ou por uma página de erro, os status codes dos diferentes grupos serão separados por “:”. | Response Phase |
${uri} |
A URI normalizada (urldecoded) da requisição. O valor da ${uri} pode mudar durante o processamento de uma requisição, por exemplo, quando ocorre um redirect interno ou quando são utilizados arquivos index. NÃO carrega os parâmetros do Query String como ${request_uri} faz. |
Request Phase Response Phase |
2.2. Operadores de Comparação
| Operador | Descrição | Tipo de argumento |
|---|---|---|
| is equal | O valor da variável é igual ao argumento, comparado caracter a caracter. | string |
| is not equal | O valor da variável não é exatamente igual ao argumento. | string |
| starts with | O valor da variável inicia pelo argumento. | string |
| does not start with | O valor da variável não inicia pelo argumento. | string |
| matches | O valor da variável coincide com a expressão regular informada como argumento. | regular expression |
| does not match | O valor da variável não coincide com a expressão regular informada como argumento. | regular expression |
| exists | A variável tem valor definido. Por exemplo ${arg_search} existe se foi enviado um argumento search na query string da requisição. |
- |
| does not exist | A variável não tem valor definido. Por exemplo ${arg_search} não existe se não foi enviado um argumento search na query string da requisição. |
- |
2.3. Operadores Lógicos
Múltiplos critérios podem ser adicionados por meio dos operadores lógicos AND e OR. Com isso, cada regra pode conter até 10 critérios.
O operador AND tem precedência implícita sobre o operador OR. Se for necessária precedência explícita, você pode adicionar múltiplos grupos de critérios apenas sob a lógica AND.
3. Behaviors
Na seção de Behaviors da Rules Engine, você adiciona os comportamentos que deseja executar, caso as condições da regra sejam atendidas.
Por exemplo, esse comportamento redireciona o usuário para uma versão em inglês de um path de FAQ:
| Comportamento | Argumento |
|---|---|
| Redirect To (302 Found) | /en-us/faq |
Cada regra pode carregar até 10 comportamentos.
Em cada fase de processamento, comportamentos distintos estão disponíveis.
| Behavior | Descrição | Fases em que pode ser utilizado | Requisitos |
|---|---|---|---|
| Add Request Header | Adiciona um campo de cabeçalho na requisição que será enviada a origem. O campo de cabeçalho deve ser informado como argumento no formato Field:value. |
Request Phase | - |
| Add Response Cookie | Adiciona um cookie na resposta através do cabeçalho Set-Cookie. O valor do cookie deve ser informado como argumento nos formatos:cookie-name=cookie-valuecookie-name=cookie-value; Expires=datecookie-name=cookie-value; Domain=domain-valuecookie-name=cookie-value; Path=path-valueMúltiplas diretivas também são permitidas, por exemplo: cookie-name=cookie-value; Domain=domain-value; Path=path-value; Expires=date |
Response Phase | Application Acceleration |
| Add Response Header | Adiciona um campo de cabeçalho na resposta que será enviada para o usuário. O campo de cabeçalho deve ser informado como argumento no formato Field: value. |
Response Phase | - |
| Bypass Cache | Define que a Azion não deverá armazenar em cache a resposta de sua origem. A execução desta regra não tem impacto sobre o cache no browser dos usuários, o qual deve ser definido utilizando o behavior Set Cache Policy | Request Phase | Application Acceleration |
| Capture Match Groups | Behavior de apoio para manipulação de strings. Armazena em uma variável temporária o resultado da captura de grupos de correspondência definidos por uma regex aplicada a um dos campos da requisição HTTP disponibilizados. Essa variável temporária pode ser posteriormente referenciada no behavior Rewrite Request para montar a string de reescrita. Este behavior requer três argumentos: captured array name: o nome que você deseja dar a variável temporária onde será armazenado o array de strings capturadas. subject: o campo da requisição HTTP de onde você deseja capturar alguma string. regex: a expressão regular usada para capturar as strings. Cada grupo capturado deve ser representado entre parênteses. Por exemplo, para capturar o caminho e o nome de um arquivo em uma requisição HTTP, você pode utilizar: captured array name: capturesubject: ${uri}regex: ^(./)([^/])$Você poderá referenciar a variável de captura como um array utilizando a notação %{*variable[index]*}. Por se tratar de uma variável local, você só poderá utilizá-la dentro da mesma regra que estiver configurando. Neste exemplo, se a URI for /path/image.jpg, a variável de captura apresentará os seguintes valores:%{capture[0]} = “/path/image.jpg”%{capture[1]} = “/path/”%{capture[2]} = “image.jpg”Você também pode nomear os índices, para referenciá-los usando nomes em vez de um índice numérico. Para tanto, utilize a notação ?<name> como no exemplo:captured array name: capturesubject: ${uri}regex: ^(?<path>.*/)(?<filename>[^/]*)$ |
Request Phase | Application Acceleration |
| Deliver | Encerra o processamento da requisição e entrega o conteúdo para o usuário, sem executar nenhuma das regras seguintes. Ao utilizar o behavior Deliver, você estará forçando o término do processamento imediatamente. | Request Phase Response Phase |
- |
| Deny (403 Forbidden) | Entrega um 403 Forbidden para o usuário. Por se tratar de uma regra finalizadora, esse behavior encerra o processamento da requisição. | Request Phase | - |
| Enable Gzip | Ativa a compressão de dados em Gzip, caso suportada pelo browser do usuário. | Request Phase Response Phase |
- |
| Enable Sliced Files | Ativa segmentação de objetos grandes em slices de 1MB, caso sua origem tenha suporte a HTTP range requests. Utilize este behavior se você entrega mídias com mais de 1MB através da CDN para que a Azion possa iniciar a entrega do conteúdo para seus usuários mesmo antes de ter recebido todo o objeto de sua origem e, dessa forma, otimizar a performance de seu site ou aplicação. Ao ativar esta funcionalidade, a Azion irá requisitar os objetos para sua origem via range requests e os mesmos serão cacheados na Azion com advanced cache key. Caso sua origem não tenha suporte a range requests, a Azion só poderá iniciar a entrega de seu conteúdo para seus usuários após sua origem finalizar o envio completo do objeto. |
Default Rule | - |
| Enforce HLS cache | Este behavior é incluído automaticamente pela Azion toda vez que você selecionar uma origem do tipo Live Ingest. Duas ações são executadas nessa situação: o bypass de todas suas regras da Cache Phase e a imposição da política de cache definida pela Azion para transmissões live em HLS. A política de cache da Azion para transmissões live em HLS é de 5 segundos de cache para playlists (.m3u8) and 60 segundos de cache para chunks (.ts). |
Request Phase | Live Ingest |
| Filter Request Header | Remove um campo de cabeçalho da requisição que será enviada para a origem. O nome do campo de cabeçalho deve ser informado como argumento. | Request Phase | - |
| Filter Response Header | Remove um campo de cabeçalho da resposta que será enviada para o usuário. O nome do campo de cabeçalho deve ser informado como argumento. | Response Phase | - |
| Forward Cookies | Ao utilizar o behavior Forward Cookies você estará determinando que a Azion encaminhe para seus usuários o cabeçalho Set-Cookie recebido de sua origem, mesmo na situação de conteúdo em cache (cache hit). Para evitar que um usuário receba Set-Cookie de sessão de outro usuário, você deve listar todos os cookies de sessão (cookies privados) de sua aplicação na aba Cache Settings de sua configuração de Content Delivery, na seção Advanced Cache Key, em Cache by Cookie. |
Request Phase | |
| Optimize Images | Ativa a otimização de imagens. | Request Phase | Image Processor |
| Redirect HTTP to HTTPS | Redireciona a requisição HTTP para a respectiva URL em HTTPS. Caso a requisição já seja HTTPS, não executa nenhum comportamento. | Request Phase | - |
| Redirect To (301 Moved Permanently) | Redireciona o usuário para uma outra URL informada como argumento, utilizando o status code 301 Moved Permanently. Por se tratar de uma regra finalizadora, esse behavior encerra o processamento da requisição. Atenção: Na Response phase, o behavior Redirect To (301 / 302) apenas é executado quando a origem retorna um erro 404. |
Request Phase Response Phase |
- |
| Rewrite Request | Modifica o path do recurso que será requisitado para a origem. Você pode reescrever o path do recurso utilizando: uma string as variáveis da requisição (as mesmas que podem ser utilizadas em Criteria) as variáveis locais, no formato %{name[index]}, com o resultado de captura de strings, ao utilizar o behavior auxiliar Capture Match Groups.Por exemplo, se você deseja que a requisição de um usuário para o recurso /original/image.jpg seja enviada para sua origem como /new/image.jpg, você pode:<li>Utilizar o behavior auxiliar Capture Match Groups com os argumentos: captured array name: capturesubject: ${uri}regex: /original/(.)<li>Utilizar o behavior Rewrite Request com o argumento /new/%{capture[1]} |
Request Phase | Application Acceleration |
| Set Cache Policy | Atribui a política de cache que deve ser utilizada para a requisição. As políticas de cache devem ser previamente configuradas na aba Cache Settings. Na política de cache você configura o tempo que o objeto deve ser armazenado em cache e as regras para variação dos objetos em cache (advanced cache key). | Request Phase | - |
| Set Origin | Atribui a origem que deve ser consultada pelo Intelligent Edge. As origens devem ser previamente configuradas na aba Origins. | Request Phase | - |
4. Funções
Para os behaviors que solicitam um argumento obrigatório, você pode utilizar as mesmas variáveis que estão disponíveis em cada fase de processamento. Dessa forma você pode, por exemplo, compor cookies ou cabeçalhos HTTP utilizando dados coletados da requisição, tais como o Device Groups do usuário ou sua geolocalização.
A Azion também disponibiliza algumas funções para simplificar a manipulação de seus argumentos:
| Função e Argumento | Descrição |
|---|---|
${cookie_time_offset(number)} |
Retorna a data atual acrescida de um offset em segundos, informado como argumento, para ser utilizado na definição do tempo de expiracão de um cookie. Por exemplo, se você deseja que o cookie expire em 1 hora, utilize o behavior Add Response Cookie com o argumento: cookie-name=cookie-value; Expires=${cookie_time_offset(3600)} |
${encode_base64(string)} |
Retorna o agumento codificado em base64. Por exemplo, ${encode_base64 (www.domain.com)} retornará o valor d3d3LmRvbWFpbi5jb20K |
5. Variáveis para Mutual Transport Layer Security (mTLS)
Utilize essas variáveis no Rules Engine da sua edge application para configurar Mutual Transport Layer Security (mTLS).
Saiba mais sobre suporte para mTLS e a diferença entre os modos Enforce (standard) e Permissive.
| Variável | Descrição | Fase |
|---|---|---|
| ${ssl_client_fingerprint} | Retorna o Secure Hash Algorithm 1 (SHA-1) do client certificate. | Requisição |
| ${ssl_client_escaped_cert} | Retorna o client certificate no formato Private Enhanced Mail (PEM)** .pem, como uma *URL encoced string. |
Requisição |
| ${ssl_client_s_dn} | Retorna o “subject DN” do client certificate. | Requisição |
| ${ssl_client_s_dn_parsed} | Retorna o “subject CN” (extraído do “subject DN”) do client certificate. | Requisição |
| ${ssl_client_cert} | Retorna o client certificate no formato PEM. Essa é uma variável descontinuada. Use $ssl_client_escaped_cert. |
Requisição |
| ${ssl_client_i_dn} | Retorna o “issuer DN” do client certificate. | Requisição |
| ${ssl_client_serial} | Retorna o serial number do client certificate. | Requisição |
| ${ssl_client_v_end} | Retorna a data de expiração do client certificate. | Requisição |
| ${ssl_client_v_remain} | Retorna o tempo, em dias, que falta para o client certificate expirar. | Requisição |
| ${ssl_client_v_start} | Retorna a data de emissão do client certificate. | Requisição |
| ${ssl_client_verify} | Retorna o resultado da verificação do client certificate. Pode ser SUCESS, FAILED:reason ou NONE. |
Requisição |
Dica: A maioria dos serviços mTLS depende do recebimento do certificado do usuário. Usando o Real-Time Manager (RTM), você pode enviar a variável
${ssl_client_escaped_cert}como Request Header (conhecido como XFCC, ou X-Forward-Client-Cert) para a origem e, em seguida, configurar sua edge application para usar esse header com os dados do certificado.
6. Debug de regras
Nota: essa funcionalidade está em early access. Entre em contato com o time de Vendas para a habilitar em sua conta.
Você pode executar o debug de regras criadas na Rules Engine para Edge Application usando GraphQL API, Data Streaming ou Real-Time Events.
Consulte Como fazer o debug de regras criadas com Rules Engine para mais detalhes e instruções sobre como ativar e usar essa funcionalidade.
Não encontrou o que procurava? Abra um ticket.