Políticas de cache do Gerenciamento de APIAPI Management caching policies

Este tópico fornece uma referência para as políticas de Gerenciamento de API a seguir.This topic provides a reference for the following API Management policies. Para obter mais informações sobre como adicionar e configurar políticas, consulte Políticas de Gerenciamento de API.For information on adding and configuring policies, see Policies in API Management.

Políticas de cacheCaching policies

Obter do cacheGet from cache

Use a política cache-lookup para realizar pesquisas e retornar uma resposta válida em cache quando disponível.Use the cache-lookup policy to perform cache look up and return a valid cached response when available. Esta política deve ser aplicada em casos nos quais o conteúdo da resposta permanece estático por um período de tempo.This policy can be applied in cases where response content remains static over a period of time. O cache das respostas reduz os requisitos de largura de banda e processamento exigidos do servidor Web de back-end e reduz a latência percebida pelos consumidores da API.Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

Observação

É necessário ter uma política correspondente de Armazenar em cache.This policy must have a corresponding Store to cache policy.

Declaração de políticaPolicy statement

<cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" caching-type="prefer-external | external | internal" downstream-caching-type="none | private | public" must-revalidate="true | false" allow-private-response-caching="@(expression to evaluate)">
  <vary-by-header>Accept</vary-by-header>
  <!-- should be present in most cases -->
  <vary-by-header>Accept-Charset</vary-by-header>
  <!-- should be present in most cases -->
  <vary-by-header>Authorization</vary-by-header>
  <!-- should be present when allow-private-response-caching is "true"-->
  <vary-by-header>header name</vary-by-header>
  <!-- optional, can repeated several times -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can repeated several times -->
</cache-lookup>

ExemplosExamples

ExemploExample

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none" must-revalidate="true" caching-type="internal" >
            <vary-by-query-parameter>version</vary-by-query-parameter>
        </cache-lookup>
    </inbound>
    <outbound>
        <cache-store duration="seconds" />
        <base />
    </outbound>
</policies>

Exemplo usando expressões de políticaExample using policy expressions

Este exemplo mostra como configurar a duração do cache de resposta do Gerenciamento de API que corresponde ao cache de resposta do serviço de back-end, conforme especificado pela diretiva Cache-Control do serviço de backup.This example shows how to configure API Management response caching duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive. Para obter uma demonstração de como configurar e usar essa política, assista ao vídeo Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky (Cloud Cover, episódio 177: Mais recursos de gerenciamento de API com Vlad Vinogradsky) e avance para 25min25s.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 25:25.

<!-- The following cache policy snippets demonstrate how to control API Management response cache duration with Cache-Control headers sent by the backend service. -->

<!-- Copy this snippet into the inbound section -->
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >
  <vary-by-header>Accept</vary-by-header>
  <vary-by-header>Accept-Charset</vary-by-header>
</cache-lookup>

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the default value of 5 min if none is found  -->
<cache-store duration="@{
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;
  }"
 />

Para obter mais informações, veja Expressões de política e Variável de contexto.For more information, see Policy expressions and Context variable.

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
cache-lookupcache-lookup Elemento raiz.Root element. SimYes
vary-by-headervary-by-header Inicie o cache de respostas por valor de cabeçalho especificado, como Accept, Accept-Charset, Accept-Encoding, Accept-Language, Authorization, Expect, From, Host, If-Match.Start caching responses per value of specified header, such as Accept, Accept-Charset, Accept-Encoding, Accept-Language, Authorization, Expect, From, Host, If-Match. NãoNo
vary-by-query-parametervary-by-query-parameter Inicie o cache de respostas de acordo com o valor dos parâmetros de consulta especificados.Start caching responses per value of specified query parameters. Insira somente um ou múltiplos parâmetros.Enter a single or multiple parameters. Use ponto e vírgula como um separador.Use semicolon as a separator. Se nenhum for especificado, todos os parâmetros de consulta serão usados.If none are specified, all query parameters are used. NãoNo

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
allow-private-response-cachingallow-private-response-caching Quando definido como true, permite armazenar em cache as solicitações que contêm um cabeçalho Authorization.When set to true, allows caching of requests that contain an Authorization header. NãoNo falsofalse
caching-typecaching-type Escolha entre os seguintes valores do atributo:Choose between the following values of the attribute:
- internal para usar o cache interno do Gerenciamento de API,- internal to use the built-in API Management cache,
- external para usar o cache externo, conforme descrito em Usar um Cache Redis do Azure externo no Gerenciamento de API do Azure,- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external para usar cache externo se configurado ou cache interno.- prefer-external to use external cache if configured or internal cache otherwise.
NãoNo prefer-external
downstream-caching-typedownstream-caching-type Este atributo deve ser definido como um dos valores a seguir.This attribute must be set to one of the following values.

