Zasada ResponseCache

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Przechowuje w pamięci podręcznej dane z zasobu backendu, co zmniejsza liczbę żądań do tego zasobu. Gdy aplikacje wysyłają żądania do tego samego identyfikatora URI, możesz użyć tej zasady, aby zwracać odpowiedzi z pamięci podręcznej zamiast przekazywać te żądania do serwera backendu. Zasady ResponseCache mogą poprawić wydajność interfejsu API dzięki zmniejszeniu czasu oczekiwania i ruchu w sieci.

Pamięć podręczna odpowiedzi będzie prawdopodobnie najbardziej przydatna, gdy dane backendu używane przez interfejs API są aktualizowane tylko okresowo. Załóżmy na przykład, że masz interfejs API, który udostępnia dane prognozy pogody 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 również liczbę przeskoków w sieci.

Do krótkoterminowego buforowania ogólnego przeznaczenia rozważ użycie zasad Populate Cache. Ta zasada jest używana w połączeniu z zasadą Lookup Cache (do odczytywania wpisów w pamięci podręcznej) i zasadą Invalidate Cache (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 elementu opisuje elementy i atrybuty zasad.

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

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <CacheKey>

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

Klucze pamięci podręcznej są ograniczone do rozmiaru 2 KB.

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

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

W czasie działania programu do wartości <KeyFragment> dodawana jest wartość elementu <Scope> lub wartość <Prefix>. Na przykład poniższy kod generuje klucz pamięci podręcznej w postaci 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 <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 zostanie uznane za brak w pamięci podręcznej. W takim przypadku przepływ jest wznawiany wzdłuż ścieżki braku 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 użyć dołączonej pamięci podręcznej. Jeśli chcesz mieć możliwość administracyjnego usuwania wpisów z pamięci podręcznej, podaj nazwę CacheResource. Więcej informacji znajdziesz w artykule Pamięć podręczna.

<CacheResource>cache_to_use</CacheResource>

Więcej informacji o konfigurowaniu pamięci podręcznych znajdziesz w artykule Tworzenie i edytowanie 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 do dopasowywania żądań do odpowiedzi w pamięci podręcznej.

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

Może to być klucz (statyczna nazwa podana przez Ciebie) lub wartość (dynamiczny wpis ustawiony przez odwołanie do zmiennej). Wszystkie określone fragmenty (wraz z prefiksem) są łą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 <Prefix> i <Scope>. Więcej informacji znajdziesz w artykule Praca z kluczami pamięci podręcznej.

Atrybuty

Element <CacheKey>/<Prefix>

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 podać własną wartość zamiast wartości wyliczonej przez <Scope>. Jeśli jest zdefiniowany, <Prefix> dodaje na początku wartość klucza pamięci podręcznej w przypadku wpisów zapisywanych w pamięci podręcznej. Wartość elementu <Prefix> zastępuje wartość elementu <Scope>.

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

Element <ExcludeErrorResponse>

Obecnie domyślnie te zasady zapisują w pamięci podręcznej odpowiedzi HTTP z dowolnym możliwym kodem stanu. Oznacza to, że w pamięci podręcznej są przechowywane zarówno odpowiedzi o powodzeniu, jak i o błędzie. 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 zapisywać w pamięci podręcznej odpowiedzi docelowe z kodami stanu błędu HTTP. Jeśli ten element ma wartość „true”, w pamięci podręcznej będą zapisywane tylko odpowiedzi z kodami stanu od 200 do 205. Są to jedyne kody stanu HTTP, które Edge uznaje za kody „powodzenia”, i nie możesz zmienić tego powiązania.

Więcej informacji o wzorcach pamięci podręcznej odpowiedzi, w których ten element jest przydatny, znajdziesz w tym poście na forum.

Uwaga: w przyszłej wersji (data nie jest jeszcze znana) domyślne ustawienie tego elementu zmieni się na „true”. Szczegółowe informacje znajdziesz w informacjach o wersji Apigee.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Element <ExpirySettings>

Określa, kiedy wpis w pamięci podręcznej powinien wygasnąć. Jeśli występuje, <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. Jeśli ten element występuje, jego element równorzędny, <TimeoutInSeconds>, zastępuje <ExpiryDate>.

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

Atrybuty

<ExpiryDate ref="" />

Element <ExpirySettings>/<TimeOfDay>

Godzina, o której wpis w pamięci podręcznej powinien wygasnąć. Użyj formularza hh:mm:ss . Jeśli ten element występuje, jego element równorzędny, <TimeoutInSeconds>, zastępuje <TimeOfDay>.

Wpisz godzinę w formacie GG:mm:ss, gdzie GG to godzina w formacie 24-godzinnym. Na przykład 14:30:00 oznacza 14:30.

W przypadku pory dnia domyślne ustawienia regionalne i strefa czasowa będą się różnić w zależności od tego, gdzie jest uruchamiany kod (nie można tego określić podczas konfigurowania zasady). 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 w pamięci podręcznej powinien wygasnąć.

Element <ExpirySettings>/<TimeoutInSeconds>

Liczba sekund, po których wpis w pamięci podręcznej powinien wygasnąć. Jeśli ten element występuje, zastępuje elementy równorzędne <TimeOfDay> i <ExpiryDate>.

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

Uwaga: podaj domyślną wartość limitu czasu, która będzie używana, jeśli zmienna ref nie otrzyma wartości z duration_variable.

Atrybuty

Element <Scope>

Wyliczenie używane do tworzenia prefiksu klucza pamięci podręcznej, gdy w elemencie <CacheKey> nie ma elementu <Prefix>.

<Scope>scope_enumeration</Scope>

Ustawienie <Scope> określa klucz pamięci podręcznej, który jest dodawany na początku zgodnie z wartością <Scope>. Jeśli na przykład zakres jest ustawiony na Exclusive, klucz pamięci podręcznej będzie miał następującą 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 to wyliczenia podane poniżej.

Elementu <Scope> używasz w połączeniu z <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 <SkipCacheLookup>

Definiuje wyrażenie, które, jeśli w czasie działania zwróci wartość „prawda”, określa, że należy pominąć wyszukiwanie w pamięci podręcznej i odświeżyć pamięć podręczną. Zobacz też ten film o używaniu funkcji SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Jeśli na przykład w przychodzącym nagłówku zmienna bypass-cache ma wartość „true”, wyszukiwanie w pamięci podręcznej jest pomijane, a pamięć podręczna jest odświeżana.

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

Element <SkipCachePopulation>

Definiuje wyrażenie, które, jeśli w czasie działania zwróci wartość „prawda”, określa, że zapis do pamięci podręcznej powinien zostać pominięty. Zobacz też ten film o używaniu parametru SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Na przykład poniższy kod pominie zapis do pamięci podręcznej, jeśli kod stanu odpowiedzi będzie wynosić 400 lub więcej:

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

Element <UseAcceptHeader>

Ustaw wartość true, aby do klucza pamięci podręcznej wpisu pamięci podręcznej odpowiedzi dołączyć wartości z nagłówków Accept odpowiedzi.

Podczas obliczania klucza pamięci podręcznej Edge używa nagłówków żądania Accept, Accept-Encoding, Accept-Language i Accept-Charset. Dzięki temu klient nie otrzyma typu multimediów, o który nie prosił.

Załóżmy na przykład, że z tego samego adresu URL przychodzą 2 żądania, z których pierwsze akceptuje gzip, a drugie nie. Pierwsze żądanie zostanie zapisane w pamięci podręcznej, a wpis w niej będzie (prawdopodobnie) skompresowaną odpowiedzią. Drugie żądanie odczyta wartość z pamięci podręcznej, a następnie może zwrócić skompresowany wpis do klienta, który nie jest w stanie odczytać skompresowanych danych.

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

<UseAcceptHeader>false</UseAcceptHeader>

Element <UseResponseCacheHeaders>

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

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

Więcej informacji znajdziesz w artykule Ustawianie wygaśnięcia wpisu 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 artykule Wewnętrzne działanie pamięci podręcznej).

