Configure o comportamento de colocação em cache

A RFC de multimédia publica conteúdo o mais próximo possível dos utilizadores através da infraestrutura global de armazenamento em cache na extremidade da rede da Google para armazenar conteúdo em cache e reduzir a carga na infraestrutura de origem.

Pode controlar como o conteúdo é colocado em cache para cada trajeto. Isto permite-lhe otimizar o comportamento com base no tipo de conteúdo, nos atributos do pedido do cliente e nos seus requisitos de atualização.

Capacidade de colocação em cache

As secções seguintes descrevem as respostas que a RFC de conteúdo multimédia armazena em cache e como melhorar o descarregamento da cache.

Comportamento de colocação em cache predefinido

Por predefinição, as seguintes definições relacionadas com a cache aplicam-se a cada serviço de cache na extremidade:

  • Modo de cache predefinido de CACHE_ALL_STATIC:

    • Respeita as diretivas de cache de origem, como Cache-Control ou Expires, até um TTL máximo configurável.
    • Coloca automaticamente em cache tipos de suportes estáticos com um TTL predefinido de 3600 s, se não estiverem presentes diretivas de cache de origem.
    • Coloca em cache os códigos de estado HTTP 200, 204 e 206 (a colocação em cache negativa não está ativada).

  • Não coloca em cache respostas que tenham diretivas de controlo de cache no-store ou private, ou que não sejam colocáveis em cache.

As respostas que não são conteúdo estático ou que não têm diretivas de cache válidas não são colocadas em cache, a menos que a colocação em cache esteja explicitamente configurada. Para saber como substituir o comportamento predefinido, consulte a documentação sobre os modos de cache .

O comportamento predefinido é equivalente ao seguinte cdnPolicy. As rotas sem um cdnPolicy explícito configurado comportam-se como se tivessem a seguinte configuração:

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 3600s
  cacheKeyPolicy:
    includeProtocol: false
    excludeHost: false
    excludeQueryString: false
  signedRequestMode: DISABLED
  negativeCaching: false

Respostas compatíveis com a cache

Uma resposta armazenável em cache é uma resposta HTTP que a RFC pode armazenar e obter rapidamente, o que permite tempos de carregamento mais rápidos. Nem todas as respostas HTTP são armazenáveis em cache.

Pode configurar modos de cache para cada rota para substituir este comportamento (por exemplo, usando o modo de cache CACHE_ALL_STATIC para colocar em cache tipos de multimédia comuns) mesmo que a origem não defina uma diretiva de controlo da cache na resposta.

Os pedidos e as respostas que cumprem os critérios definidos nas respostas não armazenáveis em cache substituem a capacidade de armazenamento em cache.

A tabela seguinte descreve os requisitos para colocar em cache respostas HTTP específicas. Ambas as respostas GET e HEAD têm de cumprir estes requisitos.

Atributo HTTP Requisitos
Código de estado O código de estado da resposta tem de ser um dos seguintes: 200, 203, 204, 206, 300, 301, 302, 307, 308, 400, 403, 404, 405, 410, 451, 500, 501, 502, 503 ou 504.
Métodos HTTP GET e HEAD
Cabeçalhos do pedido A maioria das diretivas de pedidos de colocação em cache é ignorada. Para mais informações, consulte as diretivas de controlo da cache.
Cabeçalhos das respostas

Contém uma diretiva de colocação em cache HTTP válida, como Cache-Control: max-age=3600, public.

Tem um modo de cache que armazena esse conteúdo em cache ou tem um cabeçalho Expires com uma data no futuro.
Tamanho da resposta Até 100 GiB.

O cabeçalho HTTP Age é definido com base no momento em que a RFC de conteúdo multimédia colocou a resposta em cache pela primeira vez e, normalmente, representa os segundos desde que o objeto foi colocado em cache numa localização de proteção de origem. Se a sua origem gerar um cabeçalho de resposta Age, use o modo de cache FORCE_CACHE_ALL para evitar revalidações quando a idade exceder o TTL da cache.

Para mais informações sobre como a RFC interpreta as diretivas de colocação em cache HTTP, consulte o artigo Diretivas de controlo da cache.

Requisitos de origem

Para permitir que a RFC de multimédia na nuvem armazene em cache respostas de origem superiores a 1 MiB, uma origem tem de incluir o seguinte nos cabeçalhos das respostas para pedidos HEAD e GET, salvo especificação em contrário:

  • Um cabeçalho de resposta HTTP Last-Modified ou ETag (um validador).
  • Um cabeçalho HTTP Date válido.
  • Um cabeçalho Content-Length válido.
  • O cabeçalho da resposta Content-Range, em resposta a um pedido Range GET. O cabeçalho Content-Range tem de ter um valor válido no formato bytes x-y/z (em que z é o tamanho do objeto).

O protocolo de origem predefinido é HTTP/2. Se as suas origens apenas suportarem HTTP/1.1, pode definir o campo de protocolo explicitamente para cada origem.