- none: o cache downstream não é permitido.- none - downstream caching is not allowed.
- private: o cache downstream privado é permitido.- private - downstream private caching is allowed.
- public: o cache downstream privado e compartilhado é permitido.- public - private and shared downstream caching is allowed.
NãoNo Nenhumnone
must-revalidatemust-revalidate Quando o cache downstream está habilitado, este atributo ativa ou desativa a diretiva de controle de cache must-revalidate em respostas do gateway.When downstream caching is enabled this attribute turns on or off the must-revalidate cache control directive in gateway responses. NãoNo verdadeirotrue
vary-by-developervary-by-developer Defina-o como true para armazenar em cache as respostas por chave de assinatura.Set to true to cache responses per subscription key. SimYes FalsoFalse
vary-by-developer-groupsvary-by-developer-groups Defina-o como true para armazenar em cache as respostas por grupo de usuários.Set to true to cache responses per user group. SimYes FalsoFalse

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entradaPolicy sections: inbound
  • Escopos de política: API, operação, produtoPolicy scopes: API, operation, product

Armazenar em cacheStore to cache

A política cache-store armazena as respostas em cache de acordo com a configuração de cache especificada.The cache-store policy caches responses according to the specified cache settings. Esta política deve ser aplicada em casos nos quais o conteúdo da resposta permanece estático por um período de tempo.This policy can be applied in cases where response content remains static over a period of time. O cache das respostas reduz os requisitos de largura de banda e processamento exigidos do servidor Web de back-end e reduz a latência percebida pelos consumidores da API.Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

Observação

Esta política deve ter uma política Obter do cache correspondente.This policy must have a corresponding Get from cache policy.

Declaração de políticaPolicy statement

<cache-store duration="seconds" />

ExemplosExamples

ExemploExample

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" downstream-caching-type="none | private | public" must-revalidate="true | false">
            <vary-by-query-parameter>parameter name</vary-by-query-parameter> <!-- optional, can repeated several times -->
        </cache-lookup>
    </inbound>
    <outbound>
        <base />
        <cache-store duration="3600" />
    </outbound>
</policies>

Exemplo usando expressões de políticaExample using policy expressions

Este exemplo mostra como configurar a duração do cache de resposta do Gerenciamento de API que corresponde ao cache de resposta do serviço de back-end, conforme especificado pela diretiva Cache-Control do serviço de backup.This example shows how to configure API Management response caching duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive. Para obter uma demonstração de como configurar e usar essa política, assista ao vídeo Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky (Cloud Cover, episódio 177: Mais recursos de gerenciamento de API com Vlad Vinogradsky) e avance para 25min25s.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 25:25.

<!-- The following cache policy snippets demonstrate how to control API Management response cache duration with Cache-Control headers sent by the backend service. -->

<!-- Copy this snippet into the inbound section -->
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >
  <vary-by-header>Accept</vary-by-header>
  <vary-by-header>Accept-Charset</vary-by-header>
</cache-lookup>

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the default value of 5 min if none is found  -->
<cache-store duration="@{
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;
  }"
 />

Para obter mais informações, veja Expressões de política e Variável de contexto.For more information, see Policy expressions and Context variable.

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
cache-storecache-store Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
durationduration Vida útil das entradas armazenadas em cache, especificada em segundos.Time-to-live of the cached entries, specified in seconds. SimYes N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: saídaPolicy sections: outbound
  • Escopos de política: API, operação, produtoPolicy scopes: API, operation, product

Obter valor do cacheGet value from cache

Use a política cache-lookup-value para executar a consulta em cache por chave e retornar um valor armazenado em cache.Use the cache-lookup-value policy to perform cache lookup by key and return a cached value. A chave pode ter um valor de cadeia de caracteres arbitrária e geralmente é fornecida usando uma expressão de política.The key can have an arbitrary string value and is typically provided using a policy expression.

Observação

É necessário ter uma política correspondente de Armazenar valor em cache.This policy must have a corresponding Store value in cache policy.

Declaração de políticaPolicy statement

<cache-lookup-value key="cache key value"
    default-value="value to use if cache lookup resulted in a miss"
    variable-name="name of a variable looked up value is assigned to"
    caching-type="prefer-external | external | internal" />

ExemploExample

Para saber mais e obter exemplos dessa política, veja Cache personalizado no Gerenciamento de API do Azure.For more information and examples of this policy, see Custom caching in Azure API Management.

