KeyValueMapOperations 정책

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보

대상

Apigee Edge에서 사용할 수 있는 키-값 맵 (KVM) 저장소에 대한 정책 기반 액세스를 제공합니다. PUT, GET 또는 DELETE 작업을 지정하는 KeyValueMapOperations 정책을 구성하여 이름이 지정된 기존 맵에서 키/값 쌍을 저장, 검색, 삭제할 수 있습니다. 정책에서 최소한 한 개 이상의 작업을 수행해야 합니다.

동영상

KVM에 대해 자세히 알아보려면 다음 동영상을 시청하세요.

샘플

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Put override="true">
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
      <Value ref="urlencoding.longurl.encoded"/>
      <Value ref="request.queryparam.url"/>
   </Put>
</KeyValueMapOperations>

{
    "entry" :[ 
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/> 
      </Key>
   </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
   <Scope>apiproxy</Scope>
   <Get assignTo="private.encryptedVar" index='1'>
      <Key>
         <Parameter>foo</Parameter> 
      </Key>
   </Get>
</KeyValueMapOperations>

요소 참조

요소 참조는 KeyValueMapOperations 정책의 요소 및 속성을 설명합니다.

<KeyValueMapOperations async="false" continueOnError="false" 
    enabled="true" name="Key-Value-Map-Operations-1" 
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

<KeyValueMapOperations> 속성

다음 예시는 <KeyValueMapOperations> 태그의 속성을 보여줍니다.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

다음 표에서는 <KeyValueMapOperations> 태그와 관련된 속성을 설명합니다.

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<Delete> 요소

지정된 키-값 쌍을 삭제합니다. <Get>, <Put>, <Delete> 중 하나 이상을 사용해야 합니다.

상위 요소에서 mapIdentifier 속성을 사용하여 KVM의 이름을 지정해야 합니다. 예를 들면 다음과 같습니다.

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

<Entry> 요소

초기화될 때 키 값 맵에 입력되는 키 값 맵의 시드 값입니다.

퍼블릭 클라우드용 Edge의 경우 키 크기는 2KB로 제한됩니다. 예를 들면 다음과 같습니다.

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

<ExclusiveCache> 요소

지원이 중단되었습니다. 대신 <Scope> 요소를 사용하세요.

<ExpiryTimeInSecs> 요소

Edge가 캐시된 값을 지정할 수 있습니다

값이 0 또는 -1이거나 이 요소를 제외한다는 것은 기본값 300초가 사용된다는 의미입니다. 예를 들면 다음과 같습니다.

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM은 키와 값을 NoSQL 데이터베이스에 저장하는 장기 지속성 메커니즘입니다. 이 때문에 런타임 시 KVM에서 읽기를 수행하면 프록시 성능이 저하될 수 있습니다. 개선을 위해 Edge에는 런타임 중에 메모리에 KVM 키/값을 캐시하는 메커니즘이 내장되어 있습니다. 이 KVM 작업 정책은 GET 작업의 경우 항상 캐시에서 읽습니다.

<ExpiryTimeInSecs> 요소를 사용하면 정책에 사용되는 키/값이 KVM에서 다시 새로고침되기 전에 캐시에 저장되는 기간을 제어할 수 있습니다. 하지만 GET과 PUT 작업이 캐시 만료에 미치는 영향 간에는 몇 가지 차이점이 있습니다.

GET - KVM GET 작업이 처음 실행되면 KVM에서 요청된 키/값(정책의 루트 mapIdentifier 속성에 이름이 지정됨)이 캐시에 로드됩니다. 여기서 다음 중 하나가 발생할 때까지 키/값이 후속 GET 작업에 사용됩니다.

• <ExpiryTimeInSecs>에 지정된 시간(초)이 만료됩니다.
  또는
• KVM 정책의 PUT 작업은 기존 값을 덮어씁니다(아래 설명 참조).

PUT - PUT 작업은 지정된 KVM에 키/값을 씁니다. PUT이 기존에 캐시에 있는 키에 쓰기 작업을 수행하므로 해당 캐시는 즉시 새로고침되고 정책의 <ExpiryTimeInSecs> 요소

예시 - KVM 캐싱

1. GET 연산은 'rating' 값을 검색하여 그러면 '10'이라는 값이 추가됩니다. 캐시합니다. 이 정책의 <ExpiryTimeInSecs> 값은 60입니다.
2. 30초 후 GET 정책이 다시 실행되고 '10'을 검색합니다. 삭제합니다.
3. 5초 후 PUT 정책은 'rating' 값을 '8'로 업데이트하고 PUT 정책의 <ExpiryTimeInSecs>은 20입니다. 캐시는 새 값으로 즉시 새로고침되며, 20초 동안 캐시에 보관되는 것으로 설정됩니다. PUT이 시작되지 않은 경우 첫 번째 GET에서 처음에 채워진 캐시는 처음 60초에서 남아서 30초 더 계속 존재합니다.
4. 15초 후에 또 다른 GET이 실행되고 '8' 값이 검색됩니다.

<Get> 요소

지정된 키의 값을 검색합니다. <Get>, <Put>, <Delete> 중 하나 이상을 사용해야 합니다.

상위 요소에서 mapIdentifier 속성을 사용하여 KVM의 이름을 지정해야 합니다.

정책에 여러 Get 블록을 포함하여 KVM에서 여러 항목을 검색할 수 있습니다.

KVM에서 단일 항목 가져오기

<Get assignTo="myvar" index="1">         
   <Key>             
      <Parameter>key_name_literal</Parameter>         
   </Key>     
</Get>

KVM에서 여러 항목 가져오기

다음 예시에서는 다음 키와 값이 있는 KVM을 가정합니다. KVM은 지금까지 가장 인기 있는 영화의 러닝 목록을 저장하는 것 외에 모든 주요 영화의 감독 이름을 저장합니다.

다음은 현재 가장 인기 있는 영화 및 감독의 이름을 검색하는 데 사용할 수 있는 KVM 정책 구성입니다.

<Get assignTo="top.movie.pick" index="1">
   <Key>
      <Parameter>top_movies</Parameter>
   </Key>
</Get>
<Get assignTo="movie.director">
   <Key>
      <Parameter ref="top.movie.pick"/>
   </Key>
</Get>

API 프록시가 호출되면 Edge는 다음을 만듭니다. 변수가 있습니다.

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

속성

다음 표에서는 <Get> 요소의 속성을 설명합니다.

<Get assignTo="private.myvar">

<InitialEntries> 요소

초기화될 때 키 값 맵에 입력되는 키 값 맵의 시드 값입니다. 상위 요소에서 mapIdentifier 속성을 사용하여 KVM의 이름을 지정해야 합니다. 예를 들면 다음과 같습니다.

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

이 요소를 사용하는 경우 배포된 버전의 관리 UI에 정책을 저장하는 경우 이 요소를 사용하여 정책이 포함된 API 프록시 번들을 배포하거나 KVM에서 암호화되지 않은 상태로 자동 생성됩니다. 정책 값이 KVM의 값과 다르면 KVM의 값이 프록시 배포 시 덮어쓰기 됩니다. 모든 새 키-값은 기존 키-값과 함께 기존 KVM에 추가됩니다.

이 요소에 의해 채워진 키와 값은 리터럴이어야 합니다. 예를 들어 <Parameter ref="request.queryparam.key">는 이 요소 내에서 지원되지 않습니다.

키 크기는 퍼블릭 클라우드용 Edge와 비공개 권한의 에지. KVM 값은 2KB로 제한됩니다.

암호화된 KVM을 만들려면 키/값 지도 관리 API를 사용합니다.

<Key> 요소

키/값 맵 항목의 키를 지정합니다. 키는 복합적일 수 있습니다. 즉, 둘 이상의 매개변수를 추가하여 키를 만들 수 있습니다. 예를 들어 userID 및 role을 조합하여 key을 만들 수 있습니다. 예를 들면 다음과 같습니다.

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

키 이름 설정 방법에 대한 자세한 내용은 <Parameter> 요소를 참조하세요.

퍼블릭 클라우드용 Edge에서는 키 크기가 2KB로 제한됩니다. 자세한 내용은 Public Cloud API용 Edge와 Private Cloud API의 차이점을 참조하세요.

<Parameter> 요소

키/값 쌍의 키를 지정합니다. 이 요소는 키/값 쌍을 생성, 삽입, 검색, 삭제할 때 이름을 지정합니다.

다음을 사용하여 이름을 지정할 수 있습니다.

• 리터럴 문자열

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• ref 속성을 사용하여 런타임 시 가져올 변수

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• 리터럴 및 변수 참조의 조합

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

키 요소에 여러 매개변수 요소가 포함된 경우 유효 키 문자열은 각 매개변수의 값을 연결하여 이중 밑줄로 결합합니다. 예를 들어 위의 예에서 apiproxy.name 변수의 값이 'abc1'이면 유효 키는 targeturl__abc1__weight입니다.

키-값 항목을 가져오거나 업데이트하거나 삭제하는 경우 키 이름은 키-값 맵의 키 이름입니다. 가이드라인은 키 이름 지정 및 검색을 참조하세요.

속성

다음 표에서는 <Parameter> 요소의 속성을 설명합니다.

<Put> 요소

키 값 맵이 암호화되었는지 여부와 관계없이 키 값 맵에 키/값 쌍을 씁니다. 상위 요소의 mapIdentifier 속성에 지정된 키 값 맵이 없으면 맵이 (암호화되지 않은 상태로) 자동으로 생성됩니다. 키 값 맵이 이미 있으면 키/값이 맵에 추가됩니다.

암호화된 키-값 맵을 만들려면 다음을 사용합니다. 키-값 지도 관리 API 또는 환경 키-값 맵 만들기 및 수정을 참고하세요. UI에서 암호화된 환경 범위 KVM을 만듭니다.

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"/>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>

속성

다음 표에서는 <Put> 요소의 속성을 설명합니다.

<Scope> 요소

키-값 맵에 대한 접근성의 경계를 정의합니다. 기본 범위는 environment입니다. 즉, 기본적으로 맵 항목은 환경(예: 테스트 또는 프로덕션)에서 실행되는 모든 API 프록시에서 공유합니다. 범위를 apiproxy를 포함하는 경우 키-값 맵의 항목은 사용자가 직접 지도에 값을 씁니다.

맵 또는 맵 항목에 액세스하면 지도를 만들 때 사용한 범위 값 값을 지정해야 합니다. 예를 들어 apiproxy 범위로 맵을 만든 경우 값을 검색하거나 변경사항을 적용하거나 항목을 삭제할 때 apiproxy 범위를 사용해야 합니다.

<Scope>environment</Scope>

<Value> 요소

키 값을 지정합니다. 값을 리터럴 문자열로 지정하거나 ref 속성을 사용하여 런타임 시 검색할 수 있는 변수로 사용할 수 있습니다.

<!-- Specify a literal value -->
<Value>literal<Value>

또는

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

<Value> 요소를 여러 개 포함하여 여러 부분으로 구성된 값을 지정할 수도 있습니다. 런타임 시 값이 결합됩니다.

다음 예시에서는 KVM에 두 개의 키가 추가됩니다.

• 값이 v1,v2인 키 k1
• 값이 v3,v4인 키 k2

<InitialEntries>         
   <Entry>             
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
      <Value>v2</Value>     
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

다음 예시에서는 두 개의 값이 있는 키 하나가 생성됩니다. 조직 이름이 foo_org이고, API 프록시 이름이 bar이고, 환경이 test라고 가정합시다.

• 값이 bar,test인 키 foo_org

<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>

속성

다음 표에서는 <Value> 요소의 속성을 설명합니다.

오류 참조

Edge 정책에서 반환된 오류는 오류 코드 참조에 설명된 대로 일관된 형식을 따릅니다.

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

스키마

사용 참고사항

키-값 맵의 개요는 키 값 맵 사용을 참조하세요.

키-값 맵 저장소는 키-값 쌍입니다. 정책 또는 코드를 통해 런타임 시 이에 액세스할 수 있습니다. 맵에는 key=value 형식의 임의 데이터가 포함됩니다.

예를 들면 localhost=127.0.0.1, zip_code=94110, 또는 first_name=felix입니다. 첫 번째 예시에서 localhost는 키이고 127.0.0.1은 값입니다. 각 키-값 쌍은 키 값 맵의 항목으로 저장됩니다. 키-값 맵은 여러 항목을 저장할 수 있습니다.

다음은 키-값 맵을 사용하는 예입니다. IP 주소 목록을 저장하고 다양한 백엔드 및 지원합니다 ipAddresses라는 키-값 맵을 만들 수 있으며, 여기에는 키-값 쌍의 목록입니다. 예를 들어 이 JSON은 다음 맵을 나타낼 수 있습니다.

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

이 구조를 사용하여 정책에서 사용할 수 있는 IP 주소 저장소를 만들 수 있습니다. 런타임 시 IP 허용 목록 또는 차단 목록을 적용하고 백엔드 대상을 동적으로 선택할 수 있습니다. 지정할 수 있습니다. 일반적으로 KeyValueMapOperations 정책은 여러 요청/응답 트랜잭션에 재사용해야 하는 장기 정보를 저장하거나 가져오는 데 사용됩니다.

키/값 맵은 KeyValueMapOperations 정책을 통해 조작하거나 Apigee Edge 관리 API를 참조하세요. 조직 키/값 지도 API API에 대한 자세한 내용은 관리 API 참조를 확인하세요. API를 사용하여 예를 들어 대용량 데이터 세트를 키/값 저장소에 업로드하거나 키/값을 관리하는 스크립트를 만듭니다. 매핑 항목을 사용하면 됩니다. 먼저 API로 키/값 맵을 만든 다음 KeyValueMapOperations 정책

키 이름 지정 및 검색

<Parameter> 및 <Value> 요소를 사용하면 리터럴 값(여는 태그와 닫는 태그 사이의 값)을 지정하거나 ref 속성을 사용하여 런타임 시에 사용해야 하는 변수의 이름을 지정할 수 있습니다.

Parameter 요소는 특정 값을 나타내는 키의 이름을 결정하기 때문에 특별히 언급해야 합니다. 가져오거나 삭제할 키 이름을 지정할 수 있습니다. 다음은 두 가지 예시입니다. 첫 번째 예시에서는 키 이름을 구체적으로 지정하고, 두 번째 예시에서는 변수를 사용하여 키 이름을 지정합니다. KVM에 키를 만들 때 다음을 사용한다고 가정해 보겠습니다.

<Parameter>key_name_literal</Parameter>
<Parameter ref="key.name.variable"/>

첫 번째 인스턴스에서 'key_name_literal'의 리터럴 값은 KVM에 키로 저장되기 때문에 있습니다. 두 번째 경우에는 key.name.variable에 있는 값이 무엇이든지 KVM의 키 이름입니다. 예를 들어 key.name.variable에 값이 foo이면 키 이름은 'foo'가 됩니다.

GET 작업으로 키 및 키 값을 검색하거나 DELETE 작업을 사용하여 삭제하려면 <Parameter> 설정을 KVM의 키 이름과 일치하도록 해야 합니다. 예를 들어 KVM의 키 이름이 'foo'인 경우 <Parameter>foo</Parameter>를 사용하여 리터럴 값을 지정하거나 <Parameter ref="variable.containing.foo"/>와 같이 정확한 값 'foo'를 포함하는 변수를 지정할 수 있습니다.

관련 주제

• 조직 키/값 맵 API