1. Homepage
  2. Flex Gateway (1.5)
  3. 内部ポリシーディレクトリ

  4. HTTP キャッシュ

HTTP キャッシュポリシー

ポリシー名

HTTP キャッシュ

概要

API 実装から HTTP 応答をキャッシュする

カテゴリ

サービス品質

使用可能な最小 Flex Gateway バージョン

v1.0.0

返される状況コード

このポリシーの戻りコードは存在しません

概要

HTTP キャッシュポリシーでは、HTTP 応答をキャッシュして再利用できます。これらの応答をキャッシュすると、ユーザー要求の応答時間が短縮され、バックエンドの負荷が軽減されます。たとえば、要求に対する応答が変更される可能性の低いエンドポイントをバックエンドで公開する場合、HTTP キャッシュポリシーを使用して、HTTP 応答を再利用し、バックエンド要求処理をバイパスできます。

ポリシーのパラメーターの設定

Flex Gateway のローカルモード

ローカルモードでは、宣言型の設定ファイルを使用して HTTP キャッシュポリシーを API に適用します。以下のポリシー定義とパラメーターの表を参照してください。

- policyRef:
    name: http-caching-flex
  config:
    httpCachingKey: <string> // OPTIONAL, default: "#[attributes.requestPath]"
    maxCacheEntries: <int> // OPTIONAL, default: 10000
    ttl: <int> // OPTIONAL, default: 600
    useHttpCacheHeaders: <bool> // OPTIONAL, default: true
    invalidationHeader: <string> // OPTIONAL, default: ""
    requestExpression: <string> // OPTIONAL, default: "#[attributes.method == 'GET' or attributes.method == 'HEAD']"
    responseExpression: <string> // OPTIONAL, default: "#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]"
    distributed: <bool> // OPTIONAL, default: false
    persistCache: <bool> // OPTIONAL, default: false
パラメーター 必須または省略可能 デフォルト値 説明

httpCachingKey

省略可能

#[attributes.requestPath]

DataWeave 式

maxCacheEntries

省略可能

10000

キャッシュ内に特定の期間保存できるエントリの最大数を指定します。

ttl

省略可能

600

キャッシュの 1 つのエントリの有効期限が切れるまでの時間 (秒) を指定します。

useHttpCacheHeaders

省略可能

true

Cache-Control ヘッダーディレクティブの使用を有効にします。

invalidationHeader

省略可能

空の文字列

1 つのエントリまたはキャッシュ全体を無効化するために使用されるヘッダーを指定する文字列。

requestExpression

省略可能

#[attributes.method == 'GET' or attributes.method == 'HEAD']

キャッシュされる要求を決定するために使用される DataWeave 式 (応答は条件が true の場合にのみキャッシュされる)。

responseExpression

省略可能

#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]

キャッシュされる応答を決定するために使用される DataWeave 式 (応答は条件が true の場合のみキャッシュされる)

distributed

省略可能

false

クラスター内の各ノードでキャッシュが分散されるように設定

persistCache

省略可能

false

レプリカの各再起動間でキャッシュが維持されるように設定

リソースの設定例

- policyRef:
    name: http-caching-flex
  config:
    httpCachingKey: "#[attributes.requestPath]"
    maxCacheEntries: 10000
    ttl: 500
    useHttpCacheHeaders: false
    requestExpression: "#[attributes.method == 'GET' or attributes.method == 'HEAD']"
    responseExpression: "#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]"

分散キャッシュリソースの設定例

分散キャッシュでは、共有ストレージを有効にする必要があります。共有ストレージについての詳細は、​「接続モードでの Flex Gateway の共有ストレージの設定」​を参照してください。

---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: shared-storage-redis
spec:
  sharedStorage:
    redis:
      address: redis:6379
      user: user
      password: pass
      DB: 1

---
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-http-caching
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-http
  policyRef:
    kind: Extension
    name: http-caching-flex
  config:
    httpCachingKey: "#[attributes.method ++ attributes.requestPath]"
    useHttpCacheHeaders: true
    maxCacheEntries: 100
    ttl: 600
    distributed: true
    persistCache: true
    invalidationHeader: AGW-CACHE-CONTROL

