API Management のキャッシュ ポリシーAPI Management caching policies

このトピックでは、次の API Management ポリシーについて説明します。This topic provides a reference for the following API Management policies. ポリシーを追加および構成する方法については、「 Azure API Management のポリシー」をご覧ください。For information on adding and configuring policies, see Policies in API Management.

キャッシュ ポリシーCaching policies

キャッシュから取得Get from cache

cache-lookup ポリシーを使用し、キャッシュを検索して、キャッシュに格納された有効な応答ががあればそれを返します。Use the cache-lookup policy to perform cache look up and return a valid cached response when available. このポリシーを適用できるのは、応答の内容が一定期間にわたって静的である場合です。This policy can be applied in cases where response content remains static over a period of time. 応答のキャッシュを使用すると、バックエンド Web サーバーの帯域幅および処理の要件が低減され、API コンシューマーによって認識される遅延が小さくなります。Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

注意

このポリシーには、対応するキャッシュに格納ポリシーが必要です。This policy must have a corresponding Store to cache policy.

ポリシー ステートメントPolicy 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>

Examples

Example

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

ポリシー式の使用例Example using policy expressions

この例は、API Management 応答のキャッシュ時間を、バックエンド サービスの Cache-Control ディレクティブによって指定されたバックエンド サービスの応答キャッシュ時間と一致するように構成する方法を示します。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. このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177: More API Management Features (クラウド カバー エピソード 177: その他の API Management 機能の紹介)」を 25:25 まで早送りしてご覧ください。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;
  }"
 />

詳細については、ポリシー式およびコンテキスト変数に関する各ページを参照してください。For more information, see Policy expressions and Context variable.

要素Elements

EnableAdfsAuthenticationName 説明Description 必須Required
cache-lookupcache-lookup ルート要素。Root element. はいYes
vary-by-headervary-by-header 指定されたヘッダーの値 (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. いいえNo
vary-by-query-parametervary-by-query-parameter 指定されたクエリ パラメーターの値ごとに応答をキャッシュに格納します。Start caching responses per value of specified query parameters. 1 つまたは複数のパラメーターを入力します。Enter a single or multiple parameters. セミコロンを区切り文字として使用します。Use semicolon as a separator. パラメーターを指定しない場合、すべてのクエリ パラメーターが使用されます。If none are specified, all query parameters are used. いいえNo

属性Attributes

EnableAdfsAuthenticationName 説明Description 必須Required 既定値Default
allow-private-response-cachingallow-private-response-caching true に設定すると、承認ヘッダーを含む要求をキャッシュできます。When set to true, allows caching of requests that contain an Authorization header. いいえNo falsefalse
caching-typecaching-type 属性の次の値のいずれかを選択します。Choose between the following values of the attribute:
- internal (組み込みの API Management キャッシュを使用する場合)、- internal to use the built-in API Management cache,
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。- prefer-external to use external cache if configured or internal cache otherwise.
いいえNo prefer-external
downstream-caching-typedownstream-caching-type この属性の値は次のいずれかに設定する必要があります。This attribute must be set to one of the following values.

- none - ダウンストリーム キャッシュは許可されません。- none - downstream caching is not allowed.
- private - ダウンストリーム プライベート キャッシュが許可されます。- private - downstream private caching is allowed.
- public - プライベートおよび共有ダウンストリーム キャッシュが許可されます。- public - private and shared downstream caching is allowed.
いいえNo なしnone
must-revalidatemust-revalidate ダウンストリーム キャッシュが有効になっているとき、この属性によって、ゲートウェイ応答での must-revalidate キャッシュ制御ディレクティブのオンとオフを切り替えます。When downstream caching is enabled this attribute turns on or off the must-revalidate cache control directive in gateway responses. いいえNo truetrue
vary-by-developervary-by-developer true に設定すると、サブスクリプション キーごとに応答をキャッシュします。Set to true to cache responses per subscription key. はいYes FalseFalse
vary-by-developer-groupsvary-by-developer-groups true に設定すると、ユーザー グループごとに応答をキャッシュします。Set to true to cache responses per user group. はいYes FalseFalse

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inboundPolicy sections: inbound
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

キャッシュに格納Store to cache

cache-storeポリシーは、指定されたキャッシュ設定に従って応答をキャッシュに格納します。The cache-store policy caches responses according to the specified cache settings. このポリシーを適用できるのは、応答の内容が一定期間にわたって静的である場合です。This policy can be applied in cases where response content remains static over a period of time. 応答のキャッシュを使用すると、バックエンド Web サーバーの帯域幅および処理の要件が低減され、API コンシューマーによって認識される遅延が小さくなります。Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

注意

このポリシーには、対応するキャッシュから取得ポリシーが必要です。This policy must have a corresponding Get from cache policy.

ポリシー ステートメントPolicy statement

<cache-store duration="seconds" />

Examples

Example

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

ポリシー式の使用例Example using policy expressions

この例は、API Management 応答のキャッシュ時間を、バックエンド サービスの Cache-Control ディレクティブによって指定されたバックエンド サービスの応答キャッシュ時間と一致するように構成する方法を示します。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. このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177: More API Management Features (クラウド カバー エピソード 177: その他の API Management 機能の紹介)」を 25:25 まで早送りしてご覧ください。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;
  }"
 />

詳細については、ポリシー式およびコンテキスト変数に関する各ページを参照してください。For more information, see Policy expressions and Context variable.

要素Elements

EnableAdfsAuthenticationName 説明Description 必須Required
cache-storecache-store ルート要素。Root element. はいYes

属性Attributes

EnableAdfsAuthenticationName 説明Description 必須Required 既定値Default
durationduration キャッシュに格納されたエントリの有効期間 (秒単位)。Time-to-live of the cached entries, specified in seconds. はいYes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: outboundPolicy sections: outbound
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

キャッシュから値を取得Get value from cache

cache-lookup-value ポリシーを使用して、キーごとにキャッシュの検索を行い、キャッシュされている値を返します。Use the cache-lookup-value policy to perform cache lookup by key and return a cached value. キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。The key can have an arbitrary string value and is typically provided using a policy expression.

注意

このポリシーには、対応する値をキャッシュに格納ポリシーが必要です。This policy must have a corresponding Store value in cache policy.

ポリシー ステートメントPolicy 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" />

Example

このポリシーの詳細と例については、「Custom caching in Azure API Management」(Azure API Management でのカスタム キャッシュ) を参照してください。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" />

要素Elements

EnableAdfsAuthenticationName 説明Description 必須Required
cache-lookup-valuecache-lookup-value ルート要素。Root element. はいYes

属性Attributes

EnableAdfsAuthenticationName 説明Description 必須Required 既定値Default
caching-typecaching-type 属性の次の値のいずれかを選択します。Choose between the following values of the attribute:
- internal (組み込みの API Management キャッシュを使用する場合)、- internal to use the built-in API Management cache,
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。- prefer-external to use external cache if configured or internal cache otherwise.
いいえNo prefer-external
default-valuedefault-value キーによるキャッシュ検索で何も見つからなかった場合に、変数に割り当てられる値。A value that will be assigned to the variable if the cache key lookup resulted in a miss. この属性が指定されない場合は null が割り当てられます。If this attribute is not specified, null is assigned. いいえNo null
keykey 検索で使用するキャッシュのキー値。Cache key value to use in the lookup. はいYes 該当なしN/A
variable-namevariable-name 検索が成功した場合に、検索された値が割り当てられるコンテキスト変数の名前。Name of the context variable the looked up value will be assigned to, if lookup is successful. 検索結果で何も見つからなかった場合、変数には、default-value 属性の値または null (default-value 属性が省略されたとき) が割り当てられます。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. はいYes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

値をキャッシュに格納Store value in cache

cache-store-value は、キーごとに記憶域のキャッシュを実行します。The cache-store-value performs cache storage by key. キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。The key can have an arbitrary string value and is typically provided using a policy expression.

注意

このポリシーには、対応するキャッシュから値を取得ポリシーが必要です。This policy must have a corresponding Get value from cache policy.

ポリシー ステートメントPolicy statement

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

Example

このポリシーの詳細と例については、「Custom caching in Azure API Management」(Azure API Management でのカスタム キャッシュ) を参照してください。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" />

要素Elements

EnableAdfsAuthenticationName 説明Description 必須Required
cache-store-valuecache-store-value ルート要素。Root element. はいYes

属性Attributes

EnableAdfsAuthenticationName 説明Description 必須Required 既定値Default
caching-typecaching-type 属性の次の値のいずれかを選択します。Choose between the following values of the attribute:
- internal (組み込みの API Management キャッシュを使用する場合)、- internal to use the built-in API Management cache,
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。- prefer-external to use external cache if configured or internal cache otherwise.
いいえNo prefer-external
durationduration 指定された期間 (秒単位)、値がキャッシュされます。Value will be cached for the provided duration value, specified in seconds. はいYes 該当なしN/A
keykey 値が格納されるキャッシュのキー。Cache key the value will be stored under. はいYes 該当なしN/A
valuevalue キャッシュされる値。The value to be cached. はいYes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

キャッシュから値を削除Remove value from cache

cache-remove-value は、キーで指定された、キャッシュされている項目を削除します。The cache-remove-value deletes a cached item identified by its key. キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。The key can have an arbitrary string value and is typically provided using a policy expression.

ポリシー ステートメントPolicy statement


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

Example


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

要素Elements

EnableAdfsAuthenticationName 説明Description 必須Required
cache-remove-valuecache-remove-value ルート要素。Root element. はいYes

属性Attributes

EnableAdfsAuthenticationName 説明Description 必須Required 既定値Default
caching-typecaching-type 属性の次の値のいずれかを選択します。Choose between the following values of the attribute:
- internal (組み込みの API Management キャッシュを使用する場合)、- internal to use the built-in API Management cache,
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。- prefer-external to use external cache if configured or internal cache otherwise.
いいえNo prefer-external
keykey キャッシュから削除される、前にキャッシュされた値のキー。The key of the previously cached value to be removed from the cache. はいYes 該当なしN/A

使用法Usage

このポリシーは、ポリシーの以下のセクションスコープで使用できます。This policy can be used in the following policy sections and scopes .

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

次の手順Next steps

ポリシーを使用する方法の詳細については、次のトピックを参照してください。For more information working with policies, see: