Suporte para cabeçalhos de resposta HTTP

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Este tópico descreve como a Apigee processa cabeçalhos de cache HTTP/1.1 quando você usa a política ResponseCache. No momento, a Apigee é compatível com um subconjunto dos cabeçalhos e diretivas de armazenamento em cache HTTP/1.1 (recursos incompatíveis são listados neste tópico) recebidos dos servidores de destino de back-end (origem).

Além disso, com determinados cabeçalhos, a Apigee toma as medidas com base nas diretivas. Em alguns casos, esses cabeçalhos de cache HTTP/1.1 substituem qualquer comportamento especificado na política ResponseCache. Por exemplo, se o cabeçalho Cache-Control for retornado de um servidor de back-end, será possível usar a diretiva s-maxage do cabeçalho para possivelmente substituir outras configurações de expiração na política.

Header Suporte
Cache-Control Compatível com respostas retornadas de servidores de origem de back-end, mas não com solicitações de clientes. A Apigee é compatível com um subconjunto de diretivas.
Expira em Compatível. Pode ser substituída.
Tags de entidade (ETags) Comportamento específico para If-Match e If-None-Match.
If-Modified-Since Nas solicitações GET, o cabeçalho é transmitido para o servidor de origem, mesmo que exista uma entrada de cache válida.
Accept-Encoding A Apigee envia respostas compactadas ou não compactadas de acordo com os cabeçalhos recebidos.

Cache-Control

A Apigee é compatível com o cabeçalho Cache-Control somente nas respostas retornadas pelos servidores de origem de back-end. A especificação HTTP/1.1 permite que os cabeçalhos Cache-Control sejam enviados para solicitações e respostas do servidor de origem. Os servidores de origem podem incluir endpoints de destino definidos em um proxy da API Apigee e aqueles criados usando chamadas da API TargetServer.

Limitações de compatibilidade do Cache-Control

A Apigee é compatível com um subconjunto de recursos de cabeçalho de resposta Cache-Control definidos na especificação HTTP/1.1. Observe o seguinte:

  • A Apigee não é compatível com cabeçalhos Cache-Control que chegam com a entrada de solicitações de clientes.
  • A Apigee é compatível apenas com o conceito de caches públicos. De acordo com a especificação HTTP, Cache-Control pode ser público (compartilhado) ou particular (usuário único).
  • A Apigee é compatível apenas com um subconjunto de diretivas de resposta Cache-Control na especificação HTTP/1.1. Consulte Compatibilidade com diretivas de cabeçalho de resposta do Cache-Control para saber detalhes.

Compatibilidade com diretivas de cabeçalho de resposta do Cache-Control

A Apigee é compatível com uma diretiva de subconjunto da especificação HTTP/1.1 em respostas de servidores de origem. A tabela a seguir descreve a compatibilidade da Apigee para diretivas de cabeçalho de resposta HTTP Cache-Control.

Para informações mais detalhadas sobre as diretivas listadas aqui, consulte Cache-Control na especificação HTTP/1.1.

Diretiva Cache-Control Como a Apigee processa a diretiva
cache-extension Incompatível.
max-age

Se sua política ResponseCache definir o elemento <UseResponseCacheHeaders> como true, a resposta poderá ser armazenada em cache pelo número de segundos especificado por esta diretiva.

Essa diretiva é modificada pela diretiva s-maxage e substitui o cabeçalho Expires. Ela também pode ser modificada pelo elemento <ExpirySettings> da política. Para mais informações, consulte "Como configurar a expiração da entrada de cache" e <UseResponseCacheHeaders> na política de cache de resposta.

must-revalidate Incompatível. Todas as entradas de cache são excluídas pela Apigee assim que expiram.
no-cache

A Apigee armazena a resposta de origem em cache, mas ela precisa ser revalidada com o servidor de origem antes de ser usada para atender a quaisquer solicitações de cliente subsequentes. Essa regra permite que a origem retorne uma resposta 304 Not Modified, indicando que a resposta precisa ser retornada do cache, economizando o processamento necessário para retornar toda a resposta. Se o servidor de origem retornar uma resposta completa, ele substituirá a entrada de cache atual. Nomes de campo especificados com essa diretiva são ignorados.

no-store Incompatível.
no-transform Incompatível.
private Incompatível. Se essa diretiva for recebida, a resposta de origem não será armazenada em cache. Todos os nomes de campo são ignorados.
proxy-revalidate Incompatível. Todas as entradas de cache são excluídas pela Apigee assim que expiram.
public A Apigee armazena em cache a resposta de origem, mesmo quando houver outras diretivas indicando o contrário. De acordo com a especificação HTTP/1.1, a única exceção a essa regra é se a resposta incluir um cabeçalho de autorização.
s-maxage

Se sua política ResponseCache definir o elemento <UseResponseCacheHeaders> como true, a resposta poderá ser armazenada em cache pelo número de segundos especificado por esta diretiva.

Esta diretiva substitui a diretiva max-age e o cabeçalho Expires. Ela pode ser modificada pelo elemento <ExpirySettings> da política. Para mais informações, consulte "Como configurar a expiração da entrada de cache" e <UseResponseCacheHeaders> na política de cache de resposta.

Expires