Flex Gateway の接続モード

UI から HTTP キャッシュポリシーを API に適用する場合は、次のパラメーターを設定できます。

パラメーター Description (説明) 必須

HTTP Caching Key (HTTP キャッシュキー)

DataWeave 式。 デフォルト値: #[attributes.requestPath]

はい

Maximum Cache Entries (最大キャッシュエントリ)

キャッシュ内に特定の期間保存できるエントリの最大数を指定します。 デフォルト値: 10000

はい

Entry Time To Live (エントリ存続期間)

キャッシュの 1 つのエントリの有効期限が切れるまでの時間 (秒) を指定します。 デフォルト値: 600

はい

Distributed (分散)

クラスター内の各ノードでキャッシュが分散されるように設定します。 CloudHub を使用している場合、アプリケーションをデプロイするときに Object Store v2 を有効にします。 デフォルト値: false

はい

Persistent Cache (永続キャッシュ)

Flex Gateway インスタンスの各再起動間でキャッシュが維持されるように設定します。 CloudHub を使用している場合、アプリケーションをデプロイするときに Object Store v2 を有効にします。 デフォルト値: false

はい

Follow HTTP Caching directives (HTTP キャッシュディレクティブに従う)

Cache-Control ヘッダーディレクティブの使用を有効にします。 デフォルト値: true

はい

Invalidation Header (無効化ヘッダー)

1 つのエントリまたはキャッシュ全体を無効化するために使用されるヘッダーの名前。

いいえ

Conditional Request Caching Expression (条件付き要求キャッシュ式)

キャッシュされる要求を決定するために使用される DataWeave 式 (応答は条件が true の場合にのみキャッシュされる)。 デフォルト値: #[attributes.method == 'GET' or attributes.method == 'HEAD']

いいえ

Conditional Response Caching Expression (条件付き応答キャッシュ式)

キャッシュされる応答を決定するために使用される DataWeave 式 (応答は条件が true の場合のみキャッシュされる)。 デフォルト値: #[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]

いいえ

ポリシーのしくみ

HTTP 要求がエンドポイントに到達した後の次の処理は、要求がまだキャッシュにないのか (キャッシュミス)、すでにあるのか (キャッシュヒット) によって決まります。

キャッシュミス

キャッシュミスの場合、HTTP キャッシュポリシーは、送信された要求に対する応答がすでにキャッシュされているかどうかをチェックします。要求がバックエンドに到達したら、キャッシュミスの場合にのみプロセスが開始されます。次の図は、このシナリオで発生するイベントのフローを示しています。

http policy cache miss

  1. クライアント (ユーザー) が API に要求を送信します。

  2. 要求は、HTTP キャッシュポリシーに到達するまでポリシーチェーンの他のポリシーを進みます。

  3. HTTP キャッシュポリシーは、要求がすでにオブジェクトストアにあるかどうかをチェックします。ない場合は、キャッシュミスプロセスが開始されます。

  4. 要求は、他の残りのポリシーのチェーンを引き続き進みます。

  5. 要求がバックエンドに到達し、必要なすべての処理を実行します。

  6. バックエンドが応答し、応答はポリシーチェーンを戻ります。

  7. 応答が HTTP キャッシュポリシーに到達します。

  8. キャッシュで再度オブジェクトストアがヒットし、後で再利用できるように要求の​キー​を保存しようとします。

  9. 応答は、ポリシーチェーンの残りのポリシーを引き続き進みます。

  10. 応答がクライアントに返されます。

キャッシュヒット

キャッシュヒットの場合、HTTP キャッシュポリシーは、オブジェクトストアのキーを検索し、要求に対する応答が​保存済みエントリ​としてすでにキャッシュされていることを検出します。要求がバックエンドに向けてポリシーチェーンを進むことはなく、キャッシュされた応答が再利用されます。

キャッシュヒットの場合、キャッシュ後にポリシーチェーンで実行される必要のあるすべてのポリシーはそれ以降実行されません。