Respostas não armazenáveis em cache

A tabela seguinte detalha os atributos de pedido e resposta que impedem que uma resposta seja colocada em cache. As respostas que podem ser colocadas em cache, mas que correspondem a critérios "não colocáveis em cache", não são colocadas em cache.

Atributo HTTP Requisito
Código de estado

Um código de estado diferente dos definidos como armazenáveis em cache, como HTTP 401, HTTP 412 ou HTTP 505.

Normalmente, estes códigos de estado são representativos de problemas orientados para o cliente e não do estado de origem. O armazenamento em cache dessas respostas pode originar cenários de "cache poisoning" em que uma resposta "má" acionada pelo utilizador é armazenada em cache para todos os utilizadores.
Cabeçalhos do pedido

Para pedidos com um cabeçalho Authorization, as respostas têm de incluir uma diretiva public Cache-Control para serem colocadas em cache.

Uma diretiva no-store no pedido faz com que a resposta não seja colocada em cache. Para mais informações, consulte as diretivas de controlo da cache.
Cabeçalhos das respostas

Tem um cabeçalho Set-Cookie.

Tem um cabeçalho Vary diferente de Accept, Accept-Encoding, Origin, X-Origin, X-Goog-Allowed-Resources, Sec-Fetch-Dest, Sec-Fetch-Mode ou Sec-Fetch-Site.

No modo CACHE_ALL_STATIC ou USE_ORIGIN_HEADERS, tem uma diretiva de controlo de cache no-store ou private.
Tamanho da resposta Superior a 100 GiB.

Estas regras aplicam-se além do modo de cache configurado. Em concreto:

  • Com o modo de cache CACHE_ALL_STATIC configurado, apenas as respostas consideradas conteúdo estático ou respostas com diretivas de cache válidas nos respetivos cabeçalhos de resposta são colocadas em cache. Outras respostas são enviadas através de proxy tal como estão.
  • O modo de cache FORCE_CACHE_ALL coloca todas as respostas em cache incondicionalmente, sujeito aos requisitos de não colocação em cache indicados anteriormente.
  • O modo de cache USE_ORIGIN_HEADERS requer que as respostas definam diretivas de cache válidas nos respetivos cabeçalhos de resposta, além de serem um código de estado armazenável em cache.

Notas:

  • As respostas que não estão em cache não têm as respetivas diretivas de controlo de cache nem outros cabeçalhos alterados e são encaminhadas através de proxy tal como estão.
  • As respostas podem ter os cabeçalhos Cache-Control e Expires reduzidos a um único campo Cache-Control. Por exemplo, uma resposta com Cache-Control: public e Cache-Control: max-age=100 em linhas separadas seria reduzida a Cache-Control: public,max-age=100.
  • As respostas não memorizáveis em cache (respostas que nunca seriam memorizadas em cache) não são contabilizadas do ponto de vista da faturação.Cache Egress

Usar modos de cache

Os modos de cache permitem-lhe configurar quando a RFC de multimédia deve respeitar as diretivas de cache de origem, colocar em cache tipos de multimédia estáticos e colocar em cache todas as respostas da origem, independentemente das diretivas definidas.

Os modos de cache são configurados ao nível da rota e, quando combinados com substituições de TTL, permitem-lhe configurar o comportamento da cache por anfitrião, caminho, parâmetros de consulta e cabeçalhos (quaisquer parâmetros de pedido correspondentes).

  • Por predefinição, a RFC usa o CACHE_ALL_STATICmodo de cache, que coloca automaticamente em cache os tipos de multimédia estáticos comuns durante 1 hora (3600 segundos), ao mesmo tempo que dá prioridade a quaisquer diretivas de cache especificadas pela origem para respostas colocáveis em cache.
  • Pode aumentar ou diminuir o TTL da cache aplicado às respostas sem um TTL da cache definido explicitamente (uma diretiva max-age ou s-maxage) definindo o campo cdnPolicy.defaultTtl numa rota.
  • Para evitar o armazenamento em cache de respostas sem êxito durante mais tempo do que o pretendido, os códigos de estado não 2xx (sem êxito) não são armazenados em cache de acordo com o respetivo Content-Type (tipo MIME) e não têm o TTL predefinido aplicado.

Os modos de cache disponíveis, que são definidos no cdnPolicy.cacheMode de cada rota, são apresentados na tabela seguinte.

Modo de cache Comportamento
USE_ORIGIN_HEADERS Requer que as respostas de origem definam diretivas de cache válidas e cabeçalhos de colocação em cache válidos. Para ver uma lista completa de requisitos, consulte o artigo Respostas memorizáveis em cache.
CACHE_ALL_STATIC

Coloca automaticamente em cache as respostas bem-sucedidas com conteúdo estático, a menos que tenham uma diretiva no-store ou private. As diretivas de colocação em cache válidas da origem são priorizadas.

O conteúdo estático inclui vídeo, áudio, imagens e recursos Web comuns, conforme definido pelo tipo MIME no cabeçalho da resposta Content-Type.
FORCE_CACHE_ALL

Coloca em cache incondicionalmente as respostas bem-sucedidas, substituindo quaisquer diretivas de cache definidas pela origem.

Certifique-se de que não publica conteúdo privado por utilizador (como HTML dinâmico ou respostas da API) com este modo configurado.
BYPASS_CACHE

Qualquer pedido que corresponda a uma rota com este modo de cache configurado ignora a cache, mesmo que exista um objeto em cache que corresponda a essa chave de cache.

Recomendamos que use esta opção apenas para depuração, uma vez que a CDN de multimédia foi concebida como uma infraestrutura de cache à escala global e não como um proxy de uso geral.

Tipos MIME de conteúdo estático

O modo de cache CACHE_ALL_STATIC permite que a CDN de multimédia armazene automaticamente em cache conteúdo estático comum, como vídeo, áudio, imagens e recursos Web comuns, com base no tipo MIME devolvido no cabeçalho de resposta HTTP Content-Type. No entanto, independentemente do tipo de suporte, a RFC dá prioridade a quaisquer cabeçalhos Cache-Control ou Expires explícitos na resposta de origem.

A tabela seguinte lista os tipos MIME que podem ser colocados automaticamente em cache com o modo de cache CACHE_ALL_STATIC.

As respostas não são automaticamente colocadas em cache se não tiverem um cabeçalho de resposta com um valor que corresponda aos seguintes valores.Content-Type Tem de garantir que a resposta define uma diretiva de cache válida ou tem de usar o modo de cache FORCE_CACHE_ALL para colocar em cache incondicionalmente as respostas.

