Cache Key

Cache Key（キャッシュキー）は、Cloudflare がキャッシュ内のファイルを識別する識別子です。Cache Key Template は、ある HTTP リクエストに対するその識別子を定義します。

デフォルトの Cache Key には次が含まれます。

1. 完全な URL:
   • scheme — HTTP または HTTPS
   • host — 例: www.cloudflare.com
   • クエリ文字列付き URI — 例: /logo.jpg?utm_source=newsletter
2. クライアントが送った Origin ヘッダー（CORS 対応のため）。
3. x-http-method-override、x-http-method、x-method-override ヘッダー。
4. x-forwarded-host、x-host、x-forwarded-scheme（http または https 以外の場合）、x-original-url、x-rewrite-url、forwarded ヘッダー。

カスタム Cache Key を使うと、任意のリソースのキャッシュ可否を細かく設定できます。制御は増えますが、キャッシュヒット率が下がり、キャッシュが細かく分かれることがあります。

1. Cloudflare ダッシュボードで、Cache Rules ページを開きます。

   Cache Rules を開く ↗

2. Create rule を選択します。

3. When incoming requests match で ルール式 を定義します。

4. Then の Cache eligibility で Eligible for cache を選択します。

5. ルールに Cache Key 設定を追加し、適切な Query String 設定を選びます。

6. Headers、Cookie、Host、User の設定も選べます。

7. 保存してデプロイするには Deploy を選択します。まだデプロイしない場合は Save as Draft を選択します。

Cache Key Template を変えるよくある理由は次のとおりです。

• キャッシュを分割し、1 つの URL を複数ファイルとして保存する。たとえば、URL 内の特定のクエリ文字列に応じて別ファイルを保存する。
• キャッシュを統合し、異なる HTTP リクエストを同じファイルとして保存する。たとえば、Cloudflare の Cache Key にデフォルトで付く Origin ヘッダーを除く。

Cloudflare の $scheme 変数はキャッシュ動作で重要な役割を持ちますが、意味は Cache Key の種類によって変わります。

• デフォルトの Cache Key: $scheme は オリジンのスキーム、つまり Cloudflare がオリジンサーバーへ接続するプロトコル（HTTP または HTTPS）を指します。この構成では、SSL 設定の変更（例: Flexible から Full への切り替え）がオリジンのスキームを変えます。Cache Key にオリジンのスキームが含まれるため、こうした変更はキャッシュバスト（キャッシュの無効化）を起こし、Cloudflare はオリジンからコンテンツを再取得します。

• カスタム Cache Key: $scheme は 訪問者のスキーム、つまりクライアントが Cloudflare へリクエストするときに使うプロトコルを指します。この場合、カスタム設定にオリジンのスキームを明示的に含めない限り、SSL 設定の変更は Cache Key に影響しません。

たとえば Flexible SSL では、訪問者が HTTP と HTTPS のどちらを使っても、Cloudflare は常に HTTP でオリジンへ接続します。デフォルト構成では、両プロトコルで同じ Cache Key になります。

デフォルトの Cache Key を使っている場合、SSL 設定の変更でキャッシュが無効化されることがあります。

• Off から Full、Full (strict)、Strict へ切り替えると、オリジンのスキームが HTTP から HTTPS に変わり、キャッシュバストが起きます。

• Flexible から Full、Full (strict)、Strict へ移す場合も、オリジンのスキームが HTTPS に変わり、キャッシュバストが起きます。

SSL モードを変更するときは、$scheme とキャッシュ設定の関係を把握し、想定外のキャッシュ動作を避けてください。

Cache Level の Ignore Query String は、デフォルトの Cache Key の要素をすべて含みつつ、URI のクエリ文字列だけを除いた Cache Key を作ります。たとえば http://example.com/file.jpg?something=123 と http://example.com/file.jpg?something=789 は、この場合同じ Cache Key になります。

次のフィールドで Cache Key Template を制御します。