http policy cache hit

  1. クライアント (ユーザー) が API に要求を送信します。

  2. 要求は、HTTP キャッシュポリシーに到達するまで他のポリシーを通過します。

  3. HTTP キャッシュポリシーは、要求がすでにキャッシュにあるかどうかを確認します。

  4. オブジェクトストアで​キー​が見つかり、保存された応答が返されます。

  5. 応答は、最後のポリシーに到達するまでポリシーチェーンの残りのポリシーを引き続き進みます。

  6. キャッシュされた応答がクライアントに返されます。

保存済みエントリ

保存済みエントリ​は、キャッシュされた HTTP 応答です。キャッシュには、最大 1 MB のシリアル化可能データと入力ストリームを保存できます。値がこの制限を超えると、読み取りは停止し、値は保存されません。

HTTP Caching Key (HTTP キャッシュキー)

キャッシュは辞書として機能し、そこではキャッシュに保存された各応答が​キー​と呼ばれる文字列に関連付けられます。たとえば、式 #[attributes.headers['key']] では、​key​ というヘッダーがエントリキーとして使用されます。

キャッシュサイズとエントリ有効期限

キャッシュには、指定された数のエントリを特定の期間保持できます。この数は、​Maximum Cache Entries​ プロパティを使用して設定できます。各保存済みエントリは、一定時間キャッシュメモリに保持されます。その後、エントリは期限切れになり、再度処理する必要があります。この有効期限は、​存続期間​ (TTL) と呼ばれます。

キャッシュが最大項目保存数に達したときもエントリの有効期限がトリガーされます。このシナリオが発生すると、FIFO (先入れ先出し) 条件を使用してエントリが削除されます。つまり、最も早くキャッシュに到達したエントリは、TTL 値にまだ達していなくても削除されます。

分散キャッシュ

キャッシュの各エントリは、​Distributed​ オプション (表を参照) を使用して、クラスター内の各ノードや Runtime Manager の複数のワーカーで共有できます。このオプションが有効になっていない場合、各ノードには独自のキャッシュメモリが割り当てられます。

永続キャッシュ

永続キャッシュでは、Flex レプリカが再起動しても、キャッシュの保存済みエントリを保持できます。

永続的なストアを使用するように設定された HTTP キャッシュポリシーを持つインスタンスのバージョンをアップグレードすると、ポリシーは以前のバージョンで保存されたエントリを維持しようとします。ただし、最悪のシナリオでは、キャッシュ内のエントリが無効になり、新しい要求の到着時にキャッシュが再入力されます。キャッシュ内のエントリのこの操作は自動的に実行され、ユーザーが意識することはありません。

HTTP キャッシュディレクティブ

HTTP キャッシュポリシーは、キャッシュをより詳細に制御するために次のヘッダーを考慮に入れて RFC-7234​ プロトコルのいくつかの HTTP ディレクティブを解釈します。

  • Cache-Control

  • Expires

  • Date

  • Age

Cache-Control

Cache-Control​ ヘッダーは要求または応答に存在します。ヘッダーに対して可能な値は次のとおりです。これらの値は、カンマで区切って組み合わせることができます。

  • 要求:

    • no-cache

応答は検索されませんが、キャッシュに直接保存されます。

  • no-store

応答はキャッシュに保存されません。ただし、応答がキャッシュ内にすでに存在する場合は、ポリシーがその応答を返します。

  • 応答:

    • no-store​、​no-cache​、​private

どの値でも応答はキャッシュに保存されません。

  • max-age=<integer>​、​s-maxage=<integer>

<integer>​ プレースホルダーは、応答がキャッシュに残ることができる時間 (秒) を示す有効な整数に置き換える必要があります。両方のパラメーターが定義されている場合、​max-age​ よりも ​s-maxage​ が優先されます。

ポリシーでグローバル存続期間 (TTL) 値も定義されている場合、ヘッダーで指定されている時間がグローバル TTL よりも少ないと、これらのヘッダー値がポリシーで設定されているグローバル TTL よりも優先されます。

Expires (有効期限)

存在する場合、このヘッダーでキャッシュ内のエントリの有効期限を指定します。​max-age​ ディレクティブまたは ​s-maxage​ ディレクティブが指定されている場合、このヘッダーは無視されます。ヘッダー値は RFC-1123​ のとおりに定義する必要があります。

