# Como ajustar as configurações de cache

import Tabs from '~/components/tabs/Tabs'


Utilize as capacidades do [Cache](/pt-br/documentacao/produtos/build/applications/cache-settings/) para configurar as [políticas de cache](/pt-br/documentacao/produtos/build/applications/cache-settings/) da sua application, incluindo valores de expiração no edge ou no navegador, otimização de arquivos grandes para dividir conteúdos em partes menores e segmentação de cache key com base em métodos HTTP, query strings, cookies ou grupos de dispositivos.

:::caution[atenção]
Algumas funcionalidades de cache requerem que o módulo [Application Accelerator](/pt-br/documentacao/produtos/build/applications/application-accelerator/) esteja ativo. Se o **Application Accelerator** estiver ativado, a transferência de dados pode gerar custos relacionados ao uso. Consulte a [página de preços](/pt-br/documentacao/produtos/precos/) para mais informações.
:::

---

Quando você [cria uma application](/pt-br/documentacao/produtos/comecar-com-um-template/) pela primeira vez, uma variável de configuração de cache será criada e ativada por padrão. Este guia mostrará como criar e ativar uma nova instância de configuração de cache.

<Tabs client:visible>
    <Fragment slot="tab.console">Console</Fragment>
    <Fragment slot="tab.api">API</Fragment>

<Fragment slot="panel.console">
1. Acesse o [Azion Console](/pt-br/documentacao/produtos/guias/como-acessar-o-azion-console/) > **Applications**.
2. Clique na application que você deseja configurar. 
3. Ative o módulo **Application Accelerator** para desbloquear configurações avançadas de cache key.
4. Clique no botão **Save**.
5. Navegue até a aba **Cache Settings**.
6. Clique no botão **+ Cache Setting**.
7. Dê um nome para sua configuração de cache.

**Cache Expiration Policies**

Você pode personalizar o Time To Live (TTL) do cache nos navegadores e no edge. Esses dados são enviados em requisições e respostas através dos cabeçalhos HTTP `Cache-Control` e `Expires`.

:::note
O TTL é determinado pela diretiva `max-age` em `Cache-Control`. Se `Cache-Control` não estiver presente na requisição ou resposta, o timestamp enviado no cabeçalho `Expires` determina o TTL do cache. 
:::

1. Em **Browser Cache**, selecione **Override cache settings** para determinar um valor de TTL personalizado.
2. Adicione o TTL em segundos no campo **Max Age (seconds)**. Por exemplo: `432000` = 5 dias.

Em **Cache**, você pode determinar se o edge deve obedecer aos valores enviados nos cabeçalhos `Cache-Control` e `Expires`.

Você pode optar por manter **Honor cache policies** selecionado para respeitar os valores TTL enviados nos cabeçalhos pela origem ou pela própria aplicação.

Se a sua aplicação não estiver enviando cabeçalhos `Cache-Control` e `Expires` ou se os valores não estiverem configurados corretamente, você pode determinar um TTL máximo padrão para o cache ser mantido no edge no campo **Max Age (seconds)**. Se a sua aplicação estiver enviando esses valores, para substituí-los:

3. Em **Cache**, selecione **Override cache settings** para determinar um valor de TTL personalizado.
4. Adicione o TTL em segundos no campo **Max Age (seconds)**. Por exemplo: `864000` = 10 dias.

:::note
Os valores máximo e padrão de TTL para o edge devem estar entre `60` e `31536000` segundos (1 ano). Se você tiver o módulo [Application Accelerator](/pt-br/documentacao/produtos/build/applications/application-accelerator/) ativado, você pode definir este valor para um mínimo de `0`. Além disso, se você tiver o módulo [Cache](/pt-br/documentacao/produtos/build/applications/cache/tiered-cache/) ativado e desejar manter o cache na camada de Cache, você deve definir o TTL para pelo menos `3` segundos.

