Vary

Vary ↗ HTTP レスポンスヘッダーは、同じ URL でもリクエストヘッダーに応じて異なるレスポンスをオリジンが返せることを Cloudflare に伝えます。たとえば、オリジンは Accept-Language に基づいて言語を変えたり、Accept に基づいてコンテンツ形式を変えたりできます。

デフォルトでは、Cloudflare の CDN はリクエストの URL と一部の特定ヘッダーから キャッシュキー を組み立てます。Cache Rules では、ほかのリクエスト属性を事前にキャッシュキーへ追加できます。Vary レスポンスヘッダーがあると、Cloudflare がレスポンスを受け取ったときに、どのリクエストヘッダーが重要かをオリジン側で決められます。

このページでは、Vary がキャッシュにどう影響するかを説明します。Vary を設定するには、Cache Rules の設定にある Vary を使うか、Workers のサブリクエストでは cf.vary を使います。

この機能は Vary for Images とは別です。Vary for Images は、別の cache variants ルールを通じて、Accept ヘッダーに基づく画像形式のバリアントを配信します。

Cloudflare が Vary ヘッダー付きのレスポンスをキャッシュすると、列挙されたリクエストヘッダーは、RFC 9111 ↗ で説明されている HTTP キャッシュの振る舞いに従い、そのレスポンスのキャッシュキーの一部になります。同じ URL に複数のキャッシュ版を持てます。それぞれは、オリジンの Vary レスポンスで指定されたリクエストヘッダー値で選ばれます。

Cache Rule で Vary を設定したからといって、Cloudflare がキャッシュ済みレスポンスすべてを Vary するわけではありません。オリジンレスポンスに Vary ヘッダーが必要です。そのうえで Cloudflare は、列挙された各ヘッダーに対する設定済みアクションを使い、どのリクエストヘッダー値をキャッシュキーへ追加するかを決めます。

たとえば、オリジンが次のレスポンスを返すとします。

Vary: Accept-Language
Cache-Control: public, max-age=3600

これは、Accept-Language リクエストヘッダーの値をキャッシュキーの一部にすべきだと Cloudflare に伝えます。

accept-language を normalize に設定していると、次の 2 つのリクエストは同じキャッシュ版を使えます。

Accept-Language: en-US, fr;q=0.8
Accept-Language: fr;q=0.8, en-GB

どちらのリクエストヘッダーも、同じ言語優先順位 en,fr に正規化されます。正規化後の値が異なるリクエスト（例: Accept-Language: fr, en;q=0.8）は、同じ URL の別のキャッシュ版を作成または選択します。

レスポンスが複数ヘッダーで Vary する場合、Cloudflare は列挙された各ヘッダーをキャッシュキーに含めます。たとえば Vary: Accept, Accept-Language のレスポンスは、設定した accept の値と accept-language の値の両方を使って、キャッシュ済みレスポンスを選びます。

オリジンレスポンスに Vary ヘッダーがない場合、Cloudflare は通常どおりレスポンスをキャッシュします。オリジンレスポンスの Vary ヘッダー名がキャッシュを bypass するよう設定されている場合、Cloudflare はそのレスポンスを保存しません。

設定する各ヘッダーは、次の 3 つのアクションのいずれかを使います。

normalize は、同等のリクエストヘッダー値を同じキャッシュキー値へ変換し、不要なキャッシュ版を減らします。

たとえば、次の 2 つの Accept ヘッダーは同じ値に正規化できます。

Accept: text/html, application/json;q=0.9
Accept: application/json;q=0.9, text/html

passthrough は、キャッシュ版を選ぶときに生のリクエストヘッダー値を使います。意味が同じ値でも、バイトが異なれば別のキャッシュ版になります。

たとえば passthrough では、次の 2 つのリクエストは別のキャッシュ版を選びます。

Accept: text/html, application/json
Accept: application/json, text/html

passthrough は、ヘッダーの正確な値がオリジンにとって重要で、キャッシュでも重要であるべき場合にだけ使います。

bypass は、オリジンの Vary レスポンスにそのヘッダー名が含まれるとき、レスポンスをキャッシュしないよう Cloudflare に指示します。

たとえば、設定で user-agent を bypass にしている場合、次のヘッダーを持つレスポンスはキャッシュされません。

Vary: User-Agent

Vary の正規化は、設定したアクションが normalize のときに行う正規化です。Cloudflare がキャッシュ版を選ぶ方法に影響し、一部のヘッダーではオリジンへ転送する内容にも影響します。

正規化は任意ですが、ほとんどの導入では推奨します。キャッシュ版の数を減らし、キャッシュヒット率を上げます。

ヘッダーのアクションが normalize のとき、Cloudflare は正規化後の値でキャッシュ版を選びます。正規化は情報が失われることがあります。値の並べ替え、quality 値の削除、小文字化、設定した許可リストにないエントリの削除などです。

Accept、Accept-Language、および Respect Strong ETags を有効にした Accept-Encoding では、Cloudflare が正規化後のヘッダー値をオリジンへ転送することもあります。これにより、オリジンが生成するレスポンスと、Cloudflare がキャッシュに使うキャッシュキー値が一致します。

たとえば、accept-language が次の 2 つのリクエストを en,fr に正規化する場合、キャッシュミスまたは再検証のとき、Cloudflare はオリジンへ Accept-Language: en,fr を転送します。

Accept-Language: en-US, fr;q=0.8
Accept-Language: fr;q=0.8, en-GB

正規化後の値を転送することで、ある生ヘッダー値向けに生成されたレスポンスを、別のリクエストが誤って再利用できる広い正規化値の下に保存するのを防ぎます。