Date (日付)

date​ ヘッダーが RFC-1123​ に従って定義されている場合、応答の作成日時が指定されます。定義されていない場合、​date​ ヘッダーが要求の受信時刻で追加されます。このヘッダーは、Cache-Control ヘッダーの ​max-age​ および ​s-maxage​ ディレクティブに定義された値と一緒に使用されます。

Age (存続期間)

age​ ヘッダーは、date ヘッダーに指定されたキャッシュされている応答の作成以降の経過時間 (秒) を示します。このヘッダーはポリシーによって計算され、キャッシュから取得された各応答に追加されます。

有効期限は、​cache-control​、​date​、​expires​ ヘッダーを使用して計算されます。ただし、計算された有効期限がエントリの TTL 値で指定された存続時間を超える場合、キャッシュエントリの有効期限が切れます。

無効化

HTTP キャッシュポリシーで ​invalidate​ ヘッダーが設定されている場合、キャッシュ内のエントリが無効化され、要求が再度処理されます。[Invalidation Header (無効化ヘッダー)] 設定のヘッダーの名前を指定して、オプションを有効にします。ヘッダーの値には、​invalidate​ オプションのみを設定できます。

このオプションは、キーが現在の要求に一致するエントリを無効化します。 invalidate-all​ このオプションは、キャッシュからすべてのエントリを無効化します。

たとえば、ポリシーで要求の次の値が設定されているとします。

  • HTTP Caching Key​ (HTTP キャッシュキー): "#[attributes.requestPath]"

  • Invalidation header​ (無効化ヘッダー): "myInvalidationHeader"

次のコマンドは、キャッシュからキーが "/my/policy" のエントリを無効化します。

curl http://<MyAppURL>/my/policy -H “myInvalidationHeader:invalidate”

次の要求は、キャッシュからすべてのエントリを無効化します。

curl http://<MyAppURL>/my/policy -H “myInvalidationHeader:invalidate-all”

条件付きキャッシュ

条件付きキャッシュでは、エントリをキャッシュに保存するために満たす必要がある一連の条件を設定できます。条件付きキャッシュパラメーターが設定されていない場合、すべての受信要求の応答がキャッシュに保存されます。設定されている場合、各要求のパラメーターが評価されて、現在の要求の応答を保存する必要があるかどうかが判断されます。

条件付き要求式の場合、デフォルトでは、HTTP メソッドの ​GET​ または ​HEAD​ による受信要求に対する応答のみがキャッシュされます。条件付き応答式の場合、デフォルトでは、 RFC-7231​ で指定された状況コードのみがキャッシュされます。

デフォルト値についての詳細は、​「ポリシーのパラメーターの設定」​を参照してください。

FAQ

キーの評価がエラーになった場合はどうなりますか?

特定の要求の式の評価がエラーになった場合、ポリシーは有効にならず、要求はポリシーチェーンの次の受け入れ先に引き続き進みます。

このポリシーで応答の一部のみを保存できますか?

いいえ。ただし、このポリシーの前に別のポリシーを適用して、応答を変更することはできます。

あるパラメーターではキャッシュ内で応答を検索するように設定し、別のパラメーターではその逆のアクションを実行するように設定した場合、どうなりますか?

これは、Cache-Control ヘッダーに no-store ディレクティブがある状態で応答をキャッシュに保存するように設定したときと同じになります。

この場合、応答は保存されません。キャッシュに応答を保存したり、キャッシュの応答を検索したりできるようにするには、Cache-Contro ヘッダーとキャッシュの両方を設定する必要があります。

省略可能なパラメーターを定義しないとどうなりますか?

invalidation​ ヘッダーを設定していない場合、要求のキャッシュを無効化できません。 また、要求式や応答式を設定していない場合、キャッシュはすべての要求に対して使用され、すべての応答がキャッシュに保存されます (式 #[true])。

[Invalidation header (無効化ヘッダー)] の値を変更できますか?

いいえ。変更できるのはヘッダー名のみです。