---
name: azion-crie-um-cache-setting
description: >-
  Crie um cache setting em uma aplicação e aplique-o com uma regra, pelo Azion Console, pela Azion API ou pela Azion CLI.
---

# Crie um cache setting

Você cria um cache setting em uma aplicação pelo Azion Console, pela Azion API v4 ou pela Azion CLI, e o aplica às requisições com uma regra do [Rules Engine](/pt-br/documentacao/plataforma/applications/rules-engine/). Um setting carrega os TTLs e as regras de variação; enquanto uma regra não o nomear pelo behavior **Set Cache Policy**, ele não se aplica a nenhuma requisição.

Para um primeiro cache setting apenas pelo Console, consulte [Primeiros passos com Cache](/pt-br/documentacao/plataforma/applications/cache/primeiros-passos/). Para variar o cache por um argumento de query string ou por um cookie, consulte [Configure a Advanced Cache Key para uma aplicação](/pt-br/documentacao/guias/performance-e-confiabilidade/cache-e-purge/advanced-cache-key/).

---

## Pré-requisitos

- Uma aplicação. Para criar uma, consulte [Primeiros passos com Applications](/pt-br/documentacao/plataforma/applications/primeiros-passos/).
- Acesso ao Azion Console, para os procedimentos pelo Console. Consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/).
- Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/), para os procedimentos pela API.
- A [Azion CLI](/pt-br/documentacao/devtools/cli/) instalada e autorizada, para os procedimentos pela CLI.
- O [Application Accelerator](/pt-br/documentacao/plataforma/applications/#application-accelerator) na aplicação, para um **Max Age** abaixo de 60 segundos ou para variação de cache.

---

## Crie o cache setting pelo Azion Console

O drawer **Create Cache Settings** carrega cada campo de um setting. Para criar um:

1. **Abra a aplicação**

   Acesse [Azion Console](https://console.azion.com/) > **Applications** e selecione a aplicação.

2. **Vá para a aba Cache Settings**

3. **Selecione + Cache**

4. **Nomeie o cache setting**

   Em **Name**, insira um nome único e descritivo.

5. **Escolha o comportamento do browser cache**

   Em **Browser Cache**, selecione uma opção. *Honor cache policies* repassa ao browser os headers `Cache-Control` e `Expires` da origem. *Override cache settings* os substitui por um TTL que você insere. *No cache* desativa o cache no browser, de modo que o conteúdo é sempre buscado no servidor.

6. **Escolha o comportamento de cache**

   Em **Cache**, selecione *Honor cache policies* para manter os headers da origem, ou *Override cache behavior* para substituí-los.

7. **Defina o Max Age**

   Em **Max Age**, insira os segundos que a Azion mantém uma cópia. Um setting novo carrega `60`.

8. **Ative o Stale cache**

   Com o toggle ativo, a Azion entrega uma cópia expirada quando uma tentativa de revalidação com a origem falha.

9. **Ative o Large file optimization**

   Com o toggle ativo, a Azion coloca um objeto grande em cache em fragmentos, e não como uma peça única.

10. **Ative o Tiered Cache**

    O toggle adiciona uma segunda camada de cache entre o cache da Azion e a origem. Ele exige *Override cache behavior* e um **Max Age** de pelo menos 3 segundos.

11. **Selecione Save**

O setting aparece na lista de **Cache Settings** com o seu **Name**, **ID**, **Browser Cache** e **Cache**. Para cada campo, com o seu tipo, o seu padrão e os seus limites, consulte [Cache settings](/pt-br/documentacao/plataforma/applications/cache/cache-settings/).

---

## Aplique o setting com uma regra

Uma regra na request phase decide quais requisições o setting cobre. Para criá-la:

1. **Vá para a aba Rules Engine**

2. **Selecione + Rule**

3. **Nomeie a regra**

4. **Selecione Request Phase**

5. **Defina os criteria**

   Em **Criteria**, selecione `${uri}`, um operador e o argumento que casa os paths a colocar em cache.

6. **Adicione o behavior Set Cache Policy**

   Em **Behaviors**, selecione **Set Cache Policy** e depois selecione o cache setting.

7. **Selecione Save**

A regra aparece na lista e aplica o setting a cada requisição que os seus criteria casam.

> **nota**
>
> Uma regra nova pode levar alguns minutos para propagar. Aguarde antes de verificar o status de cache de uma resposta.

---

## Crie o cache setting pela API

Duas requisições criam o setting e a regra que o aplica. Para enviá-las:

1. **Crie o cache setting**

   ```bash
   curl --location --request POST 'https://api.azion.com/v4/workspace/applications/{application_id}/cache_settings' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Token [TOKEN VALUE]' \
   --data '{
     "name": "static-assets",
     "browser_cache": { "behavior": "no-cache" },
     "modules": {
       "cache": {
         "behavior": "override",
         "max_age": 300,
         "stale_cache": { "enabled": true },
         "large_file_cache": { "enabled": true, "offset": 1024 },
         "tiered_cache": { "enabled": true, "topology": "nearest-region" }
       }
     }
   }'
   ```

2. **Leia o id na resposta**

   A API responde com HTTP `201`, `state` igual a `executed` e o novo setting em `data`:

   ```json
   {"state":"executed","data":{"id":123456,"name":"static-assets","browser_cache":{"behavior":"no-cache","max_age":0},"modules":{"cache":{"behavior":"override","max_age":300,"stale_cache":{"enabled":true},"large_file_cache":{"enabled":true,"offset":1024},"tiered_cache":{"topology":"nearest-region","enabled":true}}},"created_at":"2026-01-01T12:00:00.577248Z"}}
   ```

3. **Crie a regra que o aplica**

   Substitua `[CACHE SETTING ID]` pelo `id` que a resposta retornou:

   ```bash
   curl --location --request POST 'https://api.azion.com/v4/workspace/applications/{application_id}/request_rules' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Token [TOKEN VALUE]' \
   --data '{
     "name": "apply-static-assets-cache",
     "criteria": [[{ "variable": "${uri}", "operator": "starts_with", "conditional": "if", "argument": "/static/" }]],
     "behaviors": [{ "type": "set_cache_policy", "attributes": { "value": "[CACHE SETTING ID]" } }]
   }'
   ```

4. **Leia a resposta da regra**

   A API responde com HTTP `202` e a regra com `state` igual a `pending`, porque uma regra nova propaga antes de se aplicar:

   ```json
   {"state":"pending","data":{"id":234572,"name":"apply-static-assets-cache","active":true,"order":0}}
   ```

O setting agora se aplica a cada requisição cujo path começa com o argumento. Para listar os settings de uma aplicação, envie um `GET` para o mesmo path `cache_settings`.

---

## Crie o cache setting pela Azion CLI

A CLI cobre parte do objeto com flags, e o objeto inteiro com um arquivo JSON. Para criar um setting por flags:

1. **Execute o comando de criação**

   ```bash
   azion create cache-setting \
   --application-id <application-id> \
   --name "product-listing" \
   --browser-cache-behavior override \
   --browser-cache-max-age 30 \
   --cache-by-query-string allowlist \
   --query-string-fields "category,page" \
   --cache-by-cookies allowlist \
   --cookie-names "session_id"
   ```

2. **Leia o id na saída**

   ```text
   Created Cache Settings configuration with ID 123457
   ```

3. **Leia o setting de volta**

   ```bash
   azion describe cache-setting --application-id <application-id> --cache-setting-id 123457 --format json
   ```

   O objeto carrega o browser cache e os campos de variação que as flags definiram, e o `modules.cache` nos seus padrões: `honor` e `60`.

Para criar um setting com os campos que as flags não cobrem, envie o corpo da requisição a partir de um arquivo:

1. **Escreva o corpo em um arquivo**

   Salve o corpo da requisição da API acima como `cache-setting.json`.

2. **Crie o setting a partir do arquivo**

   ```bash
   azion create cache-setting --application-id <application-id> --file cache-setting.json
   ```

   O comando imprime o id do novo setting:

   ```text
   Created Cache Settings configuration with ID 123458
   ```

> **nota**
>
> As flags da CLI não definem o **Max Age**, o comportamento de cache, o stale cache, o Large File Optimization nem o Tiered Cache. Use o `--file` com o corpo da requisição para esses campos.

A CLI não cria a regra que aplica o setting. Crie-a pelo Console ou pela API, com qualquer um dos procedimentos desta página. Para cada flag, consulte [Azion CLI create](/pt-br/documentacao/devtools/cli/recursos/).

---

## Próximos passos

- [Cache settings](/pt-br/documentacao/plataforma/applications/cache/cache-settings.md): Todos os campos de um cache setting, com o seu tipo, o seu padrão por interface e os seus limites.
- [Expiração e atualização](/pt-br/documentacao/plataforma/applications/cache/expiracao-e-atualizacao.md): O que o TTL, o stale cache e a segunda camada fazem em uma requisição.
- [Configure políticas de cache para uma aplicação](/pt-br/documentacao/guias/performance-e-confiabilidade/cache-e-purge/cache-settings.md): Defina um TTL para um path, ignore o cache em outro e encaminhe cookies.
- [Purgue conteúdo em cache](/pt-br/documentacao/guias/performance-e-confiabilidade/cache-e-purge/purgar-conteudo-em-cache.md): Remova uma cópia armazenada antes do fim do TTL deste setting.
- [Acelerar sites e APIs com uma CDN](/pt-br/documentacao/casos-de-uso/melhorar-performance-e-confiabilidade/acelerar-sites-e-apis-com-uma-cdn.md): Dois cache settings, um com Tiered Cache, que servem os arquivos estáticos e as páginas de um site perto dos usuários.