View a markdown version of this page

Invalidar conteúdo por tags de cache - Amazon CloudFront
Como funciona a invalidação por tagRequisitos de formato das tagsConfigurar uma distribuição para invalidações por tagCriar invalidações por tagVerificar o status da invalidaçãoConsiderações importantesExemplos de casos de uso

Invalidar conteúdo por tags de cache

O Amazon CloudFront oferece suporte a invalidações por tag, permitindo invalidar objetos armazenados em cache com base em tags semânticas, em vez de caminhos de URL. Isso proporciona controle flexível sobre a invalidação de cache sem exigir que a estrutura de URLs corresponda à estratégia de invalidação.

Como funciona a invalidação por tag

  1. Configure a distribuição: adicione um CacheTagConfig à distribuição especificando o nome do cabeçalho HTTP usado pela origem para retornar tags de cache.

  2. Adicione tags a objetos na origem: ao retornar um objeto que deve ser armazenado em cache com tags, configure a origem para incluir o cabeçalho especificado nas respostas HTTP com valores de tags separados por vírgula.

    HTTP/1.1 200 OK
Content-Type: text/html
x-amz-meta-cache-tag: product:electronics, category:tv, brand:example
Cache-Control: max-age=3600
    nota

    Para origens do S3, é possível anexar tags de cache aos objetos do S3 como metadados. É possível adicionar uma entrada de metadados com uma chave de sua escolha (exemplo: cache-tag) e uma lista de tags separadas por vírgula como valor (exemplo: product:electronics, category:tv, brand:example).

    O S3 expõe os metadados do objeto como cabeçalhos de resposta com o prefixo x-amz-meta-<Key>, portanto, uma chave de metadados de cache-tag seria retornada como um cabeçalho x-amz-meta-cache-tag. É possível definir o HeaderName em CacheTagConfig como x-amz-meta-cache-tag para permitir o envio de invalidações para essas tags.

    nota

    Como alternativa, é possível anexar uma função do Lambda@Edge de resposta da origem ao comportamento de cache para adicionar cabeçalhos de tags de cache. Ao usar Lambda@Edge, o nome do cabeçalho não precisa seguir o formato x-amz-meta-<Key>.

  3. Invalidar por tag: use a API CreateInvalidation com o prefixo # para invalidar todos os objetos armazenados em cache com a tag especificada.

    aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#product:electronics"

    Isso invalida TODOS os objetos armazenados em cache que contêm a tag product:electronics, independentemente do caminho da URL.

Requisitos de formato das tags

Valor do cabeçalho de resposta da origem:

  • As tags são separadas por vírgula no valor do cabeçalho.

  • Espaços no início e no fim de cada tag são removidos.

  • Tanto tag1,tag2,tag3 quanto tag1, tag2, tag3 são válidos e equivalentes.

Valores individuais de tags:

  • Caracteres ASCII visíveis (33 – 126).

  • Sem caracteres de controle, espaços ou vírgulas.

  • Não diferencia maiúsculas de minúsculas.

  • Máximo de 256 caracteres por tag.

  • Máximo de 50 tags por objeto (tags adicionais são ignoradas).

Configurar uma distribuição para invalidações por tag

Para habilitar invalidações por tag, adicione um CacheTagConfig à configuração da distribuição:

aws cloudfront create-distribution \
  --distribution-config '{
    "CallerReference": "my-distribution",
    "CacheTagConfig": {
      "HeaderName": "x-amz-meta-cache-tag"
    },
    "DefaultCacheBehavior": {
      "TargetOriginId": "myOrigin",
      "ViewerProtocolPolicy": "redirect-to-https",
      "CachePolicyId": "658327ea-f89d-4fab-a63d-7e88639e58f6"
    },
    "Origins": { ... },
    "Enabled": true,
    "Comment": "Distribution with tag support"
  }'

Criar invalidações por tag

Use o prefixo # no parâmetro --paths para especificar tags:

# Invalidate all objects tagged with "user1"
aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#user1"

# Invalidate objects matching any of multiple tags (OR logic)
aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#user1" "#product-category:electronics"

# Mix path and tag invalidations in one batch
aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "/index.html" "#user1" "/images/*" "#product-category:electronics"

Verificar o status da invalidação

Use GetInvalidation para verificar o status. A resposta inclui itens de caminho e de tag:

aws cloudfront get-invalidation \
  --distribution-id distribution_ID \
  --id invalidation_ID

Considerações importantes

  • Adesão obrigatória: a invalidação por tag funciona apenas em distribuições com CacheTagConfig configurado. Distribuições sem essa configuração ignoram cabeçalhos de tags de cache enviados pela origem.

  • Limites de processamento de tags: o CloudFront processa até 50 tags por objeto armazenado em cache. Se uma resposta da origem contiver mais de 50 tags, as tags adicionais além desse limite não serão armazenadas.

  • Alteração do nome do cabeçalho: invalidações por tag são verificadas com base na configuração atual de CacheTagConfig. Se o HeaderName for alterado em CacheTagConfig, as invalidações emitidas para objetos armazenados em cache com tags sob o nome antigo do cabeçalho deixarão de ser avaliadas. Se for necessário alterar o nome do cabeçalho, comece retornando tanto os novos quanto os antigos cabeçalhos de tags de cache com os objetos. Em seguida, emita uma invalidação de caminho (por exemplo, /*) ou invalide as tags existentes antes de alterar o nome do cabeçalho para evitar a entrega de conteúdo desatualizado. Feito isso, você pode parar de enviar o cabeçalho antigo de tags de cache com os objetos.

  • Remoção de CacheTagConfig: ao remover CacheTagConfig de uma distribuição, o CloudFront deixa de extrair tags das respostas da origem. Objetos armazenados em cache com tags existentes continuam sendo entregues normalmente até expirarem ou serem invalidados por caminho.

  • Compatibilidade retroativa: invalidações existentes por caminho e por caractere curinga continuam funcionando sem alterações. As invalidações por tag são complementares: é possível usar ambos os métodos na mesma distribuição.

  • Locatários da distribuição: a invalidação por tag também é compatível com locatários de distribuição por meio da API CreateInvalidationForDistributionTenant.

Exemplos de casos de uso

Exemplo 1: catálogo de produtos de e-commerce

Um site de e-commerce adiciona tags às páginas de produtos armazenadas em cache com produto, categoria e marca:

x-amz-meta-cache-tag: category:electronics, brand:acme, product:12345

Quando a ACME atualiza a identidade visual, é possível invalidar todos os produtos da ACME de uma só vez:

aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#brand:acme"

Exemplo 2: plataforma de conteúdo gerado por usuários

Uma plataforma adiciona tags ao conteúdo armazenado em cache com o ID do usuário proprietário:

x-amz-meta-cache-tag: user:12345, content-type:image

Quando um usuário encerra a conta, é possível invalidar todo o conteúdo dele após removê-lo da origem:

aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#user:12345"

Exemplo 3: versionamento de conteúdo

Um CMS adiciona tags ao conteúdo com identificadores de versão:

x-amz-meta-cache-tag: version:v2, template:homepage

Ao implantar uma nova versão, invalide todo o conteúdo da v2:

aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#version:v2"