ResponseCache 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

백엔드 리소스의 데이터를 캐시하여 리소스 요청 수를 줄입니다. 여러 앱이 동일한 URI에 요청할 때 요청을 백엔드 서버에 전달하는 대신 이 정책을 사용하여 캐시된 응답을 반환할 수 있습니다. ResponseCache 정책은 지연 시간 및 네트워크 트래픽을 줄여 API 성능을 향상시킬 수 있습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

API에서 사용하는 백엔드 데이터가 주기적으로만 업데이트되는 경우 ResponseCache가 가장 유용할 수 있습니다. 예를 들어 10분마다 새로고침되는 날씨 보고서 데이터를 노출하는 API가 있다고 가정해 봅시다. ResponseCache를 사용하여 새로고침 사이에 캐시된 응답을 반환함으로써 백엔드에 도달하는 요청 수를 줄일 수 있습니다. 이렇게 하면 네트워크 홉의 수도 줄어듭니다.

범용 단기 캐싱의 경우 PopulateCache 정책을 사용해 보세요. 이 정책은 LookupCache 정책(캐시 항목 읽기용) 및 InvalidateCache 정책(항목 무효화용)과 함께 사용됩니다.

샘플

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 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>

<CacheKey> 요소

캐시에 저장된 데이터 조각을 가리키는 고유한 포인터를 구성합니다.

캐시 키의 크기는 2KB로 제한됩니다.

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

<CacheKey>는 캐시에 저장된 각 데이터 조각의 이름을 구성합니다. 이 키는 항목 헤더 또는 쿼리 매개변수의 값을 사용하여 설정되는 경우가 많습니다. 이 경우 요소의 참조 속성이 키 값을 포함하는 변수를 지정해야 합니다.

런타임 시 <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 이름을 지정해야 합니다. 자세한 내용은 캐시 API를 참조하세요.

<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 오류 상태 코드가 있는 대상 응답의 캐시를 제외하지 않으려면 false로 설정합니다.

이 요소가 유용한 응답 캐시 패턴에 대한 자세한 내용은 방지 패턴 소개를 참조하세요.

<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>를 재정의합니다.

시각을 HH:mm:ss 형식으로 입력합니다. 여기서 HH는 24시간제의 시를 나타냅니다. 예를 들어 오후 2:30은 14:30:00으로 표시합니다.

시각의 경우, 기본 언어 및 시간대는 코드가 실행되는 위치에 따라 다릅니다(정책을 구성할 때 알지 못함).

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

속성

<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> 요소

런타임 시 true로 평가되면 캐시 조회를 건너뛰고 캐시를 새로고침하도록 지정하는 표현식을 정의합니다. SkipCacheLookup 사용에 대한 자세한 내용은 ResponseCache 정책 사용 동영상도 참조하세요.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

다음 예시에서 수신 헤더에서 우회-캐시 변수가 true로 설정되어 있으면 캐시 조회를 건너뛰고 캐시가 새로고침됩니다.

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

<SkipCachePopulation> 요소

런타임 시 true로 평가되면 캐시에 대한 쓰기를 건너뛰도록 지정하는 표현식을 정의합니다. SkipCachePopulation 사용에 대한 이 동영상도 참조하세요.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

예를 들어 다음은 응답 상태 코드가 400 이상인 경우 캐시 쓰기를 건너뜁니다.

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

<UseAcceptHeader> 요소

응답 Accept 헤더의 값과 함께 응답 캐시 항목의 캐시 키를 추가하려면 true로 설정합니다.

Apigee는 캐시 키를 계산할 때 Accept, Accept-Encoding, Accept-Language, Accept-Charset 요청 헤더를 사용합니다. 이 방법은 클라이언트가 요청하지 않은 미디어 유형을 가져오지 못하도록 합니다.

예를 들어 두 개의 요청이 동일한 URL에서 수신되는 경우 첫 번째 요청이 gzip을 수락하지만 두 번째 요청은 수락하지 않을 경우를 생각해 보겠습니다. 첫 번째 요청은 캐시되며 캐시된 항목은 gzip 처리된 응답이 될 수 있습니다. 두 번째 요청은 캐시된 값을 읽은 후 gzip을 읽을 수 없는 클라이언트에 gzip 처리된 항목을 반환할 수 있습니다.

