KeyValueMapOperations 정책

Apigee Edge 문서를 보고 있습니다.
Apigee X 문서로 이동하세요. info

대상

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가 지정된 KVM에서 캐시된 값을 새로고침하는 시간을 초 단위로 지정합니다.

값이 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는 API 프록시 흐름에 사용할 수 있는 다음 변수를 만듭니다.

• 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와 프라이빗 클라우드용 Edge 모두 키 크기는 2KB로 제한됩니다. KVM 값은 2KB로 제한됩니다.

암호화된 KVM을 만들려면 키/값 맵 관리 API를 사용하세요.

<Key> 요소

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

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

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

퍼블릭 클라우드용 Edge의 경우 키 크기는 2KB로 제한됩니다. 자세한 내용은 Edge for Public Cloud API와 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로 설정하면 키-값 맵의 항목은 맵에 값을 쓰는 API 프록시로만 액세스할 수 있습니다.

맵 또는 맵 항목에 액세스하면 지도를 만들 때 사용한 범위 값 값을 지정해야 합니다. 예를 들어 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 정책에서 반환되는 오류는 오류 코드 참조에 설명된 일정한 형식을 따릅니다.

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

런타임 오류

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

배포 오류

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

스키마

사용 참고사항

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

키-값 맵 저장소는 키-값 쌍으로 형식이 지정된 데이터에 대한 간단한 지속성 메커니즘을 제공합니다. 정책 또는 코드를 통해 런타임 시 이에 액세스할 수 있습니다. 맵에는 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를 사용하여 대규모 데이터 세트를 키/값 스토어에 업로드하거나 스크립트를 만들어 키/값 맵 항목을 관리할 수 있습니다. KeyValueMapOperations 정책으로 API에 액세스하려면 API를 사용하여 키/값 맵을 만들어야 합니다.

키 이름 지정 및 검색

<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