Zasada ResponseCache

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Buforuje dane z zasobu backendu, zmniejszając liczbę żądań kierowanych do tego zasobu. Ponieważ aplikacje wysyłają żądania do tego samego identyfikatora URI, możesz używać tej zasady do zwracania odpowiedzi z pamięci podręcznej, zamiast przekazywania ich do serwera backendu. Zasada ResponseCache może poprawić wydajność interfejsu API przez krótszy czas oczekiwania i ruch w sieci.

Interfejs ResponseCache jest prawdopodobnie przydatny, gdy dane backendu używane przez interfejs API są aktualizowane tylko okresowo. Załóżmy na przykład, że masz interfejs API, który ujawnia dane z raportu o pogodzie odświeżane tylko co 10 minut. Używając ResponseCache do zwracania odpowiedzi z pamięci podręcznej między odświeżeniami, możesz zmniejszyć liczbę żądań docierających do backendu. Zmniejsza to też liczbę przeskoków sieci.

W przypadku krótkoterminowego buforowania ogólnego przeznaczenia rozważ użycie zasady wypełniania pamięci podręcznej. Ta zasada jest używana w połączeniu z zasadą Sprawdź pamięć podręczną (do odczytu wpisów w pamięci podręcznej) i zasadą unieważniania pamięci podręcznej (do unieważniania wpisów).

Przykłady

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>

Odwołanie do elementu

Odwołanie do elementów opisuje elementy i atrybuty zasady.

<?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>

Atrybuty <ResponseCache>

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

Tabela poniżej zawiera opis atrybutów wspólnych dla wszystkich elementów nadrzędnych zasad:

Element <DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <CacheKey>

Konfiguruje unikalny wskaźnik do danych przechowywanych w pamięci podręcznej.

Rozmiar klucza pamięci podręcznej nie może przekraczać 2 KB.

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

<CacheKey> tworzy nazwę każdego fragmentu danych przechowywanych w pamięci podręcznej. Klucz jest często ustawiany za pomocą wartości z nagłówków encji lub parametrów zapytania. W takich przypadkach atrybut ref tego elementu powinien określać zmienną zawierającą wartość klucza.

W czasie działania wartości <KeyFragment> są dołączane na początku wartości elementu <Scope> lub <Prefix>. Na przykład w poniższym przykładzie powstaje klucz pamięci podręcznej UserToken__apiAccessToken__<value_of_client_id>:

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

Elementu <CacheKey> używasz w połączeniu z elementami <Prefix> i <Scope>. Więcej informacji znajdziesz w artykule Praca z kluczami pamięci podręcznej.

Element <CacheLookupTimeoutInSeconds>

Określa liczbę sekund, po których nieudane wyszukiwanie w pamięci podręcznej będzie uznawane za brak w pamięci podręcznej. W takim przypadku przepływ jest wznawiany po ścieżce pominięcia w pamięci podręcznej.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

Element <CacheResource>

Określa pamięć podręczną, w której mają być przechowywane wiadomości. Pomiń ten element, aby korzystać z uwzględnionej współdzielonej pamięci podręcznej. Aby móc administracyjnie czyścić wpisy zawarte w pamięci podręcznej, podaj nazwę zasobu CacheResource. Więcej informacji na ten temat znajdziesz w artykule Pamięci podręczne.

<CacheResource>cache_to_use</CacheResource>

Więcej informacji o konfigurowaniu pamięci podręcznych znajdziesz w artykule o tworzeniu i edytowaniu pamięci podręcznej środowiska.

Element <CacheKey>/<KeyFragment>

Określa wartość, która powinna być uwzględniona w kluczu pamięci podręcznej, tworząc przestrzeń nazw na potrzeby dopasowywania żądań do odpowiedzi w pamięci podręcznej.

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

Może to być klucz (wpisana przez Ciebie statyczna nazwa) lub wartość (dynamiczny wpis ustawiony przez odwoływanie się do zmiennej). Wszystkie określone fragmenty (plus prefiks) są połączone, aby utworzyć klucz pamięci podręcznej.

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

