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.

Observação: Como usar cabeçalhos para influenciar as chaves de cache e o TTL de entrada do cache é possível fazer a Apigee usar cabeçalhos de resposta na criação de chaves de cache de resposta e definição do TTL de entrada do cache. Para fazer isso, use estes elementos de sinalização da política ResponseCache:

<UseResponseCacheHeaders>: quando for definido como true, a Apigee considerará os cabeçalhos de resposta HTTP usados ao definir o "time to live" (TTL) da resposta no cache. Para mais detalhes, consulte "Como configurar a expiração da entrada de cache" e <UseResponseCacheHeaders> na política de cache de resposta.
<UseAcceptHeader>: quando for definido como true, a Apigee usará cabeçalhos Accept de resposta para aumentar a chave de cache. Para mais informações, consulte <UseAcceptHeader> na política de cache de resposta.

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. Observação: o conteúdo armazenado em cache com a política ResponseCache manterá o valor de max-age definido pela origem. Isso significa que, quando recuperado do cache, o conteúdo pode ser mais antigo do que o valor de max-age sugere (mais antigo que o cliente sabe).
`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. Observação: o cabeçalho HTTP/1.0, `Pragma: no-cache` é tratado como equivalente a `Cache-Control: no-cache`.
`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. Observação: o conteúdo armazenado em cache com a política ResponseCache manterá o valor s-maxage definido pela origem. Isso significa que, quando recuperado do cache, o conteúdo pode ser mais antigo do que o valor s-maxage sugere (mais antigo que o cliente sabe).

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.

Observação: as diretivas max-age e s-maxage de cabeçalho Cache-Control têm precedência e substituem o cabeçalho Expires. Para mais informações, consulte "Como configurar a expiração da entrada de cache" e <UseResponseCacheHeaders> na política de cache de resposta.

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.

Observação: a seção 14.21 da especificação indica que um valor de Expires de mais de um ano no futuro significa que uma entrada de cache nunca expira, mas a Apigee interpreta esse valor como se a entrada precisasse ser armazenada em cache até a data e a hora especificadas.

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	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`. Se uma correspondência for encontrada, a entrada do cache será retornada. 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	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`. 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.