このオリジンリクエストの書き換えが適用されるのは、次です。

• Accept
• Accept-Language
• Accept-Encoding（Respect Strong ETags が有効な場合のみ）

この書き換えが適用されないのは、次です。

• passthrough に設定したヘッダー
• bypass に設定したヘッダー
• その他の一般的なヘッダー

この書き換えは、Cloudflare がオリジンレスポンスを受け取る前に起きるため、Cache Rule の設定に基づきます。Accept、Accept-Language、または Accept-Encoding が normalize で設定されている場合、オリジンの最終レスポンスの Vary にそのヘッダーがなくても、Cloudflare はオリジンへ転送するときにそのリクエストヘッダーを書き換えます。キャッシュ版の選択とバイパスは、引き続きオリジンレスポンスの Vary ヘッダーに依存します。

正規化の結果ヘッダーが空になる場合（たとえば、リクエストのどの値も設定した media_types または languages リストに一致しない場合）、Cloudflare はそのヘッダーをオリジンリクエストから削除します。

Cloudflare は Accept リクエストヘッダーを、次の手順で正規化します。

1. MIME タイプを小文字に変換します。
2. 任意の空白を取り除きます。
3. quality 値で MIME タイプを並べ替えます。同じ quality 値のタイプはアルファベット順です。
4. パラメーターを取り除きます。

quality 値は並べ替えに使ったあと、正規化後の値からは削除されます。q=0 は「受け入れない」を意味し、優先度の低い値と区別する必要があるため残します。

任意の media_types リストを指定できます。指定した場合、リストにない MIME タイプは正規化後の値から削除されます。

Cloudflare は Accept-Language リクエストヘッダーを、次の手順で正規化します。

1. 言語を小文字に変換します。
2. 任意の空白を取り除きます。
3. quality 値で言語を並べ替えます。同じ quality 値の言語はアルファベット順です。
4. パラメーターを取り除きます。
5. 地域バリアントを取り除きます。たとえば en-US は en になります。同じ言語の地域バリアントが複数ある場合は、1 つの項目にまとめます。

quality 値は並べ替えに使ったあと、正規化後の値からは削除されます。q=0 は「受け入れない」を意味し、優先度の低い値と区別する必要があるため残します。

任意の languages リストを指定できます。指定した場合、リストにない言語は正規化後の値から削除されます。リストの項目が地域バリアントを指定していて、リクエストヘッダーに一致する項目がある場合、正規化後の値でもその地域バリアントを残します。

デフォルトでは、Cloudflare の CDN は、有効な圧縮エンコーディングに基づいて Accept-Encoding ヘッダーを上書きします。Brotli 圧縮が有効な場合、オリジンへ転送する Accept-Encoding は gzip, br です。Brotli 圧縮が無効な場合、オリジンへ転送する Accept-Encoding は gzip です。その後 Cloudflare は、訪問者の Accept-Encoding に基づいてキャッシュ済みアセットを再圧縮できます。詳細は ETag ヘッダー を参照してください。

この動作は、Respect Strong ETags を有効にするとオフにできます。Respect Strong ETags が有効な場合、Cloudflare の圧縮上書きではなく、訪問者の Accept-Encoding がオリジンへ転送されます。Accept-Encoding の Vary 正規化が有効な場合、正規化後の値はキャッシュ版の選択と、オリジンへ転送する値の両方に使われます。

Respect Strong ETags がオフのとき、Accept-Encoding は Cloudflare が制御します。そのため Accept-Encoding の正規化がオリジンリクエストを書き換えるのは、Respect Strong ETags がオンのときだけです。

Cloudflare は Accept-Encoding リクエストヘッダーを、次の手順で正規化します。

1. エンコーディングを小文字に変換します。
2. 任意の空白を取り除きます。
3. quality 値でエンコーディングを並べ替えます。同じ quality 値のエンコーディングはアルファベット順です。
4. パラメーターを取り除きます。

quality 値は並べ替えに使ったあと、正規化後の値からは削除されます。q=0 は「受け入れない」を意味し、優先度の低い値と区別する必要があるため残します。

Accept、Accept-Language、Accept-Encoding 以外のヘッダーについて、Cloudflare はそのフィールドの意味を知りません。正規化は、任意のヘッダーに対して安全な変換に限られます。

• 同じヘッダーの複数行は、受信順のまま、カンマ区切りの 1 つの値にまとめます。
• 各値の前後の任意の空白は取り除きます。

値の並べ替え、小文字化、重複排除、その他の変更は行いません。任意ヘッダーでは、順序と内容が意味を持つことがあるためです。

たとえば、次の 2 つのヘッダー行があるとします。

X-Custom-Header: Value2
X-Custom-Header: Value1

キャッシュ版を選ぶとき、Cloudflare はこれらの値を Value2,Value1 としてまとめます。オリジンへ転送するヘッダーは書き換えません。

URL をパージすると、その URL のキャッシュ版がすべてパージされます。Vary ヘッダー値ごとに別の パージ リクエストを送る必要はありません。これは、URL、タグ、ホスト名、プレフィックスによるパージ、またはすべてパージなど、キャッシュオブジェクトを対象とするパージ方法に適用されます。

Vary の設定を変えても、それ自体ではキャッシュ済みコンテンツはパージされません。新しい Vary 設定はキャッシュ版の選び方を変えることがあるため、古いキャッシュエントリが期限切れになるかパージされるまで、リクエストはミスし、新しいキャッシュキーで再投入されることがあります。