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
| パラメーター | 必須または省略可能 | デフォルト値 | 説明 |
|---|---|---|---|
|
省略可能 |
|
DataWeave 式 |
|
省略可能 |
10000 |
キャッシュ内に特定の期間保存できるエントリの最大数を指定します。 |
|
省略可能 |
600 |
キャッシュの 1 つのエントリの有効期限が切れるまでの時間 (秒) を指定します。 |
|
省略可能 |
true |
Cache-Control ヘッダーディレクティブの使用を有効にします。 |
|
省略可能 |
空の文字列 |
1 つのエントリまたはキャッシュ全体を無効化するために使用されるヘッダーを指定する文字列。 |
|
省略可能 |
|
キャッシュされる要求を決定するために使用される DataWeave 式 (応答は条件が true の場合にのみキャッシュされる)。 |
|
省略可能 |
|
キャッシュされる応答を決定するために使用される DataWeave 式 (応答は条件が true の場合のみキャッシュされる) |
|
省略可能 |
false |
クラスター内の各ノードでキャッシュが分散されるように設定 |
|
省略可能 |
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 式。
デフォルト値: |
はい |
Maximum Cache Entries (最大キャッシュエントリ) |
キャッシュ内に特定の期間保存できるエントリの最大数を指定します。
デフォルト値: |
はい |
Entry Time To Live (エントリ存続期間) |
キャッシュの 1 つのエントリの有効期限が切れるまでの時間 (秒) を指定します。
デフォルト値: |
はい |
Distributed (分散) |
クラスター内の各ノードでキャッシュが分散されるように設定します。
デフォルト値: |
はい |
Persistent Cache (永続キャッシュ) |
Flex Gateway インスタンスの各再起動間でキャッシュが維持されるように設定します。
デフォルト値: |
はい |
Follow HTTP Caching directives (HTTP キャッシュディレクティブに従う) |
Cache-Control ヘッダーディレクティブの使用を有効にします。
デフォルト値: |
はい |
Invalidation Header (無効化ヘッダー) |
1 つのエントリまたはキャッシュ全体を無効化するために使用されるヘッダーの名前。 |
いいえ |
Conditional Request Caching Expression (条件付き要求キャッシュ式) |
キャッシュされる要求を決定するために使用される DataWeave 式 (応答は条件が true の場合にのみキャッシュされる)。
デフォルト値: |
いいえ |
Conditional Response Caching Expression (条件付き応答キャッシュ式) |
キャッシュされる応答を決定するために使用される DataWeave 式 (応答は条件が true の場合のみキャッシュされる)。
デフォルト値: |
いいえ |
ポリシーのしくみ
HTTP 要求がエンドポイントに到達した後の次の処理は、要求がまだキャッシュにないのか (キャッシュミス)、すでにあるのか (キャッシュヒット) によって決まります。
キャッシュミス
キャッシュミスの場合、HTTP キャッシュポリシーは、送信された要求に対する応答がすでにキャッシュされているかどうかをチェックします。要求がバックエンドに到達したら、キャッシュミスの場合にのみプロセスが開始されます。次の図は、このシナリオで発生するイベントのフローを示しています。
-
クライアント (ユーザー) が API に要求を送信します。
-
要求は、HTTP キャッシュポリシーに到達するまでポリシーチェーンの他のポリシーを進みます。
-
HTTP キャッシュポリシーは、要求がすでにオブジェクトストアにあるかどうかをチェックします。ない場合は、キャッシュミスプロセスが開始されます。
-
要求は、他の残りのポリシーのチェーンを引き続き進みます。
-
要求がバックエンドに到達し、必要なすべての処理を実行します。
-
バックエンドが応答し、応答はポリシーチェーンを戻ります。
-
応答が HTTP キャッシュポリシーに到達します。
-
キャッシュで再度オブジェクトストアがヒットし、後で再利用できるように要求のキーを保存しようとします。
-
応答は、ポリシーチェーンの残りのポリシーを引き続き進みます。
-
応答がクライアントに返されます。
キャッシュヒット
キャッシュヒットの場合、HTTP キャッシュポリシーは、オブジェクトストアのキーを検索し、要求に対する応答が保存済みエントリとしてすでにキャッシュされていることを検出します。要求がバックエンドに向けてポリシーチェーンを進むことはなく、キャッシュされた応答が再利用されます。
キャッシュヒットの場合、キャッシュ後にポリシーチェーンで実行される必要のあるすべてのポリシーはそれ以降実行されません。
-
クライアント (ユーザー) が API に要求を送信します。
-
要求は、HTTP キャッシュポリシーに到達するまで他のポリシーを通過します。
-
HTTP キャッシュポリシーは、要求がすでにキャッシュにあるかどうかを確認します。
-
オブジェクトストアでキーが見つかり、保存された応答が返されます。
-
応答は、最後のポリシーに到達するまでポリシーチェーンの残りのポリシーを引き続き進みます。
-
キャッシュされた応答がクライアントに返されます。
保存済みエントリ
保存済みエントリは、キャッシュされた HTTP 応答です。キャッシュには、最大 1 MB のシリアル化可能データと入力ストリームを保存できます。値がこの制限を超えると、読み取りは停止し、値は保存されません。
HTTP Caching Key (HTTP キャッシュキー)
キャッシュは辞書として機能し、そこではキャッシュに保存された各応答がキーと呼ばれる文字列に関連付けられます。たとえば、式 #[attributes.headers['key']] では、key というヘッダーがエントリキーとして使用されます。定義済みの DataWeave 変数を含めて、文字列を返す任意の DataWeave 式を使用できます。
キャッシュサイズとエントリ有効期限
キャッシュには、指定された数のエントリを特定の期間保持できます。この数は、Maximum Cache Entries プロパティを使用して設定できます。各保存済みエントリは、一定時間キャッシュメモリに保持されます。その後、エントリは期限切れになり、再度処理する必要があります。この有効期限は、存続期間 (TTL) と呼ばれます。
キャッシュが最大項目保存数に達したときもエントリの有効期限がトリガーされます。このシナリオが発生すると、FIFO (先入れ先出し) 条件を使用してエントリが削除されます。つまり、最も早くキャッシュに到達したエントリは、TTL 値にまだ達していなくても削除されます。
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 (無効化ヘッダー)] の値を変更できますか?
いいえ。変更できるのはヘッダー名のみです。