Dzięki konfiguracji w zasadach ResponseCache możesz sprawić, że Edge będzie uwzględniać nagłówki odpowiedzi HTTP podczas ustawiania wygaśnięcia wpisu w pamięci podręcznej i kluczy pamięci podręcznej. Z tej sekcji dowiesz się, jak używać zasad z nagłówkami do zarządzania wygasaniem pamięci podręcznej i kluczami pamięci podręcznej.

Więcej informacji o tym, jak Edge obsługuje nagłówki odpowiedzi za pomocą zasady ResponseCache, znajdziesz w artykule Obsługa nagłówków odpowiedzi HTTP.

Ustawianie terminu wygaśnięcia wpisu pamięci podręcznej

Podobnie jak w przypadku zasady Populate Cache, możesz ustawić wygaśnięcie wpisu w pamięci podręcznej odpowiedzi (jego czas życia danych (TTL)) za pomocą elementu <ExpirySettings>. W zasadach ResponseCache możesz też skonfigurować Edge, aby uwzględniał nagłówki odpowiedzi, gdy są obecne.

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 z tych 2 wartości. Podczas analizowania nagłówków odpowiedzi Edge wybiera dostępną wartość zgodnie z opisem poniżej:

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

• Brak wartości Cache-Control s-maxage
• Wartość Cache-Control max-age wynosząca 300
• Expires za 3 dni
• Wartość <ExpirySettings> TimeoutInSeconds wynosi 600.

W tym przypadku do określenia czasu życia zostanie użyta wartość Cache-Control max-age, ponieważ jest ona niższa niż wartość <ExpirySettings> i nie ma wartości Cache-Control s-maxage (która ma wyższy priorytet niż max-age).

Konfigurowanie klucza pamięci podręcznej

Podobnie jak w przypadku zasad pamięci podręcznej ogólnego przeznaczenia, takich jak zasady Populate Cache, w przypadku zasad ResponseCache używasz elementów <CacheKey> i <Scope> do konfigurowania tworzenia klucza pamięci podręcznej dla wpisów w pamięci podręcznej. Dzięki ResponseCache możesz też nadawać kluczom pamięci podręcznej większe znaczenie, dołączając do wartości kluczy nagłówki Accept odpowiedzi.

Ogólne informacje o konfigurowaniu kluczy pamięci podręcznej znajdziesz w artykule Praca z kluczami pamięci podręcznej. Informacje o używaniu nagłówków Accept znajdziesz w artykule <UseAcceptHeader>.

Informacje o szyfrowaniu pamięci podręcznej

Edge w chmurze publicznej: pamięć podręczna jest szyfrowana tylko w organizacjach, w których włączono zgodność z wymaganiami PCI i HIPAA. Szyfrowanie w tych organizacjach jest konfigurowane podczas udostępniania organizacji.

Zmienne przepływu

Gdy wykonywana jest zasada ResponseCache, wypełniane są te wstępnie zdefiniowane zmienne Flow: Więcej informacji o zmiennych Flow znajdziesz w dokumentacji 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 zasad jest zdefiniowany przez schemat XML (.xsd). Schematy zasad są dostępne na GitHubie.