Elementu <KeyFragment> używasz w połączeniu z elementami <Prefix> i <Scope>. Więcej informacji znajdziesz w artykule Praca z kluczami pamięci podręcznej.

Atrybuty

Element <CacheKey>/<Prefiks>

Określa wartość, która ma być używana jako prefiks klucza pamięci podręcznej.

<Prefix>prefix_string</Prefix>

Użyj tej wartości zamiast <Scope>, jeśli chcesz określić własną wartość zamiast wartości określonej przez <Scope>. Jeśli został określony, <Prefix> dołącza na początku wartość klucza pamięci podręcznej do wpisów zapisanych w pamięci podręcznej. Wartość elementu <Prefix> zastępuje wartość elementu <Scope>.

Elementu <Prefix> używasz w połączeniu z elementami <CacheKey> i <Scope>. Więcej informacji znajdziesz w artykule Praca z kluczami pamięci podręcznej.

Element <ExcludeErrorResponse>

Obecnie ta zasada domyślnie zapisuje w pamięci podręcznej odpowiedzi HTTP z każdym możliwym kodem stanu. Oznacza to, że w pamięci podręcznej są przechowywane zarówno odpowiedzi zakończone powodzeniem, jak i błędem. Na przykład odpowiedzi z kodami stanu 2xx i 3xx są domyślnie przechowywane w pamięci podręcznej.

Ustaw ten element na true, jeśli nie chcesz buforować odpowiedzi z kodami stanu błędu HTTP. Jeśli ten element ma wartość Prawda, w pamięci podręcznej będą przechowywane tylko odpowiedzi z kodami stanu od 200 do 205. To są jedyne kody stanu HTTP, które Edge liczy jako kody „sukcesu”. Nie możesz zmienić tego powiązania.

Opis wzorców pamięci podręcznej odpowiedzi, w których ten element jest przydatny, znajdziesz w tym poście na karcie Społeczność.

Uwaga: w przyszłej wersji (co zostanie ustalone) domyślne ustawienie tego elementu zmieni się na „true” (prawda). Szczegóły znajdziesz w informacjach o wersji Apigee.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Element <ExpirySettings>

Określa, kiedy wpis w pamięci podręcznej powinien wygasnąć. Gdy występuje, atrybut <TimeoutInSeconds> zastępuje zarówno <TimeOfDay>, jak i <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>

Element <ExpirySettings>/<ExpiryDate>

Określa datę wygaśnięcia wpisu w pamięci podręcznej. Użyj formularza mm-dd-yyyy. Gdy ten element jest obecny, jego element równorzędny (<TimeoutInSeconds>) zastępuje <ExpiryDate>.

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

Atrybuty

<ExpiryDate ref="" />

Element <ExpirySettings>/<TimeOfDay>

Pora dnia, o której wpis w pamięci podręcznej powinien wygasnąć. Użyj formularza hh:mm:ss . Gdy ten element jest obecny, jego element równorzędny (<TimeoutInSeconds>) zastępuje <TimeOfDay>.

Podaj godzinę w formacie GG:mm:ss, gdzie GG oznacza godzinę na zegarze 24-godzinnym. np. 14:30:00 dla 14:30 po południu.

Pora dnia domyślne ustawienia regionalne i strefa czasowa będą różnić się w zależności od miejsca, w którym działa kod (nie wiadomo, kiedy konfigurujesz zasadę). Informacje o konfigurowaniu ustawień regionalnych znajdziesz w artykule Tworzenie i edytowanie pamięci podręcznej środowiska.

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

Atrybuty

Element <ExpirySettings>/<TimeoutInSec>

Liczba sekund, po których wpis pamięci podręcznej powinien wygasnąć.

Element <ExpirySettings>/<TimeoutInSeconds>

Liczba sekund, po których wpis pamięci podręcznej powinien wygasnąć. Gdy jest obecny, zastępuje on elementy równorzędne (<TimeOfDay> i <ExpiryDate>).

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

Uwaga: podaj domyślny czas oczekiwania do użycia w przypadku, gdy ref nie otrzyma wartości z duration_variable.

Atrybuty

Element <Scope>

Wyliczenie używane do utworzenia prefiksu klucza pamięci podręcznej, gdy element <Prefix> nie zawiera elementu <CacheKey>.

<Scope>scope_enumeration</Scope>

Ustawienie <Scope> określa klucz pamięci podręcznej dołączany na początku zgodnie z wartością <Scope>. Gdy zakres jest ustawiony na Exclusive, klucz pamięci podręcznej miałby na przykład taką postać: orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

Jeśli w elemencie <CacheKey> występuje element <Prefix>, zastępuje on wartość elementu <Scope>. Prawidłowe wartości obejmują wyliczenia poniżej.

Elementu <Scope> używasz w połączeniu z elementami <CacheKey> i <Prefix>. Więcej informacji znajdziesz w artykule Praca z kluczami pamięci podręcznej.

Dopuszczalne wartości

apifactory__test__weatherapi__16__default__apiAccessToken

Element <PomińCacheLookup>

Definiuje wyrażenie, które, jeśli ma wartość prawda w czasie działania, określa, że należy pominąć wyszukiwanie w pamięci podręcznej, a pamięć podręczna powinna zostać odświeżona. Obejrzyj też ten film o korzystaniu z funkcji PomińCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Jeśli w poniższym przykładzie zmienna pomijania pamięci podręcznej ma wartość „prawda” w nagłówku przychodzącym, wyszukiwanie w pamięci podręcznej jest pomijane, a pamięć podręczna jest odświeżana.

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

Element <PomińCacheDuration>

Definiuje wyrażenie, które, jeśli ma wartość prawda w czasie działania, określa, że zapis w pamięci podręcznej ma być pomijany. Obejrzyj też ten film o korzystaniu z funkcji PomińCacheużywanie.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Jeśli na przykład kod stanu odpowiedzi ma wartość 400 lub wyższą, ten kod pomija zapisywanie w pamięci podręcznej:

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

Element <UseAcceptHeader>

Ustaw jako true, aby do klucza pamięci podręcznej wpisu żądania odpowiedzi były dołączane wartości z nagłówków Accept odpowiedzi.

Do obliczania klucza pamięci podręcznej Edge używa nagłówków żądań Accept, Accept-Encoding, Accept-Language i Accept-Charset. Dzięki temu klient nie uzyska dostępu do typu mediów, o który nie prosił.

Rozważ na przykład, czy 2 żądania pochodzą z tego samego adresu URL, gdzie pierwsze z nich akceptuje kod gzip, a drugie nie. Pierwsze żądanie zostanie zapisane w pamięci podręcznej, a wpis z pamięci podręcznej będzie prawdopodobnie odpowiedzią w formacie gzip. Drugie żądanie odczyta wartość z pamięci podręcznej, a następnie może zwrócić wpis w formacie gzip klientowi, który nie jest w stanie odczytać pliku gzip.

Więcej informacji znajdziesz w artykule Konfigurowanie klucza pamięci podręcznej.

<UseAcceptHeader>false</UseAcceptHeader>

Element <UseResponseCacheHeaders>

Ustaw wartość true, aby przy ustawianiu „czasu życia danych” (TTL) odpowiedzi w pamięci podręcznej były brane pod uwagę nagłówki odpowiedzi HTTP. Jeśli tak jest, podczas ustawiania czasu życia Edge uwzględnia wartości tych nagłówków odpowiedzi i porównuje je z wartościami ustawionymi przez <ExpirySettings>:

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

Więcej informacji znajdziesz w artykule Ustawianie ważności wpisów w pamięci podręcznej.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Zastosowanie

Maksymalny rozmiar każdego obiektu w pamięci podręcznej to 256 KB. Szczegółowe informacje o tym, jak Edge przetwarza pamięć podręczną, znajdziesz w dokumentacji wewnętrznej.

Dzięki konfiguracji w zasadzie ResponseCache możesz sprawić, że Edge będzie uwzględniać nagłówki odpowiedzi HTTP przy ustawianiu daty ważności wpisów z pamięci podręcznej i kluczy pamięci podręcznej. W tej sekcji opisujemy, jak za pomocą zasady z nagłówkami zarządzać wygaśnięciem pamięci podręcznej i kluczami pamięci podręcznej.

Więcej informacji o tym, jak Edge obsługuje nagłówki odpowiedzi z zasadą ResponseCache, znajdziesz w artykule na temat obsługi nagłówków odpowiedzi HTTP.

Ustawianie daty wygaśnięcia pozycji w pamięci podręcznej

Podobnie jak w przypadku zasady uzupełniania pamięci podręcznej, za pomocą elementu <ExpirySettings> możesz ustawić datę ważności wpisu dotyczącego pamięci podręcznej odpowiedzi (czas życia). W zasadzie ResponseCache możliwe jest, aby przeglądarka Edge uwzględniała nagłówki odpowiedzi, jeśli są one dostępne.

Aby używać nagłówków odpowiedzi, ustaw wartość elementu <UseResponseCacheHeaders> na „true”. To ustawienie powoduje, że Edge uwzględnia nagłówki odpowiedzi, porównuje je z wartością ustawioną przez <ExpirySettings>, a następnie używa najniższej wartości między nimi. Podczas analizowania nagłówków odpowiedzi Edge wybiera dostępną wartość w sposób opisany w tym artykule:

Załóżmy, że odpowiedź jest przechowywana w pamięci podręcznej z tymi wartościami:

• Brak wartości parametru Cache-Control s-maxage
• Wartość Cache-Control max-age wynosząca 300
• Data: Expires w ciągu 3 dni
• Wartość <ExpirySettings> TimeoutInSeconds wynosząca 600.

W tym przypadku jako wartość TTL zostanie użyta wartość Cache-Control max-age, ponieważ jest niższa od wartości <ExpirySettings> i nie ma wartości Cache-Control s-maxage (która ma pierwszeństwo przed wartością max-age).

Konfigurowanie klucza pamięci podręcznej

Podobnie jak w przypadku ogólnych zasad dotyczących pamięci podręcznej, np. zasady wypełniania pamięci podręcznej, z ResponseCache korzystasz z elementów <CacheKey> i <Scope> do konfigurowania tworzenia kluczy pamięci podręcznej dla wpisów dotyczących pamięci podręcznej. ResponseCache zwiększa użyteczność kluczy pamięci podręcznej przez dołączanie do wartości kluczowych nagłówków Accept.

Ogólne informacje na temat konfigurowania kluczy pamięci podręcznej znajdziesz w artykule Praca z kluczami pamięci podręcznej. Informacje o korzystaniu z nagłówków Accept znajdziesz <UseAcceptHeader>.

Informacje o szyfrowaniu pamięci podręcznej

Brzegowy dla chmury publicznej: pamięć podręczna jest szyfrowana tylko w organizacjach korzystających z PCI i HIPAA. Szyfrowanie w tych organizacjach jest konfigurowane podczas obsługi administracyjnej organizacji.

Zmienne przepływu

Podczas wykonywania zasady ResponseCache są wypełniane poniższe wstępnie zdefiniowane zmienne przepływu. Więcej informacji o zmiennych przepływu znajdziesz w artykule Informacje o zmiennych.

Kody błędów

W tej sekcji opisujemy komunikaty o błędach i zmienne przepływu ustawiane, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły błędów dla serwera proxy. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Prefiks kodu błędu

Nie dotyczy

Błędy w czasie wykonywania

Ta zasada nie powoduje błędów podczas działania.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Zmienne błędów

Nie dotyczy

Przykładowa odpowiedź na błąd

Nie dotyczy

Schemat

Każdy typ zasady jest definiowany przez schemat XML (.xsd). Schematy zasad są dostępne na GitHubie.