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

API 管理缓存策略

此页面有帮助吗?

还有其他反馈吗？

反馈将发送到 Microsoft：按“提交”按钮，你的反馈将用于改进 Microsoft 产品和服务。 隐私策略。

本文提供用于缓存响应的 API 管理策略的参考。

有关策略的详细信息：

• 策略概述
• 设置或编辑策略
• 策略表达式
• 策略参考，其中提供了策略语句及其设置的完整列表

重要

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

缓存策略

• 响应缓存策略
  • 从缓存中获取 - 执行缓存查找，并返回有效的缓存响应（如果有）。
  • 存储到缓存 - 根据指定的缓存控制配置来缓存响应。
• 值缓存策略
  • 从缓存中获取值 - 按密钥检索缓存项。
  • 在缓存中存储值 - 按密钥在缓存中存储项。
  • 从缓存中删除值 - 按密钥在缓存中删除项。

从缓存中获取

使用 cache-lookup 策略执行缓存查找，并返回有效的缓存响应（如果有）。 当响应内容在某个时间段内保持静态时，即可应用该策略。 响应缓存可以降低后端 Web 服务器需要满足的带宽和处理能力要求，并可以减小 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 repeated several times -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can repeated several times -->
</cache-lookup>

注意

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

示例

示例

<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>

策略表达式使用示例

此示例演示如何配置 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>

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

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

元素

名称	说明	必需
cache-lookup	根元素。	是
vary-by-header	开始按指定标头（例如 Accept、Accept-Charset、Accept-Encoding、Accept-Language、Authorization、Expect、From、Host、If-Match）的值缓存响应。	否
vary-by-query-parameter	根据指定查询参数的值开始缓存响应。 请输入一个或多个参数。 使用分号作为分隔符。 如果未指定任何参数，将使用所有查询参数。	否

属性

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

使用情况

此策略可在以下策略节和范围中使用。

• 策略节： 入站
• 策略范围： 所有范围

存储到缓存

cache-store 策略根据指定的缓存设置缓存响应。 当响应内容在某个时间段内保持静态时，即可应用该策略。 响应缓存可以降低后端 Web 服务器需要满足的带宽和处理能力要求，并可以减小 API 使用者能够察觉到的延迟。

注意

此策略必须已设置相应的从缓存中获取策略。

提示

为了帮助你配置此策略，门户提供了基于窗体的引导式编辑器。 详细了解如何设置或编辑 API 管理策略。

策略语句

<cache-store duration="seconds" cache-response="true | false" />

示例

示例

<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>

策略表达式使用示例

此示例演示如何配置 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>

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

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

元素

名称	说明	必需
cache-store	根元素。	是

属性

名称	说明	必须	默认
duration	缓存条目的生存时间，以秒为单位指定。	是	空值
cache-response	设置为 true 可缓存当前 HTTP 响应。 如果省略此属性或将其设置为 false，则只缓存状态代码为 200 OK 的 HTTP 响应。	否	false

使用情况

此策略可在以下策略节和范围中使用。

• 策略段：出站
• 策略范围： 所有范围

从缓存中获取值

使用 cache-lookup-value 策略，可以通过密钥执行缓存查找，并返回缓存的值。 密钥的值可以是任意字符串，通常使用策略表达式来提供密钥。

注意

此策略必须已设置相应的在缓存中存储值策略。

提示

了解如何设置或编辑 API 管理策略。

策略语句

<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" />

示例

有关此策略的详细信息和示例，请参阅 Azure API 管理中的自定义缓存。

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

元素

名称	说明	必需
cache-lookup-value	根元素。	是

属性

名称	说明	必须	默认
caching-type	在以下属性值之间进行选择： - internal 使用内置的 API 管理缓存； - external 使用外部缓存，如- 中所述； - prefer-external 如果外部缓存已配置，则使用外部缓存，否则使用内部缓存。	否	prefer-external
default-value	在缓存密钥查找未命中的情况下，会分配给变量的值。 如果未指定此属性，则会分 null。	否	null
key	要在查找中使用的缓存密钥值。	是	不适用
variable-name	在查找成功的情况下，会向其分配查找值的上下文变量的名称。 如果查找未命中，则不会设置该变量。	是	空值

使用情况

此策略可在以下策略节和范围中使用。

• 策略节： 入站、出站、后端、错误时
• 策略范围： 所有范围

在缓存中存储值

cache-store-value 按密钥执行缓存存储。 密钥的值可以是任意字符串，通常使用策略表达式来提供密钥。

注意

此策略将值存储到缓存中这项操作是异步执行的。 可以使用从缓存获取值策略检索存储的值。 但是，存储的值可能不会立即就能检索，因为将值存储到缓存中的异步操作可能仍在进行中。

提示

了解如何设置或编辑 API 管理策略。

策略语句

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

示例

有关此策略的详细信息和示例，请参阅 Azure API 管理中的自定义缓存。

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

元素

名称	说明	必需
cache-store-value	根元素。	是

属性

名称	说明	必须	默认
caching-type	在以下属性值之间进行选择： - internal 使用内置的 API 管理缓存； - external 使用外部缓存，如- 中所述； - prefer-external 如果外部缓存已配置，则使用外部缓存，否则使用内部缓存。	否	prefer-external
duration	会根据提供的期间值（以秒为单位指定）将值缓存一段时间。	是	不适用
key	缓存密钥，会在其下存储值。	是	空值
value	要缓存的值。	是	空值

使用情况

此策略可在以下策略节和范围中使用。

• 策略节： 入站、出站、后端、错误时
• 策略范围： 所有范围

从缓存中删除值

cache-remove-value 删除通过密钥标识的缓存项。 密钥的值可以是任意字符串，通常使用策略表达式来提供密钥。

提示

了解如何设置或编辑 API 管理策略。

策略语句

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

示例

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

元素

名称	说明	必需
cache-remove-value	根元素。	是

属性

名称	说明	必须	默认
caching-type	在以下属性值之间进行选择： - internal 使用内置的 API 管理缓存； - external 使用外部缓存，如- 中所述； - prefer-external 如果外部缓存已配置，则使用外部缓存，否则使用内部缓存。	否	prefer-external
key	以前所缓存的值（将从缓存中删除）的密钥。	是	空值

使用情况

此策略可在以下策略节和范围中使用。

• 策略节： 入站、出站、后端、错误时
• 策略范围： 所有范围

后续步骤

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

• 教程：转换和保护 API
• 策略参考，其中提供了策略语句及其设置的完整列表
• 策略表达式
• 设置或编辑策略
• 策略示例