Quando a sinalização UseResponseCacheHeaders na política ResponseCache estiver definida como true, a Apigee usará o cabeçalho Expires para determinar o tempo de vida (TTL, na sigla em inglês) de uma entrada armazenada em cache. Esse cabeçalho especifica uma data/hora. Depois dela, a entrada de cache da resposta é considerada desatualizada. Esse cabeçalho permite que os servidores sinalizem quando é possível retornar um valor armazenado em cache com base em um carimbo de data/hora.

Os formatos de data aceitáveis para o cabeçalho Expires estão descritos na especificação HTTP/1.1. Exemplo:

Expira em: quinta-feira, 01 de dezembro de 1994 16:00:00 GMT

Para informações detalhadas sobre formatos de data/hora HTTP, consulte Formatos de data/hora na especificação HTTP/1.1.

Para mais informações sobre o cabeçalho Expires, consulte Definições de campos de cabeçalho na especificação HTTP/1.1.

ETag

Uma tag de entidade (ETag) é um identificador associado a um recurso solicitado. Ao usar uma ETag, um servidor pode determinar se o recurso solicitado e o recurso armazenado em cache correspondem. Por exemplo, o servidor poderá armazenar em cache novamente a resposta caso ela não corresponda à informação armazenada no momento. Ele pode retornar o recurso armazenado em cache caso as ETags sejam correspondentes.

Quando um endpoint de destino envia uma resposta de volta à Apigee com uma ETag, a Apigee armazena a ETag em cache junto da resposta.

Leia mais sobre tags de entidade em Parâmetros de protocolo na especificação HTTP/1.1.

If-Match

Com o cabeçalho de solicitação If-Match, uma entidade armazenada em cache será atual caso a ETag no cabeçalho corresponda à ETag em cache. Todas as solicitações diferentes de GET que especificam um cabeçalho If-Match são transmitidas ao servidor de origem para garantir que qualquer recurso de armazenamento em cache de origem tenha a chance de processar a solicitação.

Leia mais sobre If-Match em Definições de campos de cabeçalho na especificação HTTP/1.1.

Se a Apigee receber uma solicitação GET de entrada de um cliente que inclui um cabeçalho If-Match:

If Then
O cabeçalho If-Match especifica uma ou mais ETags
  1. A Apigee recupera todas as entradas de cache não expiradas para o recurso especificado e compara quaisquer ETags fortes nessas entradas em cache com as especificadas no cabeçalho If-Match.
  2. Se uma correspondência for encontrada, a entrada do cache será retornada.
  3. Caso contrário, a solicitação será transmitida para o servidor de origem.
O cabeçalho If-Match especifica "*" A solicitação é transmitida ao servidor de origem para garantir que qualquer recurso de armazenamento em cache de origem tenha a chance de processar a solicitação.
Uma entrada de cache com o mesmo URI de solicitação foi encontrada, mas contém apenas ETags fracas A entrada precisa ser revalidada pelo servidor de origem antes de ser retornada ao cliente.
As ETags são provenientes do servidor de origem. A ETag é retornada sem alteração ao cliente

If-None-Match

Com o cabeçalho If-None-Match, uma entidade armazenada em cache será atual caso a ETag no cabeçalho não corresponda à ETag em cache. Solicitações diferentes de um GET que contenham esse cabeçalho são transmitidas para o servidor de origem.

Se a Apigee receber uma solicitação GET de entrada com este cabeçalho:

If Then
O cabeçalho If-None-Match especifica uma ou mais ETags
  1. A Apigee recupera todas as entradas de cache não expiradas para o URI especificado e compara quaisquer ETags fortes nessas entradas em cache com as especificadas no cabeçalho If-None-Match.
  2. Se uma correspondência for encontrada, a Apigee retornará o status 304 Not Modified. Se nenhuma correspondência for encontrada, a Apigee transmitirá a solicitação ao servidor de origem.

O cabeçalho If-None-Match especifica "*" e uma entrada em cache não expirada para o URI solicitado

A Apigee retorna um status 304 Not Modified
Uma entrada de cache com o mesmo URI de solicitação foi encontrada, mas contém apenas ETags fracas A entrada precisa ser revalidada pelo servidor de origem antes que a Apigee a retorne ao cliente.
A Apigee recebe uma ETag de um servidor de origem A ETag é retornada sem alteração ao cliente

If-Modified-Since

Se a Apigee receber um cabeçalho If-Modified-Since em uma solicitação GET, ela será transmitida para o servidor de origem, mesmo que exista uma entrada de cache válida.

Isso garante que todas as atualizações de um recurso que não tenham sido aprovadas pela Apigee sejam consideradas. Se o servidor de origem retornar uma nova entidade, a Apigee substituirá a entrada de cache atual pelo novo valor. Se o servidor retornar um status 304 Not Modified, a Apigee retornará o valor da resposta se o cabeçalho Last-Modified da resposta em cache indicar que ela não foi alterada.

Accept-Encoding

Quando uma solicitação recebida inclui o cabeçalho Accept-Encoding com valores de gzip, deflate ou compress, o servidor de origem responde com dados compactados. Quando as solicitações subsequentes vêm sem os cabeçalhos Accept-Encoding, elas esperam uma resposta não compactada. O mecanismo de armazenamento em cache de respostas da Apigee é capaz de enviar respostas compactadas e não compactadas, dependendo dos cabeçalhos de entrada, sem ter que voltar ao servidor de origem.

A opção "Aceitar valores de cabeçalho" pode ser anexada a chaves de cache para tornar as chaves mais significativas para cada item em cache. Para mais detalhes, consulte "Como configurar uma chave de cache" na Política de cache de resposta.