# Cache settings Um cache setting é um objeto em uma aplicação que diz ao [Cache](/pt-br/documentacao/plataforma/applications/#cache) como armazenar e entregar uma resposta. Ele carrega o TTL de browser, o TTL e o comportamento de cache, o stale cache, o Large File Optimization, o [Tiered Cache](/pt-br/documentacao/plataforma/applications/cache/tiered-cache/) e as regras de variação de cache. Uma regra do [Rules Engine](/pt-br/documentacao/plataforma/applications/rules-engine/) com o behavior [Set Cache Policy](/pt-br/documentacao/plataforma/applications/rules-engine/#set-cache-policy) aplica o cache setting às requisições que ela casa. Enquanto nenhuma regra o nomear, um cache setting não faz nada. Para criar um, consulte [Crie um cache setting](/pt-br/documentacao/guias/performance-e-confiabilidade/cache-e-purge/ajustar-cache-settings/). --- ## Interfaces Seis interfaces escrevem o mesmo objeto. As tabelas desta página nomeiam o controle do Console, o campo da API e a flag da CLI de cada campo. | Interface | Criar | Ler, atualizar, excluir | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Azion Console](https://console.azion.com/) | A aba **Cache Settings** de uma aplicação em [Applications](/pt-br/documentacao/plataforma/applications/) e, em seguida, **+ Cache**, que abre o drawer **Create Cache Settings** | A mesma aba lista cada setting com seu **Name**, **ID**, **Browser Cache** e **Cache** | | [Azion API v4](/pt-br/documentacao/devtools/api/) | `POST /v4/workspace/applications/{application_id}/cache_settings` | `GET`, `PATCH` e `DELETE /v4/workspace/applications/{application_id}/cache_settings/{cache_setting_id}`; `GET /v4/workspace/applications/{application_id}/cache_settings` lista todos | | Azion CLI | [`azion create cache-setting`](/pt-br/documentacao/devtools/cli/recursos/) | [`azion describe cache-setting`](/pt-br/documentacao/devtools/cli/recursos/), [`azion list cache-setting`](/pt-br/documentacao/devtools/cli/recursos/), [`azion update cache-setting`](/pt-br/documentacao/devtools/cli/recursos/), [`azion delete cache-setting`](/pt-br/documentacao/devtools/cli/recursos/) | | `azion.config.js` | Uma entrada do array `cache`, do tipo `AzionCache` | A mesma entrada | | [Azion Lib](/pt-br/documentacao/devtools/azion-lib/application/) | `createCacheSetting`, de `azion/applications` | `getCacheSetting`, `getCacheSettings`, `updateCacheSetting` e `deleteCacheSetting`, de `azion/applications` | | [Terraform](/pt-br/documentacao/devtools/terraform/applications/) | O recurso `azion_application_cache_setting`, cuja página documenta `application_id` e `name` | O mesmo recurso | A API autentica com um personal token no header `Authorization: Token `. Para mais informações, consulte [Personal tokens](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/). Uma entrada `AzionCache` carrega `name`, `stale`, `queryStringSort`, `tieredCache`, `methods`, `browser.maxAgeSeconds`, `edge.maxAgeSeconds`, `cacheByCookie` e `cacheByQueryString`. --- ## Geral A seção **General** do drawer carrega o nome. A API exige `name` e nada mais. | Controle do Console | Campo da API | Tipo | Valores | Padrão | Flag da CLI | | ------------------- | ------------ | ------ | ------------------ | ----------------------- | ----------- | | **Name** | `name` | string | 1 a 250 caracteres | obrigatório, sem padrão | `--name` | --- ## Browser Cache A seção **Browser Cache** define o que o browser recebe instrução de guardar, pelo objeto `browser_cache`. | Controle do Console | Campo da API | Tipo | Valores | Padrão | Flag da CLI | | -------------------------------------------- | ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------- | ------- | -------------------------- | | Radios de **Browser Cache** | `browser_cache.behavior` | enum | *Honor cache policies* (`honor`), *Override cache settings* (`override`), *No cache* (`no-cache`) | `honor` | `--browser-cache-behavior` | | O campo de TTL sob *Override cache settings* | `browser_cache.max_age` | integer, segundos | 0 a 31.536.000 | `0` | `--browser-cache-max-age` | *Honor cache policies* mantém os headers `Cache-Control` e `Expires` enviados pela origem e os repassa ao browser. *Override cache settings* substitui esses headers pelo TTL em `browser_cache.max_age`. Para *No cache*, o Console diz: "Disable browser caching to ensure content is always fetched directly from the server". No `azion update cache-setting`, a flag de `browser_cache.behavior` é `--browser-cache-settings`. --- ## Cache A seção **Cache** define por quanto tempo a Azion mantém a cópia e o que faz com ela, pelo objeto `modules.cache`. | Controle do Console | Campo da API | Tipo | Valores | Padrão | Flag da CLI | | ---------------------------- | ---------------------------------------- | ----------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Radios de **Cache Behavior** | `modules.cache.behavior` | enum | *Honor cache policies* (`honor`), *Override cache behavior* (`override`) | `honor` (API, CLI); *Override cache behavior* pré-selecionado no Console | apenas `--file` | | **Max Age** | `modules.cache.max_age` | integer, segundos | 0 a 31.536.000 | `60` (API, CLI, Console) | apenas `--file` | | **Stale cache** | `modules.cache.stale_cache.enabled` | boolean | `true`, `false` | `false` (API, CLI); ativado no Console | apenas `--file` | | **Large file optimization** | `modules.cache.large_file_cache.enabled` | boolean | `true`, `false` | `false` (API, CLI); desativado no Console | apenas `--file` | | **Offset (KB)** | `modules.cache.large_file_cache.offset` | integer, kB | `1024`, fixo | `1024` | apenas `--file` | | **Tiered Cache** | `modules.cache.tiered_cache.enabled` | boolean | `true`, `false` | `false` quando nenhum objeto `tiered_cache` é enviado; `true` dentro de um objeto `tiered_cache` que o omite; desativado no Console | `--tiered-caching-enabled` sozinho falha com o erro `21001`; use `--file` | | **Tiered Cache Region** | `modules.cache.tiered_cache.topology` | enum | `nearest-region`, `br-east-1`, `us-east-1` | nenhum | apenas `--file` | *Honor cache policies* mantém os headers `Cache-Control` e `Expires` enviados pela origem; *Override cache behavior* os substitui por **Max Age**. **Stale cache** permite que a Azion entregue uma cópia expirada quando a origem falha. **Large file optimization** armazena um objeto grande em fragmentos de 1.024 kB. **Tiered Cache** adiciona uma segunda camada de cache entre o cache da Azion e a origem. Para saber como cada um se comporta em uma requisição, consulte [Expiração e atualização](/pt-br/documentacao/plataforma/applications/cache/expiracao-e-atualizacao/). > **nota** > > Duas restrições se aplicam a esses valores. Um **Max Age** abaixo de 60 segundos exige o módulo [Application Accelerator](/pt-br/documentacao/plataforma/applications/#application-accelerator) na aplicação; sem ele, a API rejeita o cache setting com o erro `21021`. O Tiered Cache exige *Override cache behavior*; com `honor`, a API rejeita o cache setting com o erro `21001`. --- ## Application Accelerator Os quatro controles **Cache vary by** da seção **Application Accelerator** escrevem o objeto `modules.application_accelerator`. Cada campo dele exige o módulo [Application Accelerator](/pt-br/documentacao/plataforma/applications/#application-accelerator) na aplicação, ou a API retorna o erro `21013`. Os campos de query string e de cookie configuram a **Advanced Cache Key**; os campos de dispositivo usam os grupos definidos em [Device Groups](/pt-br/documentacao/plataforma/applications/device-groups/). Para saber o que cada behavior faz com a cache key, consulte [Configurações do Application Accelerator](/pt-br/documentacao/plataforma/applications/application-accelerator/configuracoes/). | Controle do Console | Campo da API | Tipo | Valores | Padrão | Flag da CLI | | ------------------------------------------------------ | ---------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------- | | **Cache vary by Method** > **POST**, **OPTIONS** | `cache_vary_by_method` | array de enum, no máximo 2 valores | `post`, `options` | `[]` | `--enable-caching-for-options` para `options`; `--file` para `post` | | **Cache vary by Query String** > **Behavior** | `cache_vary_by_querystring.behavior` | enum | *Ignore* (`ignore`), *All* (`all`), *Allowlist* (`allowlist`), *Denylist* (`denylist`) | `ignore` | `--cache-by-query-string` | | A lista de campos sob **Cache vary by Query String** | `cache_vary_by_querystring.fields` | array de string | nomes de argumentos de query string | `[]` | `--query-string-fields` | | **Cache vary by Query String** > **Sort** | `cache_vary_by_querystring.sort_enabled` | boolean | `true`, `false` | `false` | apenas `--file` | | **Cache vary by Cookies** > **Behavior** | `cache_vary_by_cookies.behavior` | enum | *Ignore* (`ignore`), *All* (`all`), *Allowlist* (`allowlist`), *Denylist* (`denylist`) | `ignore` | `--cache-by-cookies` | | A lista de cookies sob **Cache vary by Cookies** | `cache_vary_by_cookies.cookie_names` | array de string | nomes de cookies | `[]` | `--cookie-names` | | **Cache vary by Devices** > **Behavior** | `cache_vary_by_devices.behavior` | enum | *Ignore* (`ignore`), *Allowlist* (`allowlist`) | `ignore` | apenas `--file` | | A lista de device groups sob **Cache vary by Devices** | `cache_vary_by_devices.device_group` | array de integer | ids de device group | `[]` | apenas `--file` | *Ignore* não varia a key por nenhum dos valores, e *All* varia por todos os valores que chegam. *Allowlist* varia pelos valores nomeados, e *Denylist* por todos os valores exceto os nomeados. *Allowlist* e *Denylist* na query string exigem pelo menos um campo, ou a API retorna o erro `21018`. Para os passos no Console que configuram esses controles, consulte [Configure a Advanced Cache Key para uma aplicação](/pt-br/documentacao/guias/performance-e-confiabilidade/cache-e-purge/advanced-cache-key/). --- ## Corpo da requisição O corpo abaixo cria um cache setting completo pelo `POST /v4/workspace/applications/{application_id}/cache_settings`: ```json { "name": "static-assets", "browser_cache": { "behavior": "override", "max_age": 86400 }, "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" } } } } ``` A API responde com HTTP `201`, `state` igual a `executed` e o novo objeto com seu `id` em `data`: ```json {"state":"executed","data":{"id":123456,"name":"static-assets",...,"created_at":"2026-01-01T12:00:00.577248Z"}} ``` O endpoint de listagem envolve os settings de uma aplicação em um envelope de página: ```json {"count":2,"total_pages":1,"page":1,"page_size":10,"next":null,"previous":null,"results":[...]} ``` A CLI escreve pela linha de comando os campos cobertos por suas flags: ```bash azion create cache-setting \ --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" ``` O comando imprime o id do novo cache setting: ```text Created Cache Settings configuration with ID 123457 ``` As flags cobrem o browser cache, a variação por query string e por cookie e o cache de `OPTIONS`. Cada um dos outros campos, incluindo **Max Age**, o comportamento de cache, o stale cache, o Large File Optimization e o Tiered Cache, é definido pelo `--file` com o corpo JSON. --- ## Erros A API responde cada requisição abaixo com HTTP `400`. O corpo carrega o código e o título, e um erro de campo também aponta o campo. | Código | Título | Causa | O que fazer | | ------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `21021` | `Edge Cache Max Age Lower Than The Minimum Allowed By Application's Application Accelerator Module` | `modules.cache.max_age` está abaixo de 60 em uma aplicação sem o Application Accelerator; `meta.min_value` é `60`, e o detalhe diz `The value is lower than the minimum required when the Application's Application Accelerator Module is disabled.` e aponta `/data/modules/cache/max_age`. | Defina **Max Age** como 60 ou mais, ou ative o Application Accelerator na aplicação. | | `21020` | `Edge Cache Max Age Lower Than The Minimum Allowed By The Tiered Cache Module` | `modules.cache.max_age` está abaixo de 3 com `tiered_cache.enabled` igual a `true`; `meta.min_value` é `3`, e o detalhe diz `The value is lower than the minimum required by the Tiered Cache Module.` e aponta `/data/modules/cache/max_age`. | Defina **Max Age** como 3 ou mais, ou desative o Tiered Cache. | | `21001` | `It's Not Possible To Use This Edge Cache Behavior.` | `tiered_cache.enabled` é `true` enquanto `modules.cache.behavior` é `honor`; o detalhe diz `It's not possible to use this edge cache behavior while using Tiered Cache.` e aponta `/data/modules/cache/behavior`. O `azion create cache-setting --tiered-caching-enabled true` envia essa combinação, porque nenhuma flag define o comportamento. | Defina `modules.cache.behavior` como `override`; pela CLI, envie o corpo com `--file`. | | `21013` | `This Configuration Requires The Edge Application's Application Accelerator Module` | Um campo de `modules.application_accelerator` é enviado para uma aplicação sem o módulo; o detalhe diz `To use this value, you must first enable the Application Accelerator module in Edge Application's Main Settings.` e aponta o campo, como `/data/modules/application_accelerator/cache_vary_by_method`. | Ative o **Application Accelerator** em **Main Settings** > **Modules**, ou remova o campo. | | `21018` | `Query String Fields Are Required For Current Cache Vary By Query String Behavior` | `cache_vary_by_querystring.behavior` é `allowlist` ou `denylist` e `fields` está vazio; o detalhe diz `The current behavior requires you to configure query string fields.` e aponta `/data/modules/application_accelerator/cache_vary_by_querystring/fields`. | Liste pelo menos um campo, ou defina o behavior como `ignore` ou `all`. | | `21014` | `Cannot Delete Cache Setting` | Um `DELETE` atinge um cache setting que o behavior **Set Cache Policy** de uma regra ainda nomeia; o detalhe diz `This Cache Setting cannot be deleted because it is being used.` e aponta `/data`. | Altere ou exclua essa regra e repita o `DELETE`. | | `10068` | `Max Value` | `modules.cache.max_age` ou `browser_cache.max_age` está acima de 31.536.000, com o detalhe `Ensure this value is less than or equal to 31536000.`; ou `large_file_cache.offset` está acima de 1.024, com o detalhe `Ensure this value is less than or equal to 1024.` | Reduza o valor até o limite que o detalhe nomeia. | | `10046` | `Max Length` | `name` tem mais de 250 caracteres; o detalhe diz `Ensure this field has no more than 250 characters.` | Reduza o nome para 250 caracteres ou menos. | | `10039` | `Invalid Choice` | `tiered_cache.topology` não é `nearest-region`, `br-east-1` nem `us-east-1`. | Envie um dos três valores. | --- ## Limites Os limites abaixo se aplicam a um cache setting. Cada linha nomeia a resposta da API além do valor. | Valor | Limite | Além do limite | | ----------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | | `name` | 1 a 250 caracteres | HTTP `400`, erro `10046` | | `modules.cache.max_age` | 0 a 31.536.000 segundos | HTTP `400`, erro `10068` acima do máximo | | `modules.cache.max_age` sem o Application Accelerator | pelo menos 60 segundos | HTTP `400`, erro `21021` | | `modules.cache.max_age` com o Tiered Cache ativo | pelo menos 3 segundos | HTTP `400`, erro `21020` | | `browser_cache.max_age` | 0 a 31.536.000 segundos | HTTP `400`, erro `10068` | | `cache_vary_by_method` | no máximo 2 valores | A especificação limita o array a 2 itens; nenhuma string de erro é documentada | | `large_file_cache.offset` | 1.024 kB, fixo | HTTP `400`, erro `10068` acima de 1.024. Para alterar o tamanho do fragmento, entre em contato com o time de Vendas | Para os limites de purge e as quantidades incluídas em cada plano, consulte [Limites de Applications](/pt-br/documentacao/plataforma/applications/limites/#cache). --- ## Recursos relacionados - [Crie um cache setting](/pt-br/documentacao/guias/performance-e-confiabilidade/cache-e-purge/ajustar-cache-settings.md): Os passos no Console, na API e na CLI que criam um cache setting e o aplicam com uma regra. - [Expiração e atualização](/pt-br/documentacao/plataforma/applications/cache/expiracao-e-atualizacao.md): O que o TTL, o stale cache, o Large File Optimization e o Tiered Cache fazem em uma requisição. - [Cache keys](/pt-br/documentacao/plataforma/applications/cache/cache-keys.md): A key a que cada variação destas tabelas é acrescentada, e os headers de debug que a mostram. - [Configure políticas de cache para uma aplicação](/pt-br/documentacao/guias/performance-e-confiabilidade/cache-e-purge/cache-settings.md): Os passos no Console que definem um TTL para um path e ignoram o cache em outro.