Cache

Cache API ↗ を使うと、Cloudflare グローバルネットワーク ↗ のキャッシュへの読み書きを細かく制御できます。

Cache API はグローバルに使えますが、キャッシュの内容は発生元データセンターの外には複製されません。GET /users のレスポンスは発生元データセンターにキャッシュできますが、明示的に作成しない限り、別のデータセンターには存在しません。

カスタムドメインにデプロイした Workers では、cache 操作が使えます。Pages functions も同様で、カスタムドメインと *.pages.dev ドメインのどちらでも使えます。

ただし、Cloudflare Workers ダッシュボードエディターと Playground のプレビューでは、Cache API の操作は効果がありません。Cloudflare Access の手前にある Workers では、現時点で Cache API は利用できません。

caches.default API は、Web ブラウザーの Cache API の影響を強く受けていますが、重要な違いがあります。たとえば、Cloudflare Workers ランタイムは単一のグローバルキャッシュオブジェクトを公開します。

let cache = caches.default;
await cache.match(request);

caches.open ↗ メソッドで、追加の Cache インスタンスを作成および管理できます。

let myCache = await caches.open('custom:cache');
await myCache.match(request);

Cache API の実装は、put() に渡したレスポンスの次の HTTP ヘッダーを尊重します。

• Cache-Control
  • キャッシュディレクティブを制御します。Cloudflare Cache-Control Directives と一致します。Cache-Control ディレクティブがない場合の HTTP レスポンスコードと TTL の一覧は、Edge TTL を参照してください。
• Cache-Tag
  • あとからタグでリソースをパージできます。
• ETag
  • cache.match() が If-None-Match による条件付きリクエストを評価できるようにします。
• Expires 文字列
  • リソースが無効になるタイミングを指定する文字列です。
• Last-Modified
  • cache.match() が If-Modified-Since による条件付きリクエストを評価できるようにします。

Web ブラウザーの Cache API とは異なり、リクエストやレスポンスのヘッダーは尊重されません。

cache.put(request, response);

• put(request, response) : Promise

  • 指定したリクエストをキーとして、レスポンスをキャッシュに追加しようとします。キャッシュへの保存成否にかかわらず、undefined に解決する Promise を返します。

• request string | Request

  • キーとなる文字列、または Request オブジェクトです。文字列を渡すと、新しい Request オブジェクトの URL として解釈されます。

• response Response

  • 指定したキーの下に保存する Response オブジェクトです。

cache.put は、次の場合にエラーをスローします。

• 渡した request のメソッドが GET 以外です。
• 渡した response の status が 206 Partial Content ↗ です。
• 渡した response にヘッダー Vary: * が含まれます。Vary ヘッダーの値がアスタリスク（*）です。詳細は Cache API の仕様 ↗ を参照してください。

Cache-Control がキャッシュしないよう指示している場合、またはレスポンスが大きすぎる場合、cache.put は 413 エラーを返します。

cache.match(request, options);

• match(request, options) : Promise<Response | undefined>

  • そのリクエストをキーとするレスポンスオブジェクトを包んだ Promise を返します。

• request string | Request

  • 検索キーとして使う文字列、または Request オブジェクトです。文字列は、新しい Request オブジェクトの URL として解釈されます。

• options

  • 取りうるプロパティは ignoreMethod（Boolean）だけです。true の場合、実際の値にかかわらずリクエストを GET として扱います。

ブラウザーの Cache API と違い、Cloudflare Workers は match() の ignoreSearch や ignoreVary オプションをサポートしません。この動作は、put() 時にクエリ文字列や HTTP ヘッダーを除くことで実現できます。

Cache API の実装は、match() に渡したリクエストの次の HTTP ヘッダーを尊重します。

• Range

  • 一致するレスポンスに Content-Length ヘッダーがある場合、206 レスポンスになります。レスポンスに Accept-Ranges ヘッダーがあってもなくても、Cloudflare のキャッシュは常に range リクエストを尊重します。

• If-Modified-Since

  • 一致するレスポンスに Last-Modified ヘッダーがあり、その値が If-Modified-Since で指定した時刻より前の場合、304 レスポンスになります。

• If-None-Match

  • 一致するレスポンスに ETag ヘッダーがあり、その値が If-None-Match のいずれかの値と一致する場合、304 レスポンスになります。

要求したコンテンツがない、または期限切れの場合、cache.match は 504 エラーレスポンスを生成します。Cache API はこの 504 を Worker スクリプトへ直接は公開せず、代わりに undefined を返します。ただし、基になる 504 は Cloudflare Logs では確認できます。

Cloudflare Logs を使っている場合、RequestSource が edgeWorkerCacheAPI の 504 レスポンスが見えることがあります。キャッシュ済みアセットがない、または期限切れの場合、これは想定どおりです。なお、edgeWorkerCacheAPI リクエストは、Cache Analytics などほかのビューではすでに除外されています。これらのリクエストを除外する、またはサイトのエンドユーザーからのリクエストだけに絞り込むには、エンドユーザーで絞り込む を参照してください。

cache.delete(request, options);

• delete(request, options) : Promise<boolean>

キャッシュから Response オブジェクトを削除し、Boolean レスポンスの Promise を返します。

• true: レスポンスはキャッシュされていたが、削除された
• false: 削除時点でレスポンスはキャッシュになかった

• request string | Request

  • 検索キーとして使う文字列、または Request オブジェクトです。文字列は、新しい Request オブジェクトの URL として解釈されます。

• options object

  • 取りうるプロパティは ignoreMethod（Boolean）だけです。実際の値にかかわらず、リクエストメソッドを GET として扱います。

• キャッシュの仕組み
• 例: fetch() でキャッシュする
• 例: Cache API を使う
• 例: POST リクエストをキャッシュする