Um TTL zero não é o mesmo que um cache bypass. Para mais detalhes, leia sobre a diferença entre essas configurações na documentação [behavior Bypass Cache](/pt-br/documentacao/produtos/build/applications/rules-engine/#bypass-cache).
:::

**Stale cache**

A Azion oferece a capacidade de servir conteúdo obsoleto do cache quando o servidor de origem estiver inativo ou enquanto o cache estiver sendo renovado. A funcionalidade **Stale Cache** está habilitada por padrão, permitindo que sua aplicação continue servindo o conteúdo em um cache mais recente durante esses eventos.

**Otimização de arquivos grandes**

Em vez de baixar um arquivo de conteúdo grande e correr o risco de timeouts ou terminações de conexão, [os arquivos podem ser divididos](/pt-br/documentacao/produtos/build/applications/cache-settings/#large-file-optimization) em partes menores e armazenados em cache sob demanda.

5. Em **Large file optimization**, habilite o switch para ativar.
6. A camada **Cache** já está selecionada por padrão. Se você tiver o módulo **Cache** ativado, você também pode habilitar este recurso para a camada de Cache.

:::note
O tamanho padrão dos fragmentos é de `1024 kB`.
:::

**Application Accelerator**

Esta seção permite que você personalize como o cache varia com base em métodos HTTP, campos de query string, cookies e grupos de dispositivos por meio de [cache keys](/pt-br/documentacao/produtos/build/applications/cache-settings/#advanced-cache-key). Você pode escolher segmentar as cache keys usando esses atributos para controlar como os objetos são armazenados e servidos a partir do cache.

:::caution[atenção]
Para habilitar todas as funcionalidades do **Application Accelerator**, você deve ativar o módulo [Application Accelerator](/pt-br/documentacao/produtos/build/applications/application-accelerator/).
:::

Para determinar a variação de conteúdo no cache:

9. Em **Cache vary by Query String**, selecione **Content varies by some query string fields (Allowlist)**.
10. Em **Query string fields**, adicione o valor `cidade`.
  - Este campo diferencia letras maiúsculas de minúsculas e as trata de forma distinta ao armazenar objetos no cache.

Quando uma requisição é feita para uma URL de aplicação `xxxxxxxxxx.map.azionedge.net/pagina?city=12345`, a cache key para essa URL será diferente das cache keys feitas para `xxxxxxxxxx.map.azionedge.net/pagina` e quaisquer outras query strings adicionadas à URL.

:::tip
Use a opção **Content varies by query string, except for some fields (Blocklist)** para fazer o inverso: manter todas as requisições com query strings como cache keys diferentes; as especificadas em **Query string fields** serão agrupadas em uma única cache key.
:::

Para desconsiderar a ordem dos dados enviados na query string e manter objetos com os mesmos valores de query string como uma única cache key:

11. Ative **Query String Sort**.

Você também pode personalizar quais tipos de requisições podem ser armazenadas em cache:

12. Ative **Enable caching for POST** para armazenar requisições `POST` em cache.
13. Ative **Enable caching for OPTIONS** para armazenar requisições `OPTIONS` em cache.

14. Em **Cache vary by Cookies**, selecione **Content varies by some cookies (Allowlist)**.
15. Em **Cookie Names**, adicione o valor `nome_do_cookie`.
  - Este campo diferencia letras maiúsculas de minúsculas e as trata de forma distinta ao armazenar objetos no cache.

Quando uma requisição é feita a uma aplicação e a resposta da origem envia um cabeçalho `Set-Cookie`, os objetos no cabeçalho de requisição `Cookie` que contêm o nome `nome_do_cookie`, independentemente do valor, serão considerados como um objeto diferente no cache de outras requisições.

:::tip
Use a opção **Content varies by cookies, with the exception of a few (Blocklist)** para fazer o inverso: manter todas as requisições com cookies como cache keys diferentes; as especificadas em **Cookie names** serão agrupadas em uma única cache key.
:::

16. Em **Cache vary by Devices**, selecione **Content varies by some device groups (Allowlist)**.
17. Clique no botão **+ Add Device Group** para adicionar um device group e selecione‑o da lista.
18. Repita o passo anterior para cada device group para o qual você deseja especificar uma cache key diferente.

Depois de terminar de configurar a sua cache setting:

19. Clique no botão **Save**.

**Activating your cache setting**

A página de configurações de cache agora lista a nova instância criada. No entanto, essa nova configuração de cache não está ativa em sua aplicação. Você precisa definir o que acionará a implementação das políticas de cache em sua aplicação. Para isso, você pode usar o [Rules Engine](/pt-br/documentacao/produtos/build/applications/rules-engine/) de sua application.

As instruções abaixo ajudarão você a criar uma regra na qual qualquer requisição de seus usuários para `xxxxxxxxxx.map.azionedge.net/cache` aplicará a configuração de cache que você criou.

1. Navegue até a aba **Rules Engine**.
2. Clique no botão **+ Rule**.
3. Dê um nome para sua regra.
4. Selecione **Request Phase**.
5. Na seção **Criteria**, selecione a variável `${uri}`.

:::note
A variável `${uri}` pode já estar selecionada por padrão se você não ativou o módulo **Application Accelerator**.
:::

6. Como operador de comparação, selecione **is equal**.
7. Como argumento, adicione `/cache`.
8. Na seção **Behaviors**, selecione **Set Cache Policy** na lista de comportamentos.
9. Selecione a nova cache setting que você criou.
10. Clique no botão **Save**.
11. Aguarde alguns minutos para que as alterações se propaguem.

Para analisar como seu conteúdo está sendo armazenado em cache, você pode verificar os indicadores de cache da aplicação usando o [Modheader para Google Chrome](/pt-br/documentacao/produtos/guias/verificar-tempo-de-cache-da-pagina/).
</Fragment>

<Fragment slot="panel.api">
1. Execute a seguinte requisição `PATCH` em seu terminal, substituindo `[TOKEN VALUE]` pelo seu [personal token](/pt-br/documentacao/produtos/guias/personal-tokens/) e a variável `<application_id>` pelo [ID da sua application](/pt-br/documentacao/produtos/guias/build/definir-configuracoes-principais/) para ativar o módulo [Application Accelerator](/pt-br/documentacao/produtos/build/applications/application-accelerator/):

```bash
curl --location --request PATCH 'https://api.azionapi.net/v4/edge_application/applications/<application_id>' \
--header 'Accept: application/json;' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--data '{
    "application_acceleration": true
}'
```

2. Você receberá uma resposta com o valor atualizado.
3. Se você quiser configurar a entrega adaptativa para um dos seus [device groups](/pt-br/documentacao/produtos/guias/build/criar-device-groups/), execute a seguinte requisição `GET` antes:

```bash
curl --location 'https://api.azionapi.net/v4/edge_application/applications/<application_id>/device_groups' \
--header 'Accept: application/json;' \
--header 'Authorization: Token [TOKEN VALUE]'
```

4. Copie o ID recebido na resposta.
5. Execute a seguinte requisição `POST` em seu terminal, substituindo `[TOKEN VALUE]` pelo seu [personal token](/pt-br/documentacao/produtos/guias/personal-tokens/), a variável `<application_id>` pelo [ID da sua application](/pt-br/documentacao/produtos/guias/build/definir-configuracoes-principais/), e a variável `<device_group_id>` pelo ID do device group da resposta anterior, se necessário:

```bash
curl --location 'https://api.azionapi.net/v4/edge_application/applications/<application_id>/cache_settings' \
--header 'Accept: application/json;' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--data '{
  "name": "/cache O60 O13660 Wcity Wcookie_name Wdg POST OPTIONS SLICE",
  "browser_cache": {
    "behavior": "override",
    "max_age": 60
  },
  "modules": {
    "edge_cache": {
      "behavior": "override",
      "max_age": 13660,
      "stale_cache": {
        "enabled": false
      },
      "large_file_cache": {
        "enabled": true,
        "offset": 1024
      }
    },
    "application_accelerator": {
      "cache_vary_by_method": [
        "post",
        "options"
      ],
      "cache_vary_by_querystring": {
        "behavior": "whitelist",
        "fields": [
          "city"
        ],
        "sort_enabled": false
      },
      "cache_vary_by_cookies": {
        "behavior": "whitelist",
        "cookie_names": [
          "cookie_name"
        ]
      },
      "cache_vary_by_devices": {
        "behavior": "whitelist",
        "device_group": [
          <device_group_id>
        ]
      }
    }
  }
}'
```

  | Chave | Descrição |
  | --- | --- |
  | `name` | Define uma string como o nome da configuração de cache. |
  | `browser_cache.behavior` | Define o comportamento de cache para navegadores. `"honor"` respeita os cabeçalhos de TTL enviados pela origem; `"override"` permite definir um valor de TTL personalizado usando `max_age`. |
  | `browser_cache.max_age` | TTL máximo (em segundos) para cache do navegador quando `behavior` está configurado como `"override"`. |
  | `modules.edge_cache.behavior` | Define o comportamento de cache no edge. `"honor"` usa os cabeçalhos de TTL da origem; `"override"` utiliza o campo `max_age` em vez disso. |
  | `modules.edge_cache.max_age` | TTL (em segundos) para o cache do edge ao substituir os cabeçalhos de TTL da origem. |
  | `modules.edge_cache.stale_cache.enabled` | Habilita o [stale cache](/pt-br/documentacao/produtos/build/applications/cache-settings/#stale-cache) para servir conteúdo expirado temporariamente enquanto busca conteúdo atualizado na origem. |
  | `modules.edge_cache.large_file_cache.enabled` | Habilita a [Otimização de arquivos grandes](/pt-br/documentacao/produtos/build/applications/cache-settings/#large-file-optimization) ao armazenar arquivos grandes em fragmentos. |
  | `modules.edge_cache.large_file_cache.offset` | Define o tamanho do fragmento (em kilobytes) para o cache de arquivos grandes. O valor padrão é `1024`. |
  | `modules.tiered_cache.topology` | Define a topologia usada no Cache: `"near-edge"` ou `"near-origin"` (quando disponível). |
  | `modules.application_accelerator.cache_vary_by_method` | Lista de métodos HTTP (por exemplo, `["post", "options"]`) que devem variar a cache key. |
  | `modules.application_accelerator.cache_vary_by_querystring.behavior` | Define como as query strings afetam a variação do cache. As opções são `"ignore"`, `"whitelist"` ou `"blacklist"`. |
  | `modules.application_accelerator.cache_vary_by_querystring.fields` | Lista de campos de query string permitidos ou bloqueados ao variar o cache, dependendo do comportamento definido. |
  | `modules.application_accelerator.cache_vary_by_querystring.sort_enabled` | Habilita a ordenação dos parâmetros de query string antes de calcular as cache keys. |
  | `modules.application_accelerator.cache_vary_by_cookies.behavior` | Define como os cookies afetam a variação do cache. As opções são `"ignore"`, `"whitelist"` ou `"blacklist"`. |
  | `modules.application_accelerator.cache_vary_by_cookies.cookie_names` | Lista dos nomes de cookies usados para variar o cache. |
  | `modules.application_accelerator.cache_vary_by_devices.behavior` | Define como os grupos de dispositivos afetam a variação do cache. As opções são `"ignore"`, `"whitelist"` ou `"blacklist"`. |
  | `modules.application_accelerator.cache_vary_by_devices.device_group` | Lista dos IDs de grupos de dispositivos usados para variar o conteúdo em cache de acordo com o dispositivo do usuário. |

6. Você receberá uma resposta semelhante a esta:

```json
{
    "status": "pending",
    "data": {
        "id": <cache_settings_id>,
        "name": "/cache O60 O13660 Wcity Wcookie_name Wdg POST OPTIONS SLICE",
        "browser_cache": {
        "behavior": "override",
        "max_age": 60
    },
    "modules": {
        "edge_cache": {
        "behavior": "override",
        "max_age": 13660,
        "stale_cache": {
            "enabled": false
        },
        "large_file_cache": {
            "enabled": true,
            "offset": 1024
        }
        },
        "application_accelerator": {
        "cache_vary_by_method": [
            "post",
            "options"
        ],
        "cache_vary_by_querystring": {
            "behavior": "whitelist",
            "fields": ["city"
            ],
            "sort_enabled": false
        },
        "cache_vary_by_cookies": {
            "behavior": "whitelist",
            "cookie_names": [
            "cookie_name"
            ]
        },
        "cache_vary_by_devices": {
            "behavior": "whitelist",
            "device_group": [
            <device_group_id>
            ]
        }
        }
    }
  }
}
```

7. Execute a seguinte requisição `POST` em seu terminal, substituindo `[TOKEN VALUE]` pelo seu [personal token](/pt-br/documentacao/produtos/guias/personal-tokens/), a variável `<application_id>` pelo [ID da sua application](/pt-br/documentacao/produtos/guias/build/definir-configuracoes-principais/), e a variável `<cache_setting_id>` pelo ID da configuração de cache recebido na resposta:

```bash
curl --location 'https://api.azionapi.net/v4/edge_application/applications/<application_id>/request_rules' \
--header 'Accept: application/json;' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token [TOKEN VALUE]' \
--data '{
    "name": "Set cache setting /cache",
    "behaviors": [
        {
            "name": "set_cache_policy",
            "target": "<cache_setting_id>"
        }
    ],
    "criteria": [
        [
            {
                "variable": "${uri}",
                "operator": "is_equal",
                "conditional": "if",
                "argument": "/cache"
            }
        ]
    ]
}'
```

8. Você receberá uma resposta com os dados atualizados.
9. Aguarde alguns minutos para que as alterações se propaguem.

Para verificar como seu conteúdo está sendo armazenado em cache, você pode [verificar os indicadores de cache da aplicação usando o Modheader para Google Chrome](/pt-br/documentacao/produtos/guias/verificar-tempo-de-cache-da-pagina/).

:::tip
Confira a [documentação da API da Azion](https://api.azion.com/) e a [especificação OpenAPI](https://github.com/aziontech/azionapi-openapi/) para saber mais sobre todos os recursos disponíveis via API.
:::
</Fragment>

</Tabs>

---