← Cloudflare Cache / cache / concepts

Vary

Vary ↗ HTTP заголовок ответа сообщает Cloudflare, что источник может отдавать разные ответы для одного и того же URL в зависимости от заголовков запроса. Например, источник может отдавать разные языковые версии в зависимости от Accept-Language, или разные форматы контента в зависимости от Accept.

По умолчанию CDN Cloudflare формирует ключи кеша из URL запроса и нескольких специфических заголовков. Cache Rules может заранее добавить в cache key другие свойства запроса. Vary заголовок ответа позволяет источнику определять, какие заголовки запроса важны, когда Cloudflare получает ответ.

На этой странице объясняется, как Vary влияет на кеширование. Чтобы настроить Vary, используйте Vary в настройках Cache Rules, или cf.vary для вложенных запросов Workers.

Эта функция отличается от Vary for images, которая отдаёт варианты форматов изображений в зависимости от Accept заголовок с помощью отдельного правила вариантов кеша.

Если Cloudflare кэширует ответ с Vary заголовка перечисленные заголовки запроса становятся частью ключа кэша для этого ответа, в соответствии с поведением HTTP-кэширования, описанным в RFC 9111 ↗. В таком случае у одного URL может быть несколько кешированных версий, каждая из которых выбирается по значениям заголовков запроса, указанным в заголовке источника Vary ответ.

Cloudflare не варьирует каждый кешированный ответ просто потому, что в Cache Rule настроен заголовок Vary. Ответ источника должен содержать Vary заголовок. Затем Cloudflare использует настроенное действие для каждого заголовка из списка, чтобы определить, какое значение заголовка запроса добавляется в ключ кэша.

Например, предположим, что источник возвращает такой ответ:

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

Это сообщает Cloudflare, что значение Accept-Language заголовок запроса должен входить в ключ кеша.

С accept-language настроен на normalize, эти два запроса могут использовать одну и ту же закешированную версию:

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.

Если ответ варьируется в зависимости от нескольких заголовков, Cloudflare включает каждый из этих заголовков в ключ кэша. Например, ответ с Vary: Accept, Accept-Language использует одновременно настроенный accept значение и настроенное accept-language значение для выбора закешированного ответа.

Если ответ источника не содержит Vary заголовка, Cloudflare кэширует ответ как обычно. Если ответ источника включает Vary имя заголовка, настроенное на bypass кеш, Cloudflare не сохраняет этот ответ.

Каждый настроенный заголовок использует одно из трёх действий:

normalize уменьшает число лишних кешированных версий, преобразуя эквивалентные значения заголовков запроса в одно и то же значение ключа кеша.

Например, эти два Accept заголовков могут приводиться к одному и тому же значению:

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

passthrough использует необработанное значение заголовка запроса при выборе закешированной версии. Семантически эквивалентные значения всё равно могут создавать разные закешированные версии, если байты отличаются.

Например, при passthrough, эти два запроса выбирают разные закешированные версии:

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

Используйте passthrough только тогда, когда точное значение заголовка важно для вашего источника и должно быть важным для кеша.

bypass указывает Cloudflare не кешировать ответ, когда заголовок источника Vary ответ включает это имя заголовка.

Например, если ваша конфигурация задаёт user-agent к bypass, ответ с этим заголовком не кешируется:

Vary: User-Agent

Vary normalization представляет собой нормализацию, которая выполняется, если задано действие normalize. Это влияет на то, как Cloudflare выбирает кешированную версию, а для некоторых заголовков и на то, что Cloudflare передаёт источнику.

Нормализация не обязательна, но рекомендуется для большинства случаев использования, так как она уменьшает количество кешированных версий и повышает коэффициент попаданий в кеш.

Если для заголовка задано действие normalize, Cloudflare использует нормализованное значение для выбора закешированной версии. Нормализация может быть с потерями: она может менять порядок значений, отбрасывать значения качества, приводить значения к нижнему регистру или удалять записи, не входящие в настроенный список разрешений.

Для Accept, Accept-Language, а также Accept-Encoding с Respect Strong ETags включённом состоянии Cloudflare может также передавать источнику нормализованное значение заголовка. Это обеспечивает соответствие между ответом источника и значением cache key, которое Cloudflare использует для кеширования.

Например, если accept-language нормализует эти два запроса до en,fr, Cloudflare передает Accept-Language: en,fr источнику при промахе кеша или ревалидации:

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

Передача нормализованного значения не позволяет Cloudflare сохранять ответ, созданный для одного исходного значения заголовка, под более общим нормализованным значением, которое другой запрос впоследствии может ошибочно повторно использовать.

Эта перезапись запроса к источнику применяется к:

• Accept
• Accept-Language
• Accept-Encoding, только если включена функция Respect Strong ETags

Эта перезапись не применяется к:

• Заголовки, настроенные как passthrough
• Заголовки, настроенные как bypass
• Другие общие заголовки

Эта перезапись происходит до того, как Cloudflare получает ответ источника, поэтому она основана на настройках вашего Cache Rule. Если Accept, Accept-Language, или Accept-Encoding настроен с normalize, Cloudflare переписывает этот заголовок запроса при пересылке источнику, даже если в итоговом ответе источника этот заголовок не указан в Vary. Выбор кеша и его обход по-прежнему зависят от заголовка ответа источника Vary заголовок.

Если в результате нормализации значение заголовка становится пустым (например, потому что ни одно из значений запроса не соответствует настроенному media_types или languages список: Cloudflare удаляет этот заголовок из запроса к источнику.

Cloudflare нормализует Accept заголовок запроса в следующих шагах:

1. Приводить MIME-типы к нижнему регистру.
2. Удаляет необязательные пробелы.
3. Сортировка MIME-типов по значению качества. Типы с одинаковым значением качества сортируются в алфавитном порядке.
4. Удаляет параметры.

Значения качества используются для сортировки, а затем удаляются из нормализованного значения. q=0 сохраняется, поскольку означает «неприемлемо» и должен оставаться отличимым от значения с низким приоритетом.

Можно указать необязательный media_types список. Если он указан, любой MIME-тип, отсутствующий в списке, удаляется из нормализованного значения.

Cloudflare нормализует Accept-Language заголовок запроса в следующих шагах:

1. Приводить языки к нижнему регистру.
2. Удаляет необязательные пробелы.
3. Сортировка языков по значению качества. Языки с одинаковым значением качества сортируются в алфавитном порядке.
4. Удаляет параметры.
5. Удаляет варианты региона. Например, en-US становится en. Если присутствует несколько региональных вариантов одного языка, они объединяются в один пункт.

Значения качества используются для сортировки, а затем удаляются из нормализованного значения. q=0 сохраняется, поскольку означает «неприемлемо» и должен оставаться отличимым от значения с низким приоритетом.

Можно указать необязательный languages список. Если он указан, любой язык, отсутствующий в списке, удаляется из нормализованного значения. Если элемент списка указывает региональный вариант и в заголовке запроса есть соответствующий элемент, региональный вариант сохраняется в нормализованном значении.

По умолчанию CDN Cloudflare переопределяет Accept-Encoding заголовок на основе включённых кодировок сжатия. Если включено сжатие Brotli, Accept-Encoding передаваемый источнику, составляет gzip, br. Если сжатие Brotli не включено, Accept-Encoding передаваемый источнику, составляет gzip. После этого Cloudflare может повторно сжимать кешированные ресурсы в зависимости от заголовка посетителя Accept-Encoding. Подробности см. в Заголовки ETag.

Это поведение можно отключить, включив Respect Strong ETags. При включённом Respect Strong ETags заголовок посетителя Accept-Encoding передается источнику вместо переопределения сжатия Cloudflare. Если нормализация Vary включена для Accept-Encoding, нормализованное значение используется как для выбора закешированной версии, так и в качестве значения, передаваемого источнику.

Поскольку Cloudflare управляет Accept-Encoding если параметр Respect Strong ETags отключен, Accept-Encoding нормализация переписывает запрос к источнику только тогда, когда включена функция Respect Strong ETags.

Cloudflare нормализует Accept-Encoding заголовок запроса в следующих шагах:

1. Приводить кодировки к нижнему регистру.
2. Удаляет необязательные пробелы.
3. Сортировка кодировок по значению качества. Кодировки с одинаковым значением качества сортируются в алфавитном порядке.
4. Удаляет параметры.

Значения качества используются для сортировки, а затем удаляются из нормализованного значения. q=0 сохраняется, поскольку означает «неприемлемо» и должен оставаться отличимым от значения с низким приоритетом.

Для любого заголовка, кроме Accept, Accept-Language, а также Accept-Encoding, Cloudflare не знает семантику поля. Нормализация ограничена преобразованиями, безопасными для любого заголовка:

• Несколько строк одного и того же заголовка объединяются в одно значение, разделённое запятыми, в порядке получения.
• Необязательные пробелы вокруг каждого значения удаляются.

Значения не переупорядочиваются, не приводятся к нижнему регистру, не дедуплицируются и не изменяются иным образом, поскольку порядок и содержимое произвольного заголовка может иметь значение.

Например, эти две строки полей заголовка:

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

При выборе закэшированной версии Cloudflare объединяет эти значения следующим образом: Value2,Value1. Заголовок, передаваемый источнику, не переписывается.

При очистке URL удаляются все кешированные версии этого URL. Не нужно отправлять отдельный очистка запрос на каждый Vary значение заголовка. Это применимо к методам очистки, нацеленным на кешированный объект, таким как очистка по URL-адресу, тегу, имени хоста, префиксу или полная очистка.

Изменение конфигурации Vary само по себе не очищает кешированное содержимое. Поскольку новая конфигурация Vary может изменить то, как выбираются кешированные версии, запросы могут не находить совпадений в кеше и заново наполнять его по новым ключам кеша, пока старые записи не истекут или не будут очищены.