クエリ文字列の設定は、どの URL クエリ文字列パラメーターを Cache Key に入れるかを制御します。include で特定のパラメーターを含めるか、exclude で除外できます。クエリ文字列パラメーターを含めると、その value が Cache Key に使われます。

https://www.example.com/?foo=bar のような URL でクエリ文字列 foo を含めると、Cache Key に bar が入ります。include と exclude のどちらか一方だけを指定します。

• すべてのクエリ文字列パラメーターを含める（デフォルト）には、include: "\*" を使います。
• クエリ文字列を無視するには、exclude: "\*" を使います。
• ほとんどのクエリ文字列パラメーターを含め、一部だけ除外するには exclude フィールドを使います。ほかのパラメーターは含まれる前提です。

ヘッダーの設定は、どのヘッダーを Cache Key に入れるかを制御します。クエリ文字列と同様に、特定のヘッダーを含めるか、デフォルトのヘッダーを除外できます。

ヘッダーを含めると、その値が Cache Key に入ります。たとえば HTTP リクエストに X-Auth-API-key: 12345 があり、Cache Key Template に X-Auth-API-Key ヘッダーを含めると、Cache Key に 12345 が入ります。

Include headers and selected values では、ヘッダー名とその値を Cache Key に追加できます。カスタムヘッダーでは値は任意です。次の制限付きヘッダーでは、1 から 10 個の具体的な値を含める必要があります。

• accept
• accept-charset
• accept-encoding
• accept-datetime
• accept-language
• referer
• user-agent

値自体は含めず、ヘッダーの有無だけを見るには Check presence of を使います。

現在除外できるのは Origin ヘッダーだけです。明示的に除外しない限り、Origin ヘッダーは常に含まれます。Cache Key に Origin ヘッダー ↗ を含めることは、CORS ↗ の適用に重要です。

さらに、次のヘッダーは含められません。

• キャッシュやプロキシの機能を再実装するヘッダー
  • connection
  • content-length
  • cache-control
  • if-match
  • if-modified-since
  • if-none-match
  • if-unmodified-since
  • range
  • upgrade
• ほかの Cache Key 機能が扱うヘッダー
  • cookie
  • host
• Cloudflare 固有で cf- で始まるヘッダー（例: cf-ray）
• カスタム Cache Key Template にすでに含まれるヘッダー（例: origin）

Host は、Cache Key に含める Host ヘッダーを決めます。

• Use original host（API では resolved: false）の場合、Cloudflare はオリジンへ送る HTTP リクエストの Host ヘッダーを含めます。
• Resolved host（API では resolved: true）の場合、Cloudflare はリクエストの origin IP を解決したときに使った Host ヘッダーを含めます。Origin Rule で変更されていると、実際に送ったヘッダーと異なることがあります。

query_string や header と同様に、cookie は Cache Key に入れる Cookie を制御します。Cookie の値を含めるか、特定の Cookie の有無だけを確認できます。

Cloudflare 固有の Cookie は含められません。Cloudflare の Cookie は __cf で始まります（例: __cflb）。

ユーザー機能のフィールドは、エンドユーザー（クライアント）に関する情報を Cache Key に追加します。

• device_type は User Agent に基づき、リクエストを mobile、desktop、tablet に分類します
• geo は IP アドレスから導いたクライアントの国を含めます
• lang はクライアントが送った Accept-Language ヘッダーに含まれる最初の言語コードを含めます

Cache Key のオプションの利用可否は、プランによって異なります。

Cloudflare Trace で、リクエストにどの Cache Key 設定が適用されたかを確認できます。Trace ツールでリクエストを送ったとき、キャッシュから配信されていれば Cache Parameters にキャッシュヒットと表示されます。View parameter detail を選ぶと、使われた Cache Key のプロパティを確認できます。

Prefetch は カスタム Cache Key と併用できません。Cache Rules では、カスタム Cache Key ですべてのアセットをキャッシュします。一方、Prefetch は常にデフォルトの Cache Key を使います。そのためキーが一致しません。