你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

从缓存中获取

2025-09-11

适用于：所有 API 管理层级

使用 cache-lookup 策略执行缓存查找，并返回有效的缓存响应（如果有）。当响应内容在某个时间段内保持静态时，即可应用该策略。响应缓存可以降低后端 Web 服务器需要满足的带宽和处理能力要求，并可以减小 API 使用者能够察觉到的延迟。

注意

此策略必须已设置相应的存储到缓存策略。

重要

内置缓存是易失性的，由同一 API 管理服务中同一区域的所有单元共享。

注意

按照策略声明中提供的顺序设置策略的元素和子元素。为了帮助你配置此策略，门户提供了基于窗体的引导式编辑器。详细了解如何设置或编辑 API 管理策略。

策略语句

<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 be repeated -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can be repeated -->
</cache-lookup>

属性

属性	说明	需要	默认
allow-private-response-caching	设置为 `true` 即可缓存包含 Authorization 标头的请求。允许使用策略表达式。	否	`false`
caching-type	在以下属性值之间进行选择： - `internal`，表示可使用内置的 API 管理缓存； - `external` 使用外部缓存，如- 中所述； - `prefer-external` 如果外部缓存已配置，则使用外部缓存，否则使用内部缓存。不允许使用策略表达式。	否	`prefer-external`
downstream-caching-type	此属性必须设置为以下值之一。 - none - 不允许下游缓存。 - private - 允许下游专用缓存。 - public - 允许专用和共享下游缓存。允许使用策略表达式。	否	无
必须重新验证	启用下游缓存时，此属性会启用或关闭网关响应中的 `must-revalidate` 缓存控制指令。允许使用策略表达式。	否	`true`
vary-by-developer	设置为 `true` 以缓存每个开发人员帐户的响应，这些帐户具有请求中包含的`true`。允许使用策略表达式。	是	`false`
vary-by-developer-groups	设置为 `true` 即可按`true`缓存响应。允许使用策略表达式。	是	`false`

元素

名称	说明	需要
vary-by-header	添加这其中的一个或多个元素以开始缓存每个指定标头的值的响应，例如 `Accept`、`Accept-Charset`、`Accept-Encoding`、`Accept-Language`、`Authorization`、`Expect`、`From`、`Host`、`If-Match`。	否
vary-by-query-parameter	添加这其中的一个或多个元素以开始缓存每个指定查询参数的值的响应。请输入一个或多个参数。使用分号作为分隔符。	否

使用情况

策略节：入站
策略范围：全局、工作区、产品、API、操作
网关：经典、v2、消耗、自承载、工作区

使用注意事项

API 管理仅对 HTTP GET 请求执行缓存查找。

使用 vary-by-query-parameter 时，可能需要在 rewrite-uri 模板中声明参数，或将属性 copy-unmatched-params 设置为 false。停用此标志后，未声明的参数将被发送到后端。

此策略只能在策略部分中使用一次。
策略片段中不支持此策略。
建议在任何缓存查找后立即配置速率限制策略（或按键速率限制策略）。这有助于防止后端服务在缓存不可用时过载。

示例

具有相应 cache-store 策略的示例

此示例演示如何将 cache-store 策略与策略一起使用 cache-lookup ，以缓存内置 API 管理缓存中的响应。

注意

缓存查找后添加的速率限制策略有助于限制在缓存不可用时阻止后端服务重载的调用数。

<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>
        <rate-limit calls="10" renewal-period="60" />
    </inbound>
    <outbound>
        <cache-store duration="seconds" />
        <base />
    </outbound>
</policies>

策略表达式使用示例

此示例演示如何配置 API 管理响应缓存持续时间，使之匹配由后端服务的 Cache-Control 指令指定的后端服务响应缓存。

<!-- 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>
 <rate-limit calls="10" renewal-period="60" />

<!-- 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;
  }"
 />

有关详细信息，请参阅策略表达式和上下文变量。

缓存

有关使用策略的详细信息，请参阅：

反馈

此页面是否有帮助？