Categoria Tipos MIME
Recursos Web text/css text/ecmascript text/javascript application/javascript
Tipos de letra Qualquer Content-Type que corresponda a font/*
Imagens Qualquer Content-Type que corresponda a image/*
Vídeos Qualquer Content-Type que corresponda a video/*
Áudio Qualquer Content-Type que corresponda a audio/*
Tipos de documentos formatados application/pdf and application/postscript

Tenha em conta o seguinte:

  • O software do servidor Web da sua origem tem de definir o Content-Type para cada resposta. Muitos servidores Web definem automaticamente o cabeçalho Content-Type, incluindo NGINX, Varnish e Apache.
  • O Cloud Storage define o cabeçalho Content-Type automaticamente no carregamento quando usa a Google Cloud consola ou a CLI gcloud para carregar conteúdo.
  • O Cloud Storage envia sempre um cabeçalho Cache-Control para a RFC de multimédia. Se não for escolhido explicitamente nenhum valor, é enviado um valor predefinido. Como resultado, todas as respostas bem-sucedidas do Cloud Storage são colocadas em cache de acordo com os valores predefinidos do Cloud Storage, a menos que ajuste explicitamente os metadados de controlo da cache para objetos no Cloud Storage ou use o modo FORCE_CACHE_ALL para substituir os valores enviados pelo Cloud Storage.

Se uma resposta for armazenável em cache com base no respetivo tipo MIME, mas tiver uma diretiva de resposta Cache-Control de private ou no-store ou um cabeçalho Set-Cookie, não é armazenada em cache.

Outros tipos de suportes, como HTML (text/html) e JSON (application/json), não são colocados em cache por predefinição. Estes tipos de respostas são normalmente dinâmicos (por utilizador) e também não são adequados para a arquitetura da RFC. Recomendamos a utilização da CDN da nuvem para publicar recursos Web e para colocar em cache as respostas da API.

Configure os TTLs da cache

As substituições do tempo de vida (TTL) permitem-lhe definir valores TTL predefinidos para conteúdo em cache e substituir os valores TTL definidos nas diretivas de controlo de cache max-age e s-maxage (ou cabeçalhos Expires) definidos pelas suas origens.

Os TTLs, quer sejam definidos por substituições ou através de uma diretiva de cache, são otimistas. O conteúdo ao qual se acede raramente ou que é impopular pode ser removido da cache antes de o TTL ser alcançado.

A tabela seguinte mostra três definições de TTL.

Definição Predefinição Mínimo Máximo Descrição Modos de cache aplicáveis
Default TTL 1 hora
(3600 segundos)		 0 segundos 1 ano
(31 536 000 segundos)

O TTL a definir quando a origem não tiver especificado um cabeçalho max-age ou s-maxage.

Se a origem especificar um cabeçalho s-maxage, este é usado em vez do valor TTL predefinido aqui.

Quando usa o FORCE_CACHE_ALL para colocar em cache incondicionalmente todas as respostas, o TTL predefinido é usado para definir o TTL da cache. Todos os outros valores e diretivas são ignorados.

CACHE_ALL_STATIC

FORCE_CACHE_ALL
Max TTL 1 dia
(86400 segundos)		 0 segundos 1 ano
(31 536 000 segundos)		 Para respostas memorizáveis em cache, o TTL máximo permitido. Os valores superiores a este são limitados ao valor de maxTtl. CACHE_ALL_STATIC
Client TTL Não predefinido. 0 segundos 1 dia
(86400 segundos)		 Para respostas memorizáveis em cache, o TTL máximo a permitir na resposta a jusante (orientada para o cliente) se este precisar de ser diferente de outros valores TTL.

CACHE_ALL_STATIC

FORCE_CACHE_ALL

A definição de qualquer valor de TTL para zero (0 segundos) faz com que cada pedido seja revalidado com a origem antes de ser publicada uma resposta e aumenta a carga na origem se a definição for demasiado abrangente.

Quando o modo de cache está definido como Use Origin Headers, não é possível configurar as definições de TTL porque a RFC de multimédia depende da origem para determinar o comportamento.

Notas:

  • O valor do TTL máximo tem de ser sempre superior (ou igual) ao valor do TTL predefinido.
  • O valor do TTL do cliente tem de ser sempre inferior (ou igual) ao valor do TTL máximo.
  • Quando a RFC do Media substitui um valor TTL de origem, o cabeçalho Cache-Control enviado ao cliente também reflete esse valor.
  • Se a origem definir um cabeçalho Expires e a RFC do Media CDN substituir o TTL efetivo (com base na data/hora), o cabeçalho Expires é substituído por um cabeçalho Cache-Control na resposta a jusante ao cliente.

Colocação em cache negativa

O armazenamento em cache negativo define como os códigos de estado HTTP sem êxito (exceto os 2xx) são armazenados em cache pela RFC.

Isto permite-lhe armazenar em cache respostas de erro, como redirecionamentos (HTTP 301 e 308) e respostas não encontradas (HTTP 404), mais perto dos utilizadores, bem como reduzir a carga de origem de forma mais ampla se for improvável que a resposta mude e possa ser armazenada em cache.

Por predefinição, a colocação em cache negativa está desativada. A tabela seguinte mostra os valores predefinidos para cada código de estado quando o armazenamento em cache negativo está ativado e o elemento negativeCachingPolicy não é usado.

Códigos de estado Reason-phrase TTL
HTTP 300 Várias opções 10 minutos
HTTP 301 e HTTP 308 Redirecionamento permanente 10 minutos
HTTP 404 Não encontrado 120 segundos
HTTP 405 Método não encontrado 60 segundos
HTTP 410 Desaparecido 120 segundos
HTTP 451 Indisponível por motivos legais 120 segundos
HTTP 501 Não implementado 60 segundos

O conjunto predefinido de códigos de colocação em cache negativos corresponde aos códigos de estado que podem ser colocados em cache heuristicamente descritos no HTTP RFC 9110, com as seguintes exceções:

  • O código HTTP 414 (URI Too Long) não é suportado para o armazenamento em cache, para evitar o envenenamento da cache.
  • O código HTTP 451 (Indisponível por motivos legais) é suportado para colocação em cache, conforme descrito na RFC 7725 do HTTP.

Se precisar de configurar os seus próprios TTLs por código de estado e substituir o comportamento predefinido, pode configurar um cdnPolicy.negativeCachingPolicy. Isto permite-lhe definir o TTL para qualquer um dos códigos de estado permitidos pela RFC 7231: 300, 301, 302, 307, 308, 400, 403, 404, 405, 410, 451, 500, 501, 502, 503 e 504.

Por exemplo, para definir um TTL curto de 5 segundos para respostas HTTP 404 (Não encontrado) e um TTL de 10 segundos para respostas HTTP 405 (Método não permitido), use a seguinte definição YAML em cada rota aplicável:

cdnPolicy:
  negativeCaching: true
  negativeCachingPolicy:
    "404": 5s
    "405": 10s
  # other status codes to apply TTLs for

Para evitar o envenenamento da cache, não recomendamos a ativação da colocação em cache para o código de estado 400 (Pedido inválido) ou 403 (Proibido). Certifique-se de que o servidor de origem devolve um dos códigos como resultado do exame apenas dos componentes do pedido que estão incluídos na chave da cache. O envenenamento da cache pode ocorrer, por exemplo, quando o servidor de origem responde com uma resposta de erro 403 na ausência de um cabeçalho Authorization correto. Neste caso, o armazenamento em cache da resposta de erro 403 resulta na publicação da resposta de erro 403 pelo Media CDN para todos os pedidos subsequentes até o TTL expirar, mesmo que os pedidos tenham um cabeçalho Authorization correto.

Para desativar o armazenamento em cache negativo:

  • Para desativar o comportamento de colocação em cache negativo predefinido, defina cdnPolicy.negativeCaching: false numa rota. Tenha em atenção que as respostas de origem com diretivas de cache válidas e códigos de estado armazenáveis em cache continuam a ser armazenadas em cache.
  • Para impedir o armazenamento em cache negativo para um código de estado específico, mas continuar a respeitar as diretivas de cache de origem, omita o código de estado (cdnPolicy.negativeCachingPolicy[].code) na sua negativeCachingPolicy definição.
  • Para ignorar explicitamente as diretivas de cache de origem para um código de estado específico, defina cdnPolicy.negativeCachingPolicy[].ttl como 0 (zero) para esse código de estado.

Notas:

  • Quando a opção negativeCaching está ativada num trajeto e uma resposta define diretivas de cache válidas, as diretivas de cache na resposta têm precedência.
  • Se configurar um negativeCachingPolicy explícito e existir um TTL definido para o código de estado fornecido, o TTL definido na política é sempre usado.
  • O valor máximo para um TTL definido por negativeCachingPolicy é de 1800 segundos (30 minutos), mas as diretivas de cache de origem com um TTL mais elevado são respeitadas.
  • Se o modo de cache estiver configurado como FORCE_CACHE_ALL, as diretivas de origem são ignoradas em todos os casos.

Diretivas de controlo de cache

O comportamento da RFC do Media CDN relativamente às diretivas Cache-Control está definido aqui.

Se a diretiva não for aplicável a um pedido ou a uma resposta, como only-if-cached (uma diretiva apenas para o cliente), é marcada a opção "N/A" nessa coluna.

Diretiva Pedido Resposta
no-cache A diretiva de pedido no-cache é ignorada para impedir que os clientes iniciem ou forcem potencialmente a revalidação para a origem.

Uma resposta com no-cache é colocada em cache, mas requer validação com a origem antes de poder ser publicada.

Isto pode ser substituído por rota com o FORCE_CACHE_ALLmodo de cache.
no-store A resposta a um pedido com no-store não é colocada em cache.

Uma resposta com no-store não é colocada em cache.

Isto pode ser substituído por rota com o FORCE_CACHE_ALLmodo de cache.
public N/A

Uma resposta com a diretiva public é colocada em cache se a resposta for considerada colocável em cache como um todo e a resposta também tiver uma diretiva max-age ou s-maxage.

Quando usar os modos de CACHE_ALL_STATIC cache ou FORCE_CACHE_ALL, isto não é necessário.
private N/A

Uma resposta com a diretiva private não é colocada em cache pela CDN de multimédia, mesmo que a resposta seja considerada colocável em cache. Os clientes (como os navegadores) podem continuar a colocar o resultado em cache.

Isto pode ser substituído por rota com o FORCE_CACHE_ALLmodo de cache.

Use no-store para impedir todo o armazenamento em cache de respostas.
max-age=SECONDS A diretiva de pedido max-age é ignorada. É devolvida uma resposta em cache como se este cabeçalho não estivesse incluído no pedido. Uma resposta com a diretiva max-age é colocada em cache até ao SECONDS definido.
s-maxage=SECONDS N/A

Uma resposta com a diretiva s-maxage é colocada em cache até ao SECONDS definido.

Se max-age e s-maxage estiverem presentes, o servidor usa s-maxage.

Tenha em atenção que s-max-age (dois hífens) não é válido para fins de colocação em cache.
min-fresh=SECONDS A diretiva de pedido min-fresh é ignorada. É devolvida uma resposta em cache como se este cabeçalho não estivesse incluído no pedido. N/A
max-stale=SECONDS

A diretiva de pedido max-stale é ignorada.

É devolvida uma resposta em cache como se este cabeçalho não estivesse incluído no pedido.

 N/A
stale-while-revalidate=SECONDS N/A Sem efeito. Isto é transmitido ao cliente na resposta.
stale-if-error=SECONDS A diretiva de pedido stale-if-error é ignorada. É devolvida uma resposta em cache como se este cabeçalho não estivesse incluído no pedido. Sem efeito. Isto é transmitido ao cliente na resposta.
must-revalidate N/A

Uma resposta com must-revalidate é revalidada com o servidor de origem após expirar.
proxy-revalidate N/A

Uma resposta com proxy-revalidate é revalidada com o servidor de origem após expirar.
immutable N/A Sem efeito. Isto é transmitido ao cliente na resposta.
no-transform N/A O CDN de multimédia não aplica transformações.
only-if-cached A diretiva de pedido only-if-cached é ignorada. É devolvida uma resposta em cache como se este cabeçalho não estivesse incluído no pedido. N/A

Sempre que possível, a RFC do CDN de multimédia está em conformidade (HTTP RFC 7234), mas favorece a otimização para a transferência da cache e a minimização do impacto que os clientes podem ter na taxa de acertos e na carga de origem geral.

Para respostas que usam o cabeçalho Expires HTTP/1.1:

  • O valor do cabeçalho Expires tem de ser uma data HTTP válida, conforme definido no RFC 7231
  • Um valor de data no passado, uma data inválida ou um valor de 0 indica que o conteúdo já expirou e requer revalidação.
  • A RFC de CDN de multimédia ignora o cabeçalho Expires se um cabeçalho Cache-Control estiver presente na resposta.

O cabeçalho Pragma HTTP/1.0, se estiver presente numa resposta, é ignorado e transmitido tal como está ao cliente.

Chaves de cache

Pode reduzir o número de vezes que a RFC precisa de contactar a sua origem considerando o que identifica exclusivamente um pedido e removendo componentes que podem mudar frequentemente entre pedidos. O conjunto de componentes de pedido é frequentemente designado por "chave de cache".

As secções seguintes descrevem como configurar as chaves de cache.

Componentes principais da cache

Uma chave da cache é o conjunto de parâmetros de pedido (como o anfitrião, o caminho e os parâmetros de consulta) através dos quais um objeto em cache é referenciado.

Por predefinição, as chaves de cache para serviços de cache edge incluem o anfitrião do pedido, o caminho e os parâmetros de consulta do pedido, e têm âmbito num EdgeCacheService específico.

Componente Incluído por predefinição? Detalhes
Protocolo Não

Os pedidos através de HTTP e HTTPS referenciam o mesmo objeto em cache.

Se quiser devolver as diferentes respostas aos pedidos http: e https:, defina cacheKeyPolicy.includeProtocol como verdadeiro nas rotas associadas.
Anfitrião Sim

Os diferentes anfitriões não fazem referência aos mesmos objetos em cache.

Se tiver vários nomes de anfitrião direcionados para o mesmo EdgeCacheService e estiverem a publicar o mesmo conteúdo, defina cdnPolicy.excludeHost como verdadeiro.
Caminho Sim Está sempre incluído na chave da cache e não pode ser removido. O caminho é a representação mínima de um objeto na cache.
Parâmetros de consulta Sim

Se os parâmetros de consulta não distinguirem entre diferentes respostas, defina cacheKeyPolicy.excludeQueryString como verdadeiro.

Se apenas alguns parâmetros de consulta devem ser incluídos numa chave de cache, defina includedQueryParameters ou excludedQueryParameters, conforme adequado.
Cabeçalhos Não

Defina cacheKeyPolicy.includedHeaderNames com os nomes dos cabeçalhos a incluir na chave da cache.

A especificação de vários cabeçalhos que se combinam para ter um grande intervalo de valores (por exemplo, os valores dos cabeçalhos combinados identificam um único utilizador) reduz drasticamente a taxa de acertos da cache e pode resultar numa taxa de remoção mais elevada e num desempenho reduzido.
Cookies Não

Defina cacheKeyPolicy.includedCookieNames com os nomes dos cookies a incluir na chave da cache.

A especificação de vários cookies que se combinam para ter um grande intervalo de valores (por exemplo, os valores de cookies combinados identificam um único utilizador) reduz drasticamente a taxa de acertos da cache e pode resultar numa taxa de remoção mais elevada e num desempenho reduzido.

Tenha em conta o seguinte:

  • As chaves da cache não estão associadas a uma origem configurada, o que lhe permite atualizar uma configuração de origem (ou substituir a origem na totalidade) sem o risco de "limpar" a cache (por exemplo, quando migra o armazenamento de origem entre fornecedores).
  • As chaves de cache estão restritas a um EdgeCacheService. Os diferentes EdgeCacheServices têm namespaces de cache diferentes, o que impede o armazenamento em cache acidental de objetos entre ambientes de produção, preparação e outros ambientes de teste, mesmo que o anfitrião, o caminho ou outros componentes da chave de cache correspondam. A eliminação de um EdgeCacheService invalida efetivamente todos os objetos em cache para esse serviço.
  • As chaves da cache não estão no âmbito de uma rota individual. Várias rotas podem referir-se à mesma chave de cache, especialmente se essas rotas corresponderem a componentes que não estão incluídos na chave de cache, como cabeçalhos de pedidos ou parâmetros excluídos. Isto pode ser útil se quiser que várias rotas partilhem a mesma cache, mas devolvam cabeçalhos de resposta ou configuração de CORS diferentes.
  • As chaves da cache não incluem a configuração de reescrita de URLs. Por exemplo, uma chave da cache baseia-se no pedido apresentado ao utilizador e não no pedido "reescrito" final.
  • Quando os pedidos assinados estão configurados numa rota, os atributos assinados não são incluídos na chave da cache. O pedido é tratado como se os parâmetros de consulta (assinados) ou o componente do caminho, a começar por edge-cache-token e a terminar no separador de caminho seguinte ("/"), não fizessem parte do URL.

Inclua ou exclua parâmetros de consulta

Pode incluir ou excluir parâmetros de consulta específicos de uma chave de cache adicionando o nome do parâmetro à configuração da chave de cache includedQueryParameters ou excludedQueryParameters numa determinada rota.

Por exemplo, para incluir os parâmetros de consulta contentID e country e ignorar todos os outros da chave de cache:

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 86400s
  cacheKeyPolicy:
    includedQueryParameters: ["contentID", "country"]

Certifique-se de que inclui os parâmetros de consulta que identificam o conteúdo de forma exclusiva e exclui os que não o fazem. Por exemplo, exclua parâmetros de consulta do Analytics, IDs de sessões de reprodução ou outros parâmetros que sejam exclusivos do cliente. A inclusão de mais parâmetros de consulta do que o necessário pode diminuir as taxas de acerto da cache.

Em alternativa, em vez de especificar os parâmetros a incluir na chave de cache, pode escolher os parâmetros a excluir da chave de cache. Por exemplo, para excluir o ID de reprodução específico do cliente e as informações de data/hora da chave da cache, configure o seguinte:

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 86400s
  cacheKeyPolicy:
    excludedQueryParameters: ["playback-id", "timestamp"]

Para um determinado trajeto, pode especificar um de includedQueryParameters ou excludedQueryParameters.

Se os parâmetros de consulta nunca forem usados para identificar conteúdo de forma exclusiva em todas as solicitações, pode remover todos os parâmetros de consulta da chave de cache de uma rota. Para o fazer, defina excludeQueryString como true, da seguinte forma:

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 3600s
  cacheKeyPolicy:
    excludeQueryString: true

Se os pedidos assinados estiverem ativados numa rota, os parâmetros de consulta usados para a assinatura não são incluídos na string de consulta e são ignorados se forem incluídos. A inclusão dos parâmetros assinados na chave da cache torna cada pedido do utilizador efetivamente único e requer que cada pedido seja servido a partir da origem.

Ordenação de parâmetros de consulta

Os parâmetros de consulta (strings de consulta) são ordenados por predefinição para melhorar as taxas de acertos da cache, porque os clientes podem reordenar ou, de outra forma, pedir o mesmo objeto em cache com uma ordem diferente de parâmetros de consulta.

Por exemplo, os parâmetros de consulta b=world&a=hello&z=zulu&p=paris e p=paris&a=hello&z=zulu&b=world são ordenados como a=hello&b=world&p=paris&z=zulu antes de a chave de cache ser derivada. Isto permite que ambos os pedidos sejam mapeados para o mesmo objeto em cache, evitando um pedido desnecessário ao (e uma resposta do) servidor de origem.

Se existirem várias instâncias de uma chave de parâmetro de consulta, cada uma com valores distintos, os parâmetros são ordenados pelo respetivo valor completo (por exemplo, a=hello é ordenado antes de a=world). Não é possível desativar a ordenação.

Inclua cabeçalhos

Os nomes dos cabeçalhos não são sensíveis a maiúsculas e minúsculas e são convertidos em minúsculas pela RFC de multimédia.

Os seguintes cabeçalhos não podem ser incluídos na chave da cache:

  • Qualquer cabeçalho que comece com access-control-
  • Qualquer cabeçalho que comece com sec-fetch-
  • accept-encoding
  • accept
  • authorization
  • connection
  • content-md5
  • content-type
  • cookie
  • date
  • forwarded
  • from
  • host
  • if-match
  • if-modified-since
  • if-none-match
  • origin
  • proxy-authorization
  • range
  • referer
  • referrer
  • user-agent
  • want-digest
  • x-csrf-token
  • x-csrftoken
  • x-forwarded-for

Para incluir o método HTTP na chave da cache, use o nome do cabeçalho especial :method.

Inclua cookies

Os nomes dos cookies são sensíveis a maiúsculas e minúsculas.

Não é possível usar na chave de cache cookies que comecem por edge-cache- em qualquer variação de letras maiúsculas ou minúsculas.

Revalidação, despejo e validade

As redes de fornecimento de conteúdo, incluindo a RFC de multimédia, funcionam ao armazenar em cache o conteúdo mais popular o mais próximo possível dos utilizadores.

O armazenamento extensivo da RFC, bem como a proteção de origem, limita a necessidade de remover até mesmo conteúdo impopular. O conteúdo que é acedido um pequeno número de vezes por dia pode ser removido.

  • As respostas em cache que atingem o TTL configurado podem não ser imediatamente removidas. Para conteúdo popular, a RFC de multimédia valida novamente se a resposta em cache é a versão mais recente emitindo um pedido HEAD à origem para confirmar que os cabeçalhos não foram alterados. Em algumas circunstâncias, a RFC de conteúdo multimédia envia, em alternativa, um pedido à origem com um ou ambos os seguintes cabeçalhos de pedido: If-None-Match e If-Modified-Since. Neste caso, as origens configuradas corretamente devem devolver uma resposta HTTP 304 (Não modificado), sem os bytes do corpo, se a cache tiver a cópia "mais recente" dessa resposta.
  • As respostas que definem uma max-age ou uma s-maxage diretiva de cache ou que usam uma substituição de TTL para especificar um valor de TTL elevado (por exemplo, 30 dias) podem não ser armazenadas na cache durante o TTL completo. Não existe garantia de que um objeto seja armazenado na cache durante todo o período, especialmente se o acesso for pouco frequente.

Se estiver a ver uma taxa elevada de remoções, deve garantir que configurou as chaves da cache para excluir parâmetros que não identificam exclusivamente uma resposta.

Outras considerações

As seguintes considerações também podem aplicar-se relativamente à colocação em cache.

Vary cabeçalhos

O cabeçalho Vary indica que a resposta varia consoante os cabeçalhos de pedido do cliente. Se um cabeçalho Vary estiver presente na resposta, o Media CDN não o armazena em cache, a menos que o cabeçalho especifique um dos cabeçalhos configurados como uma definição de chave de cache ou um dos seguintes valores:

  • Accept: usado para indicar os tipos de suportes que o cliente aceita
  • Accept-Encoding: usado para indicar que tipos de compressão o cliente aceita
  • Available-Dictionary: usado para fornecer o hash de um dicionário disponível para compressão
  • Origem/X-Origem: normalmente usado para partilha de recursos de origem cruzada
  • X-Goog-Allowed-Resources: suporta a restrição da organização do Google Cloud
  • Sec-Fetch-Dest/Sec-Fetch-Mode/Sec-Fetch-Site: usado para obter cabeçalhos de pedidos de metadados

A RFC armazena em cache as respostas com um cabeçalho Vary na resposta usando o valor do cabeçalho como parte da chave de cache. Se o cabeçalho Vary na resposta tiver vários valores, estes são ordenados lexicograficamente para garantir que a chave da cache é determinística.

A RFC de multimédia armazena em cache até 100 variantes para uma determinada chave de cache e remove aleatoriamente as variantes da cache para além desse limite. Quando anula explicitamente a validação da cache para um determinado URL ou etiqueta de cache, todas as variantes são anuladas.

Ignorar a cache

Pode configurar o modo de cache BYPASS_CACHE numa rota para ignorar intencionalmente a cache em pedidos correspondentes. Isto pode ser útil se precisar de ignorar a cache para uma pequena fração do tráfego não crítico ou depurar a conetividade de origem.

Para casos em que precisa de publicar respostas dinâmicas, como back-ends de API, recomendamos que configure um balanceador de carga de aplicações externo.

Recomendamos que limite geralmente a utilização desta opção a cenários de depuração, para evitar o carregamento não intencional da origem. O tráfego de saída quando ignora a cache é cobrado às taxas de saída da Internet.

Invalidação de cache

Consulte a invalidação de cache.

Pedidos de intervalo de bytes

A RFC 7233 define que a RFC 7233 suporta pedidos de intervalo HTTP de parte única.

Além disso, a RFC de multimédia também usa pedidos de intervalo para obter respostas maiores da origem. Isto permite que a RFC 7230 armazene em cache os fragmentos individualmente e não requer que o objeto completo seja obtido de uma só vez para ser armazenado em cache.

  • Os objetos com mais de 1 MiB são obtidos como pedidos de intervalo de bytes ("blocos") de até 2 MiB cada.
  • As respostas até 1 MiB podem ser obtidas sem suporte para intervalos de bytes na origem.
  • As respostas superiores a este valor não são publicadas se os intervalos de bytes não forem suportados na origem.

O suporte de origem para pedidos de intervalo de bytes é determinado pelo seguinte:

  • Um código de estado HTTP de 200 (OK) ou 206 (Conteúdo parcial).
  • Um cabeçalho da resposta Content-Length ou Content-Range válido.
  • Um validador de respostas (ETag ou Last-Modified).

Os pedidos de preenchimento de origem individuais para cada "fragmento" (intervalo de bytes) são registados como entradas de registo discretas e associados ao respetivo pedido do cliente principal. Pode agrupar estes pedidos fazendo corresponder os pedidos no jsonPayload.cacheKeyFingerprint.

Para mais detalhes sobre o que é registado, consulte a documentação do Cloud Logging.

Pedidos de intervalo aberto

A RFC de conteúdo multimédia suporta pedidos "abertos" Range (por exemplo, um pedido com Range: bytes=0-) que mantêm um pedido aberto em relação à origem até que a resposta seja fechada pela origem (por exemplo, a origem escreve todos os bytes no cabo) ou exceda o tempo limite.

Normalmente, os intervalos de bytes ilimitados são usados por clientes que pedem segmentos de HLS de baixa latência da Apple: à medida que cada fragmento CMAF é escrito no cabo, a RFC pode colocar em cache e fornecer esse fragmento aos clientes.

Noutros casos, como quando a interoperabilidade com DASH não é necessária, a playlist de multimédia indica ao leitor que bytes representam cada fragmento:

  #EXTINF:4.08,
  fs270.mp4
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=20000@0
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=23000@20000
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=18000@43000
  #EXT-X-PRELOAD-HINT:TYPE=PART,URI="fs271.mp4",BYTERANGE-START=61000

Pode configurar o tempo de espera da RFC de multimédia entre leituras através do valor de configuração EdgeCacheOrigin.timeouts.readTimeout. Normalmente, deve configurar esta opção para um múltiplo (por exemplo, 2x) da duração alvo.

O que se segue?