Правила ResponseCache

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Кеширует данные из внутреннего ресурса, уменьшая количество запросов к нему. Если приложения отправляют запросы к одному и тому же URI, вы можете использовать это правило, чтобы возвращать кешированные ответы, а не пересылать запросы на внутренний сервер. Правило ResponseCache позволяет повысить производительность API за счет сокращения задержки и сетевого трафика.

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

Для краткосрочного кеширования общего назначения рекомендуется использовать правило заполнения кеша. Это правило используется вместе с правилом "Кэш поиска" (для чтения записей кэша) и правилом "Аннулировать кэш" (для аннулирования записей).

Примеры

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

Сведения об элементах

В справочнике по элементам описаны элементы и атрибуты правил.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
    <DisplayName>Response Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" />
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>
    </ExpirySettings>
    <CacheResource>cache_to_use</CacheResource>
    <CacheLookupTimeoutInSeconds/>
    <ExcludeErrorResponse/>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
    <UseAcceptHeader/>
    <UseResponseCacheHeaders/>
</ResponseCache>

Атрибуты <ResponseCache>

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>

Элемент <CacheKey>

Настраивает уникальный указатель на фрагмент данных, хранящийся в кеше.

Размер ключей кеша ограничен 2 КБ.

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

<CacheKey> создает название для каждого фрагмента данных, хранящихся в кеше. Ключ часто задается с помощью значения из заголовков объекта или параметров запроса. В таких случаях атрибут ref элемента должен указывать на переменную, содержащую значение ключа.

Во время выполнения к значениям <KeyFragment> добавляется значение элемента <Scope> или значение <Prefix>. Например, следующий код приведет к созданию ключа кеша UserToken__apiAccessToken__<value_of_client_id>:

<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>

Элемент <CacheKey> используется вместе с элементами <Prefix> и <Scope>. Подробнее о работе с ключами кеша…

Элемент <CacheLookupTimeoutInSeconds>

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

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

Элемент <CacheResource>

Указывает, в каком кеше должны храниться сообщения. Если вы не укажете этот элемент, будет использоваться встроенный общий кеш. Если вы хотите иметь возможность административно удалять записи, содержащиеся в кеше, укажите CacheResource по имени. Подробнее о кеше…

<CacheResource>cache_to_use</CacheResource>

Подробнее о том, как создавать и изменять кеш среды…

Элемент <CacheKey>/<KeyFragment>

Указывает значение, которое должно быть включено в ключ кеша, создавая пространство имен для сопоставления запросов с ответами, хранящимися в кеше.

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

Это может быть ключ (статическое название, которое вы задаете) или значение (динамическая запись, заданная с помощью переменной). Все указанные фрагменты (плюс префикс) объединяются в ключ кеша.

<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />

Элемент <KeyFragment> используется вместе с элементами <Prefix> и <Scope>. Подробнее о работе с ключами кеша…

Атрибуты

Элемент <CacheKey>/<Prefix>

Указывает значение, которое будет использоваться в качестве префикса ключа кеша.

<Prefix>prefix_string</Prefix>

Используйте это значение вместо <Scope>, если вы хотите указать собственное значение, а не значение, перечисленное в <Scope>. Если задано, <Prefix> добавляет значение ключа кеша для записей, которые сохраняются в кеше. Значение элемента <Prefix> переопределяет значение элемента <Scope>.

Элемент <Prefix> используется вместе с элементами <CacheKey> и <Scope>. Подробнее о работе с ключами кеша…

Элемент <ExcludeErrorResponse>

Сейчас по умолчанию это правило кеширует HTTP-ответы с любым возможным кодом статуса. Это означает, что в кеше сохраняются как успешные, так и ошибочные ответы. Например, по умолчанию кешируются ответы с кодами статуса 2xx и 3xx.

Установите для этого элемента значение true, если вы не хотите, чтобы ответы целевого сервера с кодами статуса ошибок HTTP кешировались. Если этот элемент имеет значение true, будут кешироваться только ответы с кодами статуса от 200 до 205. Это единственные коды статуса HTTP, которые Edge считает кодами успешного выполнения. Изменить эту связь нельзя.

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

Примечание. В одной из будущих версий значение по умолчанию для этого элемента будет изменено на true. Подробнее о примечаниях к выпуску Apigee…

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Элемент <ExpirySettings>

Указывает, когда должна истечь запись в кеше. Если присутствует, <TimeoutInSeconds> переопределяет <TimeOfDay> и <ExpiryDate>.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

Элемент <ExpirySettings>/<ExpiryDate>

Указывает дату, когда запись в кеше должна устареть. Используйте форму mm-dd-yyyy. Если этот элемент присутствует, его братский элемент <TimeoutInSeconds> переопределяет <ExpiryDate>.

<ExpirySettings>
    <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
</ExpirySettings>

Атрибуты

<ExpiryDate ref="" />

Элемент <ExpirySettings>/<TimeOfDay>

Время суток, когда срок действия записи в кеше должен истечь. Используйте форму hh:mm:ss . Если этот элемент присутствует, его братский элемент <TimeoutInSeconds> переопределяет <TimeOfDay>.

Укажите время в формате ЧЧ:мм:сс, где ЧЧ – час в 24-часовом формате. Например, 14:30:00 для 14:30.

Для времени суток региональные настройки и часовой пояс по умолчанию будут зависеть от того, где выполняется код (это неизвестно при настройке правила). Подробнее о том, как настроить региональные параметры…

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Атрибуты

Элемент <ExpirySettings>/<TimeoutInSec>

Количество секунд, по истечении которых запись в кеше должна стать недействительной.

Элемент <ExpirySettings>/<TimeoutInSeconds>

Количество секунд, по истечении которых запись в кеше должна стать недействительной. Если этот элемент присутствует, он переопределяет другие элементы того же уровня, <TimeOfDay> и <ExpiryDate>.

<ExpirySettings>
    <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
</ExpirySettings>

Примечание. Укажите значение времени ожидания по умолчанию, которое будет использоваться, если параметр ref не получит значение от duration_variable.

Атрибуты

Элемент <Scope>

Перечисление, используемое для создания префикса ключа кеша, если в элементе <CacheKey> не указан элемент <Prefix>.

<Scope>scope_enumeration</Scope>

Настройка <Scope> определяет ключ кеша, который добавляется в начало в соответствии со значением <Scope>. Например, если область действия задана как Exclusive, ключ кеша будет иметь следующий вид:orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

Если в элементе <CacheKey> присутствует элемент <Prefix>, он имеет приоритет над значением элемента <Scope>. Допустимые значения перечислены ниже.

Элемент <Scope> используется вместе с элементами <CacheKey> и <Prefix>. Подробнее о работе с ключами кеша…

Допустимые значения

apifactory__test__weatherapi__16__default__apiAccessToken

Элемент <SkipCacheLookup>

Определяет выражение, которое, если оно оценивается как истинное во время выполнения, указывает, что поиск в кеше следует пропустить и кеш следует обновить. Также посмотрите это видео об использовании SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

В приведенном ниже примере, если переменная bypass-cache имеет значение true во входящем заголовке, поиск в кеше пропускается и кеш обновляется.

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

Элемент <SkipCachePopulation>

Определяет выражение, которое, если оно во время выполнения оценивается как истинное, указывает, что запись в кеш должна быть пропущена. Также посмотрите это видео об использовании SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Например, следующий код пропустит запись в кеш, если код статуса ответа будет 400 или выше:

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

Элемент <UseAcceptHeader>

Если задано значение true, к ключу кеша записи кеша ответа будут добавлены значения из заголовков Accept ответа.

При расчете ключа кеша Edge использует заголовки запроса Accept, Accept-Encoding, Accept-Language и Accept-Charset. Это позволяет избежать ситуации, когда клиент получает медиаконтент, который он не запрашивал.

Например, если с одного и того же URL поступают два запроса, причем первый принимает gzip, а второй – нет, Первый запрос будет сохранен в кеше, и запись в кеше (вероятно) будет представлять собой ответ, сжатый с помощью gzip. Второй запрос прочитает значение из кеша и может вернуть клиенту, который не поддерживает gzip, запись в формате gzip.

Подробнее о настройке ключа кеша…

<UseAcceptHeader>false</UseAcceptHeader>

Элемент <UseResponseCacheHeaders>

Если задать значение true, при определении времени жизни ответа в кеше будут учитываться заголовки HTTP-ответа. Если это так, Edge учитывает значения следующих заголовков ответа, сравнивая их со значениями, заданными с помощью <ExpirySettings> при установке времени жизни:

• Cache-Control s-maxage
• Cache-Control max-age
• Expires

Подробнее о настройке срока действия записи в кеше…

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Примечания

Максимальный размер каждого кешированного объекта – 256 КБ. Подробную информацию о том, как Edge обрабатывает кеш, можно найти в статье Внутренние механизмы кеширования.

С помощью конфигурации в правиле ResponseCache можно настроить включение заголовков HTTP-ответа в установку срока действия записи кеша и ключей кеша. В этом разделе описано, как использовать правила с заголовками для управления сроком действия кеша и ключами кеша.

Подробнее о том, как Edge обрабатывает заголовки ответов с помощью правила ResponseCache, рассказывается в статье Поддержка заголовков HTTP-ответов.

Как задать срок действия записи кеша

Как и в случае с правилом заполнения кеша, вы можете задать срок действия записи в кеше ответов (время жизни) с помощью элемента <ExpirySettings>. В правилах ResponseCache можно также настроить Edge так, чтобы он учитывал заголовки ответов, если они есть.

Чтобы использовать заголовки ответов, задайте для элемента <UseResponseCacheHeaders> значение true. Этот параметр позволяет Edge учитывать заголовки ответов, сравнивать их со значением, заданным с помощью <ExpirySettings>, а затем использовать наименьшее из двух значений. При обработке заголовков ответов Edge выбирает значение, доступное следующим образом:

Предположим, что в кеше сохранен ответ со следующими значениями:

• Нет значения Cache-Control s-maxage
• Значение Cache-Control max-age равно 300.
• Expires через три дня
• Значение <ExpirySettings> TimeoutInSeconds равно 600.

В этом случае для TTL будет использоваться значение Cache-Control max-age, поскольку оно меньше значения <ExpirySettings> и отсутствует значение Cache-Control s-maxage (которое имеет приоритет над max-age).

Как настроить ключ кеша

Как и в случае с общими правилами кеширования, например Populate Cache policy, в ResponseCache вы используете элементы <CacheKey> и <Scope>, чтобы настроить создание ключа кеша для записей кеша. С помощью ResponseCache можно сделать ключи кеша более информативными, добавив к значениям ключей заголовки Accept из ответов.

Общую информацию о настройке ключей кеша можно найти в статье Как работать с ключами кеша. Подробнее об использовании заголовков Accept<UseAcceptHeader>…

О шифровании кеша

Edge для общедоступного облака. Кеш шифруется только в организациях, в которых включены PCI и HIPAA. Шифрование для таких организаций настраивается во время инициализации организации.

Переменные процесса

При выполнении правила ResponseCache заполняются следующие стандартные переменные потока: Подробнее о переменных потока…

Коды ошибок

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

Префикс кода ошибки

Н/Д

Ошибки времени выполнения

Это правило не вызывает ошибок во время выполнения.

Ошибки развертывания

Эти ошибки могут возникать при развертывании прокси-сервера, содержащего это правило.

Переменные ошибок

Н/Д

Пример ответа об ошибке

Н/Д

Схема

Каждый тип правил определяется схемой XML (.xsd). Схемы правил доступны на GitHub.