자세한 내용은 캐시 키 구성을 참조하세요.

<UseAcceptHeader>false</UseAcceptHeader>

<UseResponseCacheHeaders> 요소

캐시에서 응답의 'TTL(수명)'을 설정할 때 HTTP 응답 헤더를 사용하려면 true로 설정합니다. 이 값이 true이면 Apigee는 다음 응답 헤더의 값을 고려하여 수명을 설정할 때 <ExpirySettings>에 설정된 값과 비교합니다.

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

자세한 내용은 캐시 항목 만료 설정을 참조하세요.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

사용 참고사항

캐시된 각 객체의 최대 크기는 256KB입니다. Apigee가 캐시를 처리하는 방법에 대한 자세한 내용은 캐시 내부를 참조하세요.

ResponseCache 정책의 구성을 통해 Apigee가 캐시 항목 만료 및 캐시 키 설정에 HTTP 응답 헤더를 포함하도록 할 수 있습니다. 이 섹션에서는 헤더가 있는 정책을 사용하여 캐시 만료 및 캐시 키를 관리할 수 있는 방법을 설명합니다.

Apigee가 ResponseCache 정책으로 응답 헤더를 처리하는 방법에 대한 자세한 내용은 HTTP 응답 헤더 지원을 참조하세요.

캐시 항목 만료 설정

PopulateCache 정책과 마찬가지로 <ExpirySettings> 요소를 사용하여 응답 캐시 항목의 만료 시간(수명)을 설정할 수 있습니다. ResponseCache 정책에서 Apigee가 응답 헤더가 있는 경우 이를 고려하도록 할 수도 있습니다.

응답 헤더를 사용하려면 <UseResponseCacheHeaders> 요소 값을 true로 설정합니다. 이 설정으로 인해 Apigee는 응답 헤더를 고려하여 <ExpirySettings>에 설정한 값과 비교하며, 이 둘 중 낮은 값을 사용합니다. 응답 헤더를 고려할 때 Apigee는 다음에 설명된 대로 사용 가능한 값을 선택합니다.

예를 들어 응답이 다음 값으로 캐시되어 있다고 가정해 보겠습니다.

• Cache-Control s-maxage 값 없음
• Cache-Control max-age 값: 300
• Expires 날짜: 3일
• <ExpirySettings> TimeoutInSeconds 값: 600

이 경우 Cache-Control max-age 값은 <ExpirySettings> 값보다 낮고 Cache-Control s-maxage 값이 없으므로 TTL에 사용됩니다(max-age보다 우선시됨).

캐시 키 구성

PopulateCache 정책과 같은 범용 캐시 정책과 마찬가지로 ResponseCache에서는 <CacheKey> 및 <Scope> 요소를 사용하여 캐시 항목의 캐시 키 생성을 구성합니다. ResponseCache를 사용하면 응답 값에 응답 Accept 헤더를 추가하여 캐시 키를 더 의미 있게 만들 수도 있습니다.

캐시 키 구성에 대한 일반적인 내용은 캐시 키 작업을 참조하세요. Accept 헤더 사용에 대한 자세한 내용은 <UseAcceptHeader>을 참조하세요.

캐시 암호화 정보

Apigee 및 Apigee 하이브리드(버전 1.4 이상): 캐시 및 KVM 데이터는 항상 암호화됩니다.

흐름 변수

ResponseCache 정책이 실행될 때 다음과 같은 사전 정의된 흐름 변수가 채워집니다. 흐름 변수에 대한 자세한 내용은 흐름 변수 참조를 참조하세요.

오류 코드

이 섹션에서는 이 정책이 오류를 트리거할 때 설정되는 오류 메시지 및 흐름 변수에 대해 설명합니다. 이 정보는 프록시에 대한 오류 규칙을 개발하는 중이라면 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

오류 코드 프리픽스

해당 없음

런타임 오류

이 정책은 런타임 오류를 발생시키지 않습니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 변수

해당 없음

오류 응답 예시

해당 없음

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.