Rules Engine para Applications

Rules Engine para Applications guarda a lógica condicional de uma aplicação. Cada regra testa uma requisição contra os seus critérios, o se da regra, e executa os seus behaviors, o então, somente quando a requisição corresponde. Toda regra pertence a uma fase: ela age sobre a requisição que o usuário envia ou sobre a resposta que o usuário recebe. Algumas variáveis e alguns behaviors exigem um Produto habilitado na aplicação, e cada tabela desta página indica qual. Para a ordem em que uma aplicação executa as suas regras e os seus behaviors, consulte Como Applications funciona.

Uma regra de aplicação decide como a aplicação trata uma requisição que chegou a ela, como o connector ou o cache setting que a requisição usa. Quando o deployment do workload nomeia um firewall, o firewall decide antes se a requisição chega ou não à aplicação. Para as regras dele, consulte Rules Engine para Firewall.

Campos da regra

Uma aplicação guarda as suas regras na aba Rules Engine do Azion Console, onde + Rule cria uma regra. Uma aplicação nova não tem regras. Na API, uma regra é um objeto JSON: uma requisição define cinco dos seus campos, e a plataforma define e retorna os outros cinco.

A plataforma atribui order à medida que as regras são criadas: a primeira regra de uma fase carrega 0, e a regra seguinte carrega 1. A lista de regras do Azion Console permite mover uma regra, e uma posição além do fim da lista coloca a regra em último lugar. A API reordena uma fase com uma única chamada, que a seção API lista.

Fases

Uma regra é executada na fase escolhida na seção Phase quando a regra é criada, e essa escolha é definitiva. Para executar a mesma lógica na outra fase, crie uma regra nova nessa fase. Azion Console agrupa a lista de regras por fase, e a API mantém cada fase em uma coleção própria.

Cada fase oferece o seu próprio conjunto de variáveis e behaviors. Um valor que só existe depois que a origem responde, como ${status}, só pode ser lido na Response Phase. A coluna Fases da tabela de variáveis e as duas colunas de API da tabela de behaviors indicam qual fase aceita cada um.

Critérios

Os critérios decidem sobre quais requisições uma regra age. Um critério nomeia uma variável, um operador e, para a maioria dos operadores, um argumento com o qual a variável é comparada. Na API, um critério é um objeto com quatro chaves: variable, operator, conditional e argument.

Este critério corresponde a uma requisição de um navegador desktop, com uma expressão regular sobre o header User-Agent:

Variáveis

Uma variável contém um valor da requisição ou da resposta, e a coluna Fases indica onde um critério pode lê-la. ${request_uri} e ${device_group} exigem Application Accelerator na aplicação. A API recusa uma regra com ${request_uri} em uma aplicação sem esse Produto, com 400 e o código 25047. ${uri} não exige nenhum Produto, então é a variável de URI para uma aplicação sem Application Accelerator.

Seis entradas são famílias: substitua name pelo argumento, pelo cookie ou pelo header a ser lido.

Variáveis de Mutual Transport Layer Security (mTLS)

Estas variáveis contêm o certificado de cliente que uma requisição apresenta por mTLS, em que o cliente também se autentica com um certificado. Um critério as lê somente na Request Phase. Para saber como um workload pede e valida certificados de cliente, consulte mTLS.

A maioria dos serviços mTLS espera receber o próprio certificado de cliente. Uma regra da Request Phase pode enviar ${ssl_client_escaped_cert} à origem no header X-Forward-Client-Cert (XFCC) com Add Request Header, e a origem então lê os dados do certificado nesse header.

Variáveis em argumentos de behaviors

Um behavior que recebe um argumento pode ler as variáveis da sua fase. Por exemplo, uma regra pode gravar o device group ou a geolocalização de uma requisição em um cookie ou em um header.

Esta regra da Response Phase define um cookie que registra o host da requisição:

Quando a regra corresponde, a resposta carrega Set-Cookie: cookie-host-value=host.com.

Outras duas variáveis agem como funções: cada uma recebe um argumento, e as duas funcionam somente dentro do argumento de um behavior.

Operadores

Um critério compara a sua variável com o seu argumento por meio de um operador, e a API envia o operador como um destes valores em operator. Os operadores que Azion Console oferece podem variar conforme a variável que o critério usa.

Condicionais

Os critérios se combinam dentro de grupos, e uma regra tem de 1 a 5 grupos de 1 a 10 critérios cada. Em um grupo, o primeiro critério carrega o condicional if, e cada critério seguinte carrega and ou or. Azion Console une os critérios com And e Or.

Dentro de um grupo, and tem precedência sobre or. Para definir a precedência você mesmo, divida as condições em grupos: os grupos de uma regra são unidos por and, então uma requisição corresponde à regra somente quando corresponde a todos os grupos. Por exemplo, uma regra que precisa de A or B, e também de C, coloca A or B em um grupo e C em um segundo grupo.

