PopulateCache 정책

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

Apigee Edge 문서 보기

캐시된 값이 런타임 시 작성되는 방식을 구성합니다.

캐시 채우기 정책은 단기 범용 캐시에서 항목을 작성하도록 설계되었습니다. 이 정책은 캐시 조회 정책(캐시 항목 읽기용) 및 캐시 무효화 정책(항목 무효화용)과 함께 사용됩니다.

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

백엔드 리소스의 응답을 캐싱하려면 응답 캐시 정책을 참조하세요.

요소 참조

다음은 이 정책에서 구성할 수 있는 요소입니다.

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

<PopulateCache> 속성

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성	설명	기본값	Presence
name	정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.	해당 사항 없음	필수
continueOnError	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조: 오류 규칙은 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 오류 처리	false	선택사항
enabled	정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	true	선택사항
async	이 속성은 지원이 중단되었습니다.	false	지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

기본값	해당 사항 없음 이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
Presence	선택사항
유형	문자열

<CacheKey> 요소

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

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

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

기본값:	해당 사항 없음
Presence:	필수
유형:	해당 사항 없음

<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>와 함께 사용합니다. 자세한 내용은 캐시 키 작업을 참조하세요.

<CacheResource> 요소

메시지를 저장할 캐시를 지정합니다.

이 정책 및 해당 LookupCache 및 InvalidateCache 정책이 포함된 공유 캐시를 사용하는 경우 이 요소를 완전히 생략하세요.

<CacheResource>cache_to_use</CacheResource>

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열

캐시 구성에 대한 자세한 내용은 범용 캐싱을 참조하세요.

<CacheKey>/<KeyFragment> 요소

캐시 키에 포함되어야 하는 값을 지정합니다. ref 속성이나 고정 값을 사용하여 참조 해제할 변수를 지정합니다.

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

기본값:	해당 사항 없음
Presence:	0 이상
유형:	해당 사항 없음

런타임에서 Apigee는 <Scope> 요소 또는 <Prefix> 요소에서 가져온 값을 각 <KeyFragment> 요소의 확인된 값에 연결하여 캐시 키를 만듭니다. 자세한 내용은 캐시 키 작업을 참조하세요.

속성

속성	유형	기본값	필수	설명
ref	문자열		아니요	값을 가져올 변수입니다. 이 요소에 리터럴 값이 포함된 경우에는 사용하면 안 됩니다.

<CacheKey>/<Prefix> 요소

캐시 키 프리픽스로 사용할 고정 값을 지정합니다.

<Prefix>prefix_string</Prefix>

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열

<Prefix> 요소는 모든 <Scope> 요소를 재정의합니다.

런타임에서 Apigee는 <Scope> 요소 또는 <Prefix> 요소에서 가져온 값을 각 <KeyFragment> 요소의 확인된 값에 연결하여 캐시 키를 만듭니다. 자세한 내용은 캐시 키 작업을 참조하세요.

<ExpirySettings> 요소

캐시 항목이 만료되는 시간을 지정합니다.

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

기본값:	해당 사항 없음
Presence:	필수
유형:	해당 사항 없음

<ExpirySettings> 하위 요소

정확하게 하위 요소 하나만 사용합니다. 다음 표에서는 <ExpirySettings>의 하위 요소에 대한 설명을 제공합니다.

하위 요소	설명
<TimeoutInSeconds>	캐시 항목이 만료되는 소요 시간(초)입니다. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> 이 요소는 현재 지원 중단된 TimeoutInSec 요소를 대체합니다.
<ExpiryDate>	캐시 항목이 만료되는 날짜를 지정합니다. mm-dd-yyyy 형식의 문자열을 지정합니다. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> 지정된 날짜가 과거이면 정책은 캐시된 항목에 최대 TTL(수명)을 적용합니다. 최대 기간은 30일입니다.
<TimeOfDay>	캐시 항목이 만료되는 날짜를 지정합니다. HH:mm:ss 형식의 문자열을 지정합니다. 여기서 HH는 UTC 시간대의 시간(24시간제)을 나타냅니다. 예를 들어 14:30:00은 오후 2:30을 의미합니다. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> 참고: 시간은 협정 세계시(UTC) 시간대로 지정합니다. 캐시 채우기 시간 표기법은 국제 표준 ISO 8601에 정의된 국제 표준 날짜 표기를 따릅니다.

가능한 하위 요소 중 하나만 지정해야 합니다. 요소를 여러 개 지정하면 우선순위는 TimeoutInSeconds, ExpiryDate, TimeOfDay입니다.

<ExpirySettings>의 위 하위 요소 각각에 선택적 ref 속성을 지정하면 정책에서 이름이 지정된 컨텍스트 변수에서 만료 값을 가져옵니다. 변수가 정의되어 있지 않으면 정책은 하위 요소의 리터럴 텍스트 값을 사용합니다.

<Scope> 요소

<CacheKey> 요소에서 <Prefix> 요소가 제공되지 않은 경우 캐시 키의 프리픽스를 구성하는 데 사용되는 열거형입니다.

<Scope>scope_enumeration</Scope>

기본값:	"Exclusive"
Presence:	선택사항
유형:	문자열

<Scope> 설정은 <Scope> 값에 따라 앞에 오는 캐시 키를 결정합니다. 예를 들어 범위를 Exclusive로 설정하면 캐시 키는 다음과 같은 형식을 취합니다.

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [serializedCacheKey ]

<CacheKey>에 <Prefix> 요소가 있는 경우 <Scope> 요소 값을 대체합니다. 유효한 값에는 아래의 열거값이 포함됩니다.

<Scope> 요소를 <CacheKey> 및 <Prefix>와 함께 사용합니다. 자세한 내용은 캐시 키 작업을 참조하세요.

사용 가능한 값

Global	환경에 배포된 모든 API 프록시에서 캐시 키를 공유합니다. 캐시 키는 orgName__ envName __ 형식으로 앞에 추가됩니다. <KeyFragment> apiAccessToken 및 <Global> 범위로 <CacheKey> 항목을 정의하면 각 항목은 orgName__envName__apiAccessToken으로 저장되고, 액세스 토큰의 직렬화된 값이 뒤에 옵니다. 'apifactory'라는 조직에 있는 'test'라는 환경에 배포된 API 프록시의 경우 액세스 토큰은 캐시 키 apifactory__test__apiAccessToken 아래에 저장됩니다.
Application	API 프록시 이름은 프리픽스로 사용됩니다. 캐시 키는 orgName__envName__apiProxyName 형식으로 앞에 추가됩니다.
Proxy	ProxyEndpoint 구성이 프리픽스로 사용됩니다. 캐시 키는 orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName 형식으로 앞에 추가됩니다.
Target	TargetEndpoint 구성이 프리픽스로 사용됩니다. 캐시 키는 orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName 형식으로 앞에 추가됩니다.
Exclusive	기본값입니다. 이는 가장 구체적이므로 지정된 캐시 내에서 네임스페이스 충돌 위험을 최소화합니다. 프리픽스는 다음 두 가지 형식 중 하나입니다. 정책이 ProxyEndpoint 흐름에 연결된 경우 프리픽스는 ApiProxyName_ProxyEndpointName 형식입니다. 정책이 TargetEndpoint에 연결된 경우 프리픽스는 ApiProxyName_TargetName 형식입니다. 캐시 키는 orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName 형식으로 앞에 추가됩니다. 예를 들어 전체 문자열은 다음과 같습니다. apifactory__test__weatherapi__16__default__apiAccessToken .

<Source> 요소

캐시에 값을 작성해야 하는 변수를 지정합니다.

<Source>source_variable</Source>

기본값:	해당 사항 없음
Presence:	필수
유형:	문자열

참고:

• JSON 객체는 인메모리 캐시(L1)에만 저장됩니다.
• 이러한 객체를 영구 캐시(L2)에 캐시하려면 문자열 형식으로 직렬화하는 것이 좋습니다.
• 이 방법을 따르면 L2 캐시를 효과적으로 활용하고 캐싱 효율성을 극대화할 수 있습니다.
• 자세한 내용은 캐시 내부를 참조하세요.
  

사용 참고사항

이 정책은 범용 캐싱에 사용됩니다. 런타임 시 <PopulateCache> 정책은 <Source> 요소에 지정한 변수의 데이터를 <CacheResource> 요소에 지정된 캐시에 씁니다. <CacheKey>, <Scope>, <Prefix> 요소를 사용하여 <LookupCache> 정책에서 값을 검색하는 데 사용할 수 있는 키를 지정할 수 있습니다. <ExpirySettings> 요소를 사용하여 캐시된 값이 만료되는 시기를 구성합니다.

PopulateCache 정책, LookupCache 정책, InvalidateCache 정책을 통한 범용 캐싱은 구성한 캐시 또는 기본적으로 포함된 공유 캐시를 사용합니다. 대부분의 경우 기본 공유 캐시가 니즈를 충족해야 합니다. 이 캐시를 사용하려면 <CacheResource> 요소를 생략하면 됩니다.

캐시 한도: 이름 및 값 크기, 총 캐시 수, 캐시의 항목 수, 만료 등 다양한 캐시 한도가 적용됩니다.

기본 데이터 스토어에 대한 자세한 내용은 캐시 내부를 참조하세요.

캐시 암호화 정보

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

오류 코드

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	발생 상황
policies.populatecache.EntryCannotBeCached	500	항목은 캐시할 수 없습니다. 캐시되는 메시지 객체는 직렬화 가능한 클래스의 인스턴스가 아닙니다.

배포 오류

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

팁: 오류를 해결하는 데 도움이 필요하신가요? 해결 열의 를 클릭하여 자세한 문제 해결 정보를 확인합니다.

오류 이름	원인	수정
InvalidCacheResourceReference	이 오류는 PopulateCache 정책의 <CacheResource> 요소가 API 프록시가 배포되는 환경에 존재하지 않는 이름으로 설정되는 경우에 발생합니다.
CacheNotFound	<CacheResource> 요소에 지정된 캐시가 존재하지 않습니다.

오류 변수

이러한 변수는 이 정책으로 오류가 트리거될 때 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수	장소	예
fault.name="fault_name"	fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	populatecache.POP-CACHE-1.failed = true

오류 응답 예시

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

오류 규칙 예시

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>