<cache-lookup-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    variable-name="userprofile" />

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
cache-lookup-valuecache-lookup-value Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
caching-typecaching-type Escolha entre os seguintes valores do atributo:Choose between the following values of the attribute:
- internal para usar o cache interno do Gerenciamento de API,- internal to use the built-in API Management cache,
- external para usar o cache externo, conforme descrito em Usar um Cache Redis do Azure externo no Gerenciamento de API do Azure,- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external para usar cache externo se configurado ou cache interno.- prefer-external to use external cache if configured or internal cache otherwise.
NãoNo prefer-external
default-valuedefault-value Um valor que será atribuído à variável se a pesquisa de chave em cache resultou em um erro.A value that will be assigned to the variable if the cache key lookup resulted in a miss. Se esse atributo não for especificado, null é atribuído.If this attribute is not specified, null is assigned. NãoNo null
chavekey Valor de chave de cache a usar na pesquisa.Cache key value to use in the lookup. SimYes N/DN/A
variable-namevariable-name Nome da variável de contexto a atribuir para o valor pesquisado, se a pesquisa for bem-sucedida.Name of the context variable the looked up value will be assigned to, if lookup is successful. Se a pesquisa resulta em um erro, a variável será atribuída o valor do atributo default-value ou null, se o atributo default-value for omitido.If lookup results in a miss, the variable will be assigned the value of the default-value attribute or null, if the default-value attribute is omitted. SimYes N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções da política: entrada, saída, back-end, em caso de erroPolicy sections: inbound, outbound, backend, on-error
  • Escopos de política: global, API, operação, produtoPolicy scopes: global, API, operation, product

Armazenar valor em cacheStore value in cache

cache-store-value armazena em cache por chave.The cache-store-value performs cache storage by key. A chave pode ter um valor de cadeia de caracteres arbitrária e geralmente é fornecida usando uma expressão de política.The key can have an arbitrary string value and is typically provided using a policy expression.

Observação

Esta política deve ter uma política Obter valor do cache correspondente.This policy must have a corresponding Get value from cache policy.

Declaração de políticaPolicy statement

<cache-store-value key="cache key value" value="value to cache" duration="seconds" caching-type="prefer-external | external | internal" />

ExemploExample

Para saber mais e obter exemplos dessa política, veja Cache personalizado no Gerenciamento de API do Azure.For more information and examples of this policy, see Custom caching in Azure API Management.

<cache-store-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    value="@((string)context.Variables["userprofile"])" duration="100000" />

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
cache-store-valuecache-store-value Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
caching-typecaching-type Escolha entre os seguintes valores do atributo:Choose between the following values of the attribute:
- internal para usar o cache interno do Gerenciamento de API,- internal to use the built-in API Management cache,
- external para usar o cache externo, conforme descrito em Usar um Cache Redis do Azure externo no Gerenciamento de API do Azure,- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external para usar cache externo se configurado ou cache interno.- prefer-external to use external cache if configured or internal cache otherwise.
NãoNo prefer-external
durationduration Valor será armazenado em cache para o valor de duração fornecido, especificado em segundos.Value will be cached for the provided duration value, specified in seconds. SimYes N/DN/A
chavekey A chave em cache em que o valor será armazenado.Cache key the value will be stored under. SimYes N/DN/A
valuevalue O valor a ser armazenado em cache.The value to be cached. SimYes N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções da política: entrada, saída, back-end, em caso de erroPolicy sections: inbound, outbound, backend, on-error
  • Escopos de política: global, API, operação, produtoPolicy scopes: global, API, operation, product

Remover valor do cacheRemove value from cache

cache-remove-value exclui um item em cache identificado por sua chave.The cache-remove-value deletes a cached item identified by its key. A chave pode ter um valor de cadeia de caracteres arbitrária e geralmente é fornecida usando uma expressão de política.The key can have an arbitrary string value and is typically provided using a policy expression.

Declaração de políticaPolicy statement


<cache-remove-value key="cache key value" caching-type="prefer-external | external | internal"  />

ExemploExample


<cache-remove-value key="@("userprofile-" + context.Variables["enduserid"])"/>

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
cache-remove-valuecache-remove-value Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
caching-typecaching-type Escolha entre os seguintes valores do atributo:Choose between the following values of the attribute:
- internal para usar o cache interno do Gerenciamento de API,- internal to use the built-in API Management cache,
- external para usar o cache externo, conforme descrito em Usar um Cache Redis do Azure externo no Gerenciamento de API do Azure,- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external para usar cache externo se configurado ou cache interno.- prefer-external to use external cache if configured or internal cache otherwise.
NãoNo prefer-external
chavekey A chave do valor anteriormente armazenado em cache a ser removido do cache.The key of the previously cached value to be removed from the cache. SimYes N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes .

  • Seções da política: entrada, saída, back-end, em caso de erroPolicy sections: inbound, outbound, backend, on-error
  • Escopos de política: global, API, operação, produtoPolicy scopes: global, API, operation, product

Próximas etapasNext steps

Para obter mais informações sobre como trabalhar com políticas, consulte:For more information working with policies, see: