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

この記事では、次の API Management ポリシーについて説明します。 ポリシーを追加および構成する方法については、「 Azure API Management のポリシー」をご覧ください。

重要

組み込みのキャッシュは揮発性であり、同じ API Management サービスの同じリージョン内のすべてのユニットによって共有されます。

キャッシュ ポリシー

キャッシュから取得

cache-lookup ポリシーを使用し、キャッシュを検索して、キャッシュに格納された有効な応答ががあればそれを返します。 このポリシーを適用できるのは、応答の内容が一定期間にわたって静的である場合です。 応答のキャッシュを使用すると、バックエンド Web サーバーの帯域幅および処理の要件が低減され、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 Management 応答のキャッシュ時間を、バックエンド サービスの Cache-Control ディレクティブによって指定されたバックエンド サービスの応答キャッシュ時間と一致するように構成する方法を示します。 このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky」(クラウド カバー エピソード 177: Vlad Vinogradsky によるその他の API Management 機能の紹介) を 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;
  }"
 />

詳細については、ポリシー式およびコンテキスト変数に関する各ページを参照してください。

要素

名前 説明 必須
cache-lookup ルート要素。 はい
vary-by-header 指定されたヘッダーの値 (Accept、Accept-Charset、Accept-Encoding、Accept-Language、Authorization、Expect、From、Host、If-Match など) ごとに応答をキャッシュに格納します。 いいえ
vary-by-query-parameter 指定されたクエリ パラメーターの値ごとに応答をキャッシュに格納します。 1 つまたは複数のパラメーターを入力します。 セミコロンを区切り文字として使用します。 パラメーターを指定しない場合、すべてのクエリ パラメーターが使用されます。 いいえ

属性

名前 説明 必須 Default
allow-private-response-caching true に設定すると、承認ヘッダーを含む要求をキャッシュできます。 いいえ false
caching-type 属性の次の値のいずれかを選択します。
- internal (組み込みの API Management キャッシュを使用する場合)、
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。
いいえ prefer-external
downstream-caching-type この属性の値は次のいずれかに設定する必要があります。

- none - ダウンストリーム キャッシュは許可されません。
- private - ダウンストリーム プライベート キャッシュが許可されます。
- public - プライベートおよび共有ダウンストリーム キャッシュが許可されます。
いいえ なし
must-revalidate ダウンストリーム キャッシュが有効になっているとき、この属性によって、ゲートウェイ応答での must-revalidate キャッシュ制御ディレクティブのオンとオフを切り替えます。 いいえ true
vary-by-developer 要求に含まれているサブスクリプション キーを所有している開発者アカウントごとに応答をキャッシュする場合は、true に設定します。 はい False
vary-by-developer-groups true に設定すると、ユーザー グループごとに応答をキャッシュします。 はい False

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound
  • ポリシー スコープ: すべてのスコープ

キャッシュに格納

cache-storeポリシーは、指定されたキャッシュ設定に従って応答をキャッシュに格納します。 このポリシーを適用できるのは、応答の内容が一定期間にわたって静的である場合です。 応答のキャッシュを使用すると、バックエンド Web サーバーの帯域幅および処理の要件が低減され、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 Management 応答のキャッシュ時間を、バックエンド サービスの Cache-Control ディレクティブによって指定されたバックエンド サービスの応答キャッシュ時間と一致するように構成する方法を示します。 このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky」(クラウド カバー エピソード 177: Vlad Vinogradsky によるその他の API Management 機能の紹介) を 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;
  }"
 />

詳細については、ポリシー式およびコンテキスト変数に関する各ページを参照してください。

要素

名前 説明 必須
cache-store ルート要素。 はい

属性

名前 説明 必須 Default
duration キャッシュに格納されたエントリの有効期間 (秒単位)。 はい 該当なし
cache-response 現在の HTTP 応答をキャッシュする場合は true に設定します。 属性が省略されている場合、または false に設定されている場合は、状態コード 200 OK を含む HTTP 応答のみがキャッシュされます。 いいえ false

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: outbound
  • ポリシー スコープ: すべてのスコープ

キャッシュから値を取得

cache-lookup-value ポリシーを使用して、キーごとにキャッシュの検索を行い、キャッシュされている値を返します。 キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。

注意

このポリシーには、対応する値をキャッシュに格納ポリシーが必要です。

ポリシー ステートメント

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

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

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

要素

名前 説明 必須
cache-lookup-value ルート要素。 はい

属性

名前 説明 必須 Default
caching-type 属性の次の値のいずれかを選択します。
- internal (組み込みの API Management キャッシュを使用する場合)、
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。
いいえ prefer-external
default-value キーによるキャッシュ検索で何も見つからなかった場合に、変数に割り当てられる値。 この属性が指定されない場合は null が割り当てられます。 いいえ null
key 検索で使用するキャッシュのキー値。 はい 該当なし
variable-name 検索が成功した場合に、検索された値が割り当てられるコンテキスト変数の名前。 検索結果が見つからない場合、変数は設定されません。 はい 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

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

値をキャッシュに格納

cache-store-value は、キーごとに記憶域のキャッシュを実行します。 キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。

注意

このポリシーによって実行される、キャッシュに値を格納する操作は非同期です。 格納された値は、キャッシュから値を取得ポリシーを使用して取得できます。 ただし、キャッシュに値を格納する非同期操作がまだ進行中である可能性もあるため、格納されている値をすぐに使用できない場合があります。

ポリシー ステートメント

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

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

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

要素

名前 説明 必須
cache-store-value ルート要素。 はい

属性

名前 説明 必須 Default
caching-type 属性の次の値のいずれかを選択します。
- internal (組み込みの API Management キャッシュを使用する場合)、
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。
いいえ prefer-external
duration 指定された期間 (秒単位)、値がキャッシュされます。 はい 該当なし
key 値が格納されるキャッシュのキー。 はい 該当なし
value キャッシュされる値。 はい 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

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

キャッシュから値を削除

cache-remove-value は、キーで指定された、キャッシュされている項目を削除します。 キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。

ポリシー ステートメント


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


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

要素

名前 説明 必須
cache-remove-value ルート要素。 はい

属性

名前 説明 必須 Default
caching-type 属性の次の値のいずれかを選択します。
- internal (組み込みの API Management キャッシュを使用する場合)、
- external (「Azure API Management で外部の Azure Cache for Redis を使用する」の説明に従って、外部キャッシュを使用する場合)、
- prefer-external (構成されている場合は外部キャッシュ、そうでない場合は内部キャッシュを使用する場合)。
いいえ prefer-external
key キャッシュから削除される、前にキャッシュされた値のキー。 はい 該当なし

使用法

このポリシーは、ポリシーの以下のセクションスコープで使用できます。

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

次のステップ

ポリシーを使用する方法の詳細については、次のトピックを参照してください。