Na API, criteria é uma lista de grupos, e cada grupo é uma lista de objetos de critério, como em [[{ … }]].

Behaviors

Behaviors são o que uma regra faz com uma requisição, ou com uma resposta, que corresponde aos seus critérios, e uma regra carrega de 1 a 10 deles. Azion Console rotula a primeira linha de behavior como Then e cada linha seguinte como And, e + Add Behavior adiciona uma linha. Alguns behaviors não podem ser adicionados juntos, ou só podem sob algumas condições, e Azion Console recusa essas combinações.

Na API, cada behavior é um objeto com um type. Um behavior que recebe um argumento o carrega em attributes.value, e Capture Match Groups carrega, em vez disso, três atributos nomeados. Azion Console recusa alguns argumentos que contêm um espaço, com Argument cannot contain spaces, use %20 instead.

As duas colunas de API indicam o type que cada fase aceita, e a coluna Exige indica o Produto que a aplicação precisa ter habilitado. Quando esse Produto está desativado, Azion Console acrescenta - Required Application Accelerator, - Required Image Processor ou - Required Function ao rótulo. Uma aplicação nova tem Cache e Functions ativados, e Application Accelerator e Image Processor desativados.

Add Cookie

Add Cookie adiciona um cookie no header Set-Cookie, em qualquer uma das fases, e exige Application Accelerator na aplicação. Em uma regra da Response Phase, o behavior é Add Response Cookie. O argumento tem a forma cookie-name=cookie-value, e o valor pode ser uma variável, como em cookie-name=${arg_cookie}. Azion Console verifica o argumento e mostra This cookie is not valid quando não consegue ler um cookie nele.

Na Response Phase, o argumento pode carregar atributos de Set-Cookie depois do valor, cada um depois de um ponto e vírgula (;):

• Expires=date, no formato EEE, d MMM yyyy HH:mm:ss Z
• Domain=domain-value
• Path=path-value
• Max-age=number, um TTL em segundos que tem precedência sobre Expires
• SameSite=value; Secure
• HttpOnly

Um cookie com vários atributos os encadeia, como em cookie-name=cookie-value; Domain=domain-value; Path=path-value; SameSite=value. O valor de um atributo também pode ser uma variável, como em Path=${uri}; Domain=${host}. Na API, o type da Request Phase é add_request_cookie e o type da Response Phase é set_cookie, com o argumento em attributes.value.

Add Request Header

Add Request Header adiciona um header à requisição que a Azion envia à origem, na Request Phase, e não exige nenhum Produto. Uma regra da Response Phase adiciona, em vez disso, o header à resposta enviada ao usuário, com o type de API add_response_header. O argumento tem a forma Field: value, e Azion Console recusa qualquer outro formato com Header must follow the header-name: value format.

O nome do header aceita somente letras (a-z, A-Z), números (0-9), hífens e underscores, e qualquer outro caractere torna o header inválido. O valor do header aceita letras, números e estes caracteres:

O argumento comporta até 1.600 caracteres, e um argumento mais longo falha com Argument too long. Este argumento é um header válido:

Na API, o behavior é add_request_header, com o header em attributes.value, como "Accept: image/webp". Um behavior do tipo add_header é recusado com 400 e o código 10039. Os headers Host, Connection, Range, X-Forward-For e Cdn-Loop não podem ser sobrescritos nem filtrados.

Bypass Cache

Bypass Cache envia à origem as requisições que correspondem à regra, e a Azion não armazena a resposta em cache. Ele é executado na Request Phase e exige Application Accelerator na aplicação. O behavior não altera o cache do navegador, que Set Cache Policy define por meio de um cache setting. Na API, ele é { "type": "bypass_cache" }, sem atributos.

Bypass Cache age sobre o cache da Azion, e não sobre a camada do Tiered Cache. Uma aplicação cujos cache settings têm Tiered Cache ativado continua armazenando objetos em cache nessa camada pelo TTL mínimo. Para saber como Bypass Cache difere de um TTL de cache igual a 0, consulte Como Applications funciona. Para ignorar o cache em um path, consulte Ignore o cache em um path.

Capture Match Groups

Capture Match Groups aplica uma expressão regular a um campo da requisição e guarda os grupos que ela captura em um array temporário. Ele é executado em qualquer uma das fases e exige Application Accelerator na aplicação. Rewrite Request lê o array para montar um novo caminho. O array é local, então somente a regra que o captura pode lê-lo.

Uma captura é lida como %{name[index]}. Por exemplo, com capture como nome do array, ${uri} como subject e ^(.*/)([^/]*)$ como expressão regular, uma requisição para /path/image.jpg preenche três entradas:

• %{capture[0]} = "/path/image.jpg"
• %{capture[1]} = "/path/"
• %{capture[2]} = "image.jpg"

Um grupo também pode ter um nome, na notação ?<name>, e a sua captura é então lida por esse nome, em vez de por um índice. Esta expressão regular nomeia os dois grupos path e filename: ^(?<path>.*/)(?<filename>[^/]*)$.

Deliver

Deliver encerra o processamento da requisição e entrega o conteúdo ao usuário, e as regras seguintes não são executadas. Ele é executado em qualquer uma das fases, não exige nenhum Produto e não recebe argumento. Na API, ele é { "type": "deliver" }.

Deny (403 Forbidden)

Deny (403 Forbidden) responde à requisição com uma página 403 Forbidden e encerra o processamento da requisição. Ele é executado na Request Phase, não exige nenhum Produto e não recebe argumento. Na API, ele é { "type": "deny" }.

Enable Gzip

Enable Gzip comprime o conteúdo com gzip quando o navegador do usuário oferece suporte a isso. Ele é executado em qualquer uma das fases, não exige nenhum Produto e é { "type": "enable_gzip" } na API. Para ativar a compressão em uma aplicação, consulte Comprima as respostas de uma aplicação com gzip.

Enforce HLS cache

Enforce HLS cache impõe a política de cache que a Azion define para transmissões HLS ao vivo, e exige Live Ingest. A Azion adiciona o behavior a uma regra da Request Phase toda vez que você seleciona uma fonte Live Ingest. O behavior faz duas coisas: ignora as regras de cache da aplicação e aplica a política de HLS ao vivo.

Para aplicar a política a um stream, consulte Implemente cache HLS para streaming ao vivo.

Filter Request Cookie

Filter Request Cookie remove um cookie da requisição que a Azion envia à origem, e exige Application Accelerator na aplicação. Uma regra da Response Phase remove, em vez disso, um cookie da resposta enviada ao usuário, com o type de API filter_response_cookie. O argumento é cookie-name, para remover o cookie, ou cookie-name=cookie-value, para remover somente esse valor. Na API, o type da Request Phase é filter_request_cookie.

Filter Request Header

Filter Request Header remove um header da requisição que a Azion envia à origem, e não exige nenhum Produto. Uma regra da Response Phase remove, em vez disso, um header da resposta enviada ao usuário, com o type de API filter_response_header. O argumento é o nome do header, como Header-Name. Na API, o type da Request Phase é filter_request_header.

Cinco headers não podem ser filtrados nem sobrescritos:

• Host
• Connection
• Range
• X-Forward-For
• Cdn-Loop

Finish Request Phase

Finish Request Phase encerra a Request Phase. Os behaviors depois dele na regra, e as regras depois dessa regra, não são executados. Ele é executado na Request Phase, não exige nenhum Produto e é { "type": "finish_request_phase" } na API.

Forward Cookies

Forward Cookies faz a Azion encaminhar aos usuários o header Set-Cookie que a origem retorna, mesmo quando a resposta vem do cache. Ele é executado na Request Phase, exige Application Accelerator na aplicação e é { "type": "forward_cookies" } na API. Uma resposta em cache pode então carregar o Set-Cookie da sessão de outro usuário. Para manter as sessões separadas, consulte Encaminhe cookies da origem ao usuário.

Cookies criados com JavaScript são uma alternativa ao header de resposta Set-Cookie: um script os cria, lê e expira por meio da propriedade document.cookie. Um cookie JavaScript tem este formato:

A Azion não filtra o header de requisição Cookie por padrão, qualquer que seja a configuração de Forward Cookies, então os cookies JavaScript chegam à origem. Para mais informações, consulte JavaScript Cookies.

No Content (204)

No Content (204) responde com 204 em vez do status code que a origem retorna. Ele é executado na Request Phase, não exige nenhum Produto e é { "type": "no_content" } na API.

Optimize Images

Optimize Images aplica Image Processor às requisições que correspondem à regra, e exige Image Processor na aplicação. Ele é executado na Request Phase. Na API, ele é { "type": "optimize_images" }: não recebe atributos, e uma regra pode carregá-lo como o seu único behavior.

Redirect HTTP to HTTPS

Redirect HTTP to HTTPS redireciona para HTTPS uma requisição feita por HTTP, e não faz nada com uma requisição já feita por HTTPS. Ele é executado na Request Phase e é { "type": "redirect_http_to_https" } na API. Ele exige HTTPS habilitado nas configurações de protocolo do workload que entrega a aplicação.

Redirect To

Redirect To (301 Moved Permanently) e Redirect To (302 Found) enviam o usuário para a URL ou a URI do argumento, com esse status code. Use 301 quando um caminho muda de forma definitiva, e 302 quando a mudança é temporária. Os dois behaviors encerram o processamento da requisição, são executados em qualquer uma das fases e não exigem nenhum Produto. Em uma regra da Response Phase, eles são executados somente quando a origem retorna 404.

Azion Console pede o argumento com Redirect target is required e recusa um espaço nele com Redirect target cannot contain spaces, use %20 instead. Na API, os tipos são redirect_to_301 e redirect_to_302, com o destino em attributes.value. Este behavior envia o leitor de uma FAQ para a versão em inglês dela:

Rewrite Request

Rewrite Request altera o caminho do recurso que a Azion requisita à origem. Ele é executado na Request Phase, exige Application Accelerator na aplicação e é rewrite_request na API, com o novo caminho em attributes.value. O novo caminho pode combinar uma string, as variáveis da Request Phase e as capturas de Capture Match Groups, escritas como %{name[index]}.

Por exemplo, dois behaviors em uma regra enviam à origem uma requisição para /original/image.jpg como /new/image.jpg:

Run Function

Run Function executa uma instância de função da aplicação sobre o que corresponde à regra. Ele é executado em qualquer uma das fases e exige Application Accelerator e Functions na aplicação. As instâncias ficam na aba Functions Instances da aplicação, e uma aplicação nova tem Functions ativado. Para a Response Phase, o formulário de instância de função do Azion Console informa Only Lua functions can be used in the Response phase.

Na API, attributes.value contém o ID da instância de função, e não o da função, como em { "type": "run_function", "attributes": { "value": <function-instance-id> } }. Para criar uma instância, consulte Instancie uma função em uma aplicação.

Set Cache Policy

Set Cache Policy aplica um cache setting às requisições que correspondem à regra, e é assim que um cache setting chega a uma requisição. Ele é executado na Request Phase e não exige nenhum outro Produto. O cache setting vem primeiro, na aba Cache Settings da aplicação, e o behavior então o nomeia em uma segunda lista.

O cache setting define por quanto tempo um objeto fica em cache. A sua seção Application Accelerator contém as variações que definem a cache key. Na API, attributes.value contém o ID do cache setting. A API retorna esse ID como um inteiro, mesmo quando a requisição o envia como string. Um cache setting que uma regra aplica não pode ser excluído: a API responde 400 com o código 21014.

Set Connector

Set Connector envia as requisições que correspondem à regra a um connector, que alcança a origem. No Azion Console, as origens foram redesenhadas como connectors, e este behavior nomeia um connector. Ele é executado na Request Phase e não exige nenhum Produto, então uma regra com ${uri} e Set Connector funciona em uma aplicação sem Application Accelerator. Na API, attributes.value contém o ID do connector, como mostra a seção API.

API

Toda operação de regra é autenticada e fica em https://api.azion.com/v4/workspace/applications/<application-id>. Uma requisição carrega um personal token no header Authorization, com o esquema Token. Uma requisição com corpo também carrega Content-Type: application/json.

Uma criação responde 202 com um state igual a pending, e uma listagem responde 200. A chamada de reordenação recebe um array order que lista os IDs das regras da fase na nova ordem.

Esta chamada cria uma regra da Request Phase que envia toda requisição da aplicação a um connector:

A resposta carrega 202 e um state igual a pending. Este trecho mantém a regra como a plataforma a armazenou:

A plataforma adiciona description, uma string vazia quando a criação não envia nenhuma, e order, a posição da regra na sua fase. O mesmo corpo com ${request_uri} no lugar de ${uri} falha com o código 25047 em uma aplicação sem Application Accelerator.

CLI

Azion CLI cria uma regra com azion create rules-engine, que lê a regra de um arquivo JSON no formato que a API recebe. --phase indica a fase, e o padrão é request.

Este arquivo aplica um cache setting a toda requisição cujo caminho começa com /static/:

Salve-o como rule.json, substitua <cache-setting-id> pelo ID de um cache setting da aplicação e crie a regra:

Azion CLI recusa dois formatos antigos de arquivo de regra. Um critério com input_value no lugar de argument falha com json: unknown field "input_value". Um behavior escrito como {"type":"set_cache_settings","cache_settings_id":"<id>"} falha com data failed to match schemas in oneOf(RequestPhaseBehaviorRequest): o behavior é set_cache_policy, com o ID em attributes.value.

Erros

Uma regra recusada retorna um array errors. Cada entrada carrega um code, um title, um detail, o status e um ponteiro source que indica o campo, e algumas entradas adicionam um objeto meta. Este corpo responde a uma regra com ${request_uri} em uma aplicação sem Application Accelerator:

Recursos relacionados