KeyValueMapOperations 정책

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

Apigee Edge 문서 보기

Apigee UI의 키 값 맵 작업 아이콘

소개

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

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

동영상: 다음 동영상에서는 KVM을 간략하게 소개합니다.

샘플

KVM에 리터럴 적용하기

다음 정책이 실행되면 FooKVM이라는 암호화된 KVM을 만든 후, 리터럴 문자열 foo 및 bar로 설정된(변수에서 추출한 값으로 설정하지 않음) 두 개의 값으로 FooKey_1이라는 키를 만듭니다. 다음 예시에서 키를 GET할 경우 원하는 값을 검색하기 위한 색인 번호를 지정합니다.

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

범위는 environment입니다. 즉, 관리 UI의 API > 환경 구성 > 키-값 맵에서 KVM을 확인할 수 있습니다. 이 페이지에 표시된 KVM은 모두 선택한 환경으로 범위가 지정됩니다.

리터럴에서 KVM 가져오기

이 정책은 이전 예시의 FooKVM 맵을 검토하고 FooKey_1 키에서 두 번째 값(색인='2')을 가져와 foo_variable 변수에 보관합니다. 

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

동적으로 KVM에 액세스

이 정책은 <MapName> 요소를 사용하여 흐름 변수로 KVM을 동적으로 참조합니다. 이 요소는 흐름 변수에서 KVM 식별자를 가져옵니다. mapIdentifier 속성은 생략됩니다. <MapName>을 mapIdentifier 속성과 함께 사용할 수 없습니다.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

KVM에 변수 적용하기

유용한 KVM의 간단한 예는 URL 단축 서비스입니다. KVM은 해당 전체 URL과 함께 단축 URL을 저장하도록 구성할 수 있습니다.

이 정책 샘플은 KVM을 만듭니다. 정책은 PUT 명령어를 사용하여 2개의 연관된 값이 있는 키를 urlMapper라는 KVM에 배치합니다.

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

이 예시에서 urlencoding.requesturl.hashed 키는 커스텀 변수의 예시입니다. 해싱된 요청 URL은 코드(예: 자바스크립트 또는 자바)에 의해 생성된 다음 이 변수에 저장됩니다. 여기서 KeyValueMapOperations 정책은 여기에 액세스할 수 있습니다.

requesturl.hashed 키마다 2개의 값이 저장됩니다.

  • 이름이 urlencoding.longurl.encoded인 맞춤 변수의 콘텐츠
  • 사전 정의된 변수 request.queryparam.url의 콘텐츠

예를 들어 런타임 시 정책이 실행되면 변수 값이 다음과 같을 수 있습니다.

  • urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
  • urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
  • request.queryparam.url: http://apigee.com

다음 KVM 및 항목이 Apigee의 키/값 저장소에 생성되고, 정책이 연결된 API 프록시로 범위가 지정됩니다.

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

항목은 삭제될 때까지 유지됩니다. 키/값 저장소 항목은 클라우드가 실행되는 Apigee 인스턴스에 배포됩니다.

변수에서 KVM 가져오기

유용한 KVM의 간단한 예는 URL 단축 서비스입니다. KVM은 해당 전체 URL과 함께 단축 URL을 저장하도록 구성할 수 있습니다.

KeyValueMapOperations PUT 탭에서 다룬 값처럼 KVM 항목 값을 가져오면 KVM을 GET하도록 정책을 구성합니다.

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

이 정책이 실행될 때 urlencoding.requesturl.hashed 변수의 값이 ed24e12820f2f900ae383b7cc4f2b31c402db1be이면 이름이 urlencoding.shorturl인 맞춤 변수가 http://tinyurl.com/38lwmlr 값과 함께 설정됩니다.

이제 데이터를 검색했으므로 다른 정책과 코드에서 이러한 변수의 값을 추출하여 데이터에 액세스할 수 있습니다.

KVM에서 값 가져오기

디버그 세션에서 KVM 정보를 숨기려면 GET 명령어를 사용하여 KVM에 액세스할 때 모든 변수가 있는 private. 속성을 사용하세요. private. 속성을 사용하지 않으면 KVM이 여전히 암호화됩니다. 그러나 KVM 정보는 디버그 세션에 복호화되어 표시되며 예외가 발생하지 않습니다.

이 예시에서 private.encryptedVar 변수는 KVM foo 키의 복호화된 값을 포함합니다.

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

이제 데이터를 검색했으므로 다른 정책과 코드에서 해당 변수의 값을 추출하여 데이터에 액세스할 수 있습니다.

<KeyValueMapOperations>

키 값 맵(KVM)에 대한 정책 기반 액세스를 제공합니다.

구문

<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>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </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> 요소의 속성을 설명합니다.

속성 설명 기본값 접속 상태
mapIdentifier

액세스해야 하는 KVM에 대한 정책을 알리는 식별자를 지정합니다.

이 식별자와 <MapName>이 모두 누락되면 kvmap이라는 KVM이 사용됩니다. <MapName> 요소를 지정하면 이 속성을 사용할 수 없습니다.

 해당 사항 없음 선택사항

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

속성 설명 기본값 접속 상태
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

 해당 사항 없음 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:

 거짓 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

 참 선택사항
async

이 속성은 지원이 중단되었습니다.

 거짓 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
접속 상태 선택사항
유형 문자열

하위 요소

이 섹션에서는 KeyValueMapOperations 정책의 요소와 속성을 설명합니다.

<Delete> 요소

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

루트 요소의 mapIdentifier 속성 또는 <MapName> 요소를 사용하여 KVM 이름을 지정해야 합니다. 예를 들면 다음과 같습니다.

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>
기본값 해당 사항 없음
접속 상태 <Get> 또는 <Put>이 없는 경우 필수입니다.
유형 해당 사항 없음

<Entry> 요소

초기화될 때 KVM에 입력되는 KVM의 시드 값입니다. Apigee의 경우 키 크기는 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> 요소

Apigee가 지정된 KVM에서 캐시된 값을 새로고침하는 시간을 초 단위로 지정합니다.

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

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
기본값 300(5분)
접속 상태 선택사항
유형 정수

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

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

GET - KVM GET 작업이 처음 실행되면 KVM에서 요청된 키-값(정책의 루트 mapIdentifier 속성 또는 <MapName> 요소에 이름이 지정되어 있음)이 캐시에 로드됩니다. 여기서 키-값은 다음 중 하나가 발생할 때까지 후속 GET 작업을 위해 캐시에 유지됩니다.

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

PUT - PUT 작업은 지정된 KVM에 키-값을 씁니다. PUT에서 이미 캐시에 있는 키에 쓰기를 수행하면 캐시가 즉시 새로고침되고 정책의 <ExpiryTimeInSecs> 요소에 지정된 시간(초) 동안 새 값이 유지됩니다. 하지만 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> 중 하나 이상을 사용해야 합니다.

Apigee는 KVM에 저장된 모든 데이터를 암호화합니다. 자세한 내용은 암호화 키 정보를 참조하세요. <Get>을 사용하면 Apigee는 저장된 데이터를 복호화하고 메시지 컨텍스트의 변수에 할당합니다. 변수 이름은 assignTo 속성을 사용하여 지정됩니다.

루트 요소의 mapIdentifier 속성 또는 <MapName> 요소를 사용하여 KVM 이름을 지정해야 합니다.

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

기본값 해당 사항 없음
접속 상태 <Put> 또는 <Delete>이 없는 경우 필수입니다.
유형 해당 사항 없음

속성

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

속성 설명 기본값 접속 상태
assignTo

검색한 값을 할당해야 하는 변수입니다.

 해당 사항 없음 필수
index

값이 여러 개인 키에서 가져올 항목의 색인 번호(1부터 시작하는 색인)입니다. 예를 들어 index=1을 지정하면 첫 번째 값이 반환되고 assignTo 변수에 할당됩니다. 색인 값이 지정되지 않은 경우 해당 항목의 모든 값은 변수에 java.util.List로 할당됩니다.

예시를 보려면 샘플의 KVM에서 값 가져오기 탭을 참조하세요.

 해당 사항 없음 선택사항

KVM에서 단일 항목 가져오기

이 단계 구성 예시를 사용하면 정책은 KVM에서 단일 키의 값을 읽고 복호화하고 복호화된 값을 myvar이라는 변수에 할당합니다. 

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

디버그 세션에서 검색된 데이터 제외

KVM에 저장된 데이터가 민감한 데이터일 수 있습니다. 검색된 데이터가 디버그 세션에 표시되지 않도록 하려면 assignTo 속성에 지정된 변수 이름에 private. 프리픽스를 사용합니다. private. 프리픽스를 사용하지 않는 경우 KVM에서 검색된 데이터가 생성된 모든 디버그 세션에서 일반 텍스트로 표시됩니다.

이 단계 구성 예시를 사용하면 정책이 KVM의 단일 키에 연결된 값을 읽고 복호화하고 이 값을 변수에 할당합니다. 할당은 디버그 세션에 표시되지 않습니다.

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

KVM에서 여러 항목 가져오기

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

키 값
top_movies Princess Bride, The Godfather, Citizen Kane
Citizen Kane Orson Welles
Princess Bride Rob Reiner
The Godfather Francis Ford Coppola

top_movies 키에 연결된 값에 여러 영화 이름이 쉼표로 구분된 것을 확인할 수 있습니다.

이 구성 예시에서 정책은 현재 인기 영화와 감독의 이름을 검색합니다.

<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 프록시가 호출되면 Apigee는 나중에 API 프록시 흐름에서 사용할 수 있는 해당 값으로 다음 변수를 만듭니다.

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

첫 번째 <Get> 요소는 index 속성 1을 사용하므로 top.movie.pick 값은 쉼표로 구분된 목록의 첫 번째 항목입니다. 그런 다음 두 번째 <Get> 요소는 top.movie.pick에 할당된 값을 movie.director의 값을 검색하기 위한 키로 사용합니다.

<InitialEntries> 요소

초기화될 때 KVM에 입력되는 KVM의 시드 값입니다. KVM의 이름은 루트 요소의 mapIdentifier 속성으로 지정해야 합니다.

예를 들면 다음과 같습니다.

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

이 요소를 사용할 경우 API 프록시의 배포된 버전에서 Apigee UI에 정책을 저장하거나 이 요소와 함께 정책이 포함된 API 프록시 번들을 배포하면 키가 KVM에서 자동으로 생성됩니다. 정책 값이 KVM의 값과 다르면 API 프록시가 배포될 때 KVM의 값을 덮어씁니다. 모든 새 키-값은 기존 키-값과 함께 기존 KVM에 추가됩니다.

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

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

기본값 해당 사항 없음
접속 상태 선택사항
유형 해당 사항 없음

<Key> 요소

KVM 항목의 키를 지정합니다. 이 요소는 <Get>, <Put>, <Delete>의 하위 요소로 나타나거나 <InitialEntries>의 하위 요소인 <Entry> 하위 요소로 나타납니다. 다음은 고정 키의 예시입니다.

<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>

키는 동적 요소와 함께 복합적일 수 있습니다. 즉, 둘 이상의 <Parameter>를 추가하여 키를 만들 수 있습니다. 예를 들어 userID 및 role 변수의 콘텐츠를 조합하여 동적 키를 만들 수 있습니다. 다음은 동적으로 결정되는 복합 키를 지정하는 단계 구성의 예시입니다.

<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>

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

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

기본값 해당 사항 없음
접속 상태 선택사항
유형 해당 사항 없음

<MapName> 요소

<MapName> 요소를 사용하면 정책에서 런타임 시 동적으로 사용할 KVM을 식별할 수 있습니다. KVM을 동적으로 선택할 수 있는 기능을 통해 정책이 실행되는 컨텍스트에 따라 서로 다른 KVM에 액세스할 수 있는 하나의 KeyValueMapOperations 정책을 유연하게 설계할 수 있습니다.

예를 들면 다음과 같습니다.

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

첫 번째 줄은 KVM 이름을 리터럴 문자열로 지정합니다. 두 번째 줄은 흐름 변수에서 이름을 가져옵니다. 세 번째 줄은 흐름 변수가 빈 값으로 확인되는 경우 리터럴 문자열이 대신 사용됩니다.

정책에서 <MapName>을 사용하는 경우 mapIdentifier 속성을 지정하지 마세요. 자세한 내용은 정책 속성을 참조하세요.

프록시 배포 시 지도가 존재하지 않으면 지도가 생성되지 않으며 정책이 실행될 때 Apigee에서 런타임 오류가 발생합니다. 흐름 변수가 제공되면 <InitialEntries> 요소는 허용되지 않습니다. 배포 중 유효성 검사 오류가 발생합니다.

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

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

키/값 항목을 가져오든 업데이트하든 삭제하든, 키 이름은 KVM의 키 이름과 일치해야 합니다. 가이드라인은 키 이름 지정 및 검색을 참조하세요.

기본값 해당 사항 없음
접속 상태 필수
유형 문자열

속성

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

속성 설명 기본값 접속 상태
ref 생성하거나 가져오거나 삭제하려는 키의 정확한 이름이 포함된 변수의 이름을 지정합니다. 해당 사항 없음 여는 태그와 닫는 태그 사이에 리터럴 값이 제공되지 않은 경우 필수입니다.

<Put> 요소

KVM에 키-값 쌍을 작성합니다. 루트 요소의 mapIdentifier 속성에 지정된 KVM이 없고 <MapName> 요소가 사용되지 않으면 맵이 자동으로 생성됩니다. 키 값 맵이 이미 있으면 키/값이 맵에 추가됩니다.

UI 또는 API를 사용하여 KVM을 만들려면 다음을 참조하세요.

<Put override="false">
  <Key>
    <Parameter ref="mykeyvar"/>
  </Key>
  <Value ref="myvalvar1"/>
</Put>
기본값 해당 사항 없음
접속 상태 <Get> 또는 <Delete>이 없는 경우 필수입니다.
유형 해당 사항 없음

속성

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

속성 설명 기본값 접속 상태
재정의

true로 설정하면 키 값이 재정의됩니다.

<Put override="false">은 현재 KVM 저장소에 해당 키의 항목이 유지되지 않은 경우에만 쓰기를 수행합니다.

true 선택사항

<Scope> 요소

KVM에 대한 접근성의 경계를 정의합니다. 기본 범위는 environment입니다. 즉, 기본적으로 맵 항목은 환경(예: 테스트 또는 프로덕션)에서 실행되는 모든 API 프록시에서 공유합니다. 범위를 apiproxy로 설정하면 KVM의 항목은 맵에 값을 쓰는 API 프록시로만 액세스할 수 있습니다.

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

<Scope>environment</Scope>
기본값 environment
접속 상태 선택사항
유형 문자열
유효한 값
  • organization
  • environment
  • apiproxy
  • policy(API 프록시 버전)

<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> 요소의 속성을 설명합니다.

속성 설명 기본값 접속 상태
ref 설정하려는 키 값이 포함된 변수의 이름을 지정합니다. 해당 사항 없음 여는 태그와 닫는 태그 사이에 리터럴 값이 제공되지 않은 경우 필수입니다. 리터럴 값이 제공되면 금지됩니다.

오류 참조

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code HTTP status Cause Fix
steps.keyvaluemapoperations.UnsupportedOperationException 500

This error occurs if the mapIdentifier attribute is set to empty string in the KeyValueMapOperations policy.

Deployment errors

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

Error name Cause Fix
InvalidIndex If the index attribute specified in the <Get> element of KeyValueMapOperations policy is zero or a negative number, then the deployment of the API proxy fails. The index starts from 1, so an index of zero or negative integer is considered as invalid.
KeyIsMissing This error occurs if the <Key> element is completely missing or <Parameter> element is missing within <Key> element underneath the <Entry> of the <InitialEntries> element of the KeyValueMapOperations policy.
ValueIsMissing This error occurs if the <Value> element is missing underneath the <Entry> element of the <InitialEntries> element of the KeyValueMapOperations policy.

스키마

사용 참고사항

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

Apigee UI를 사용하여 Apigee UI로 KVM 사용에 설명된 대로 환경 범위에서만 KVM을 정의할 수 있습니다. Apigee API를 사용하면 다음 섹션에 설명된 대로 조직, 환경 또는 API 프록시 범위에서 KVM을 정의할 수 있습니다.

KVM 저장소는 키-값 쌍으로 형식이 지정된 데이터에 대한 간단한 지속성 메커니즘을 제공합니다. 정책 또는 코드를 통해 런타임 시 이에 액세스할 수 있습니다. 맵에는 key=value 형식의 임의 데이터가 포함됩니다.

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

예를 들어 다양한 백엔드 환경과 연결된 IP 주소 목록을 저장해야 한다고 가정해 봅시다. 키-값 쌍 목록을 항목으로 포함하는 ipAddresses라는 KVM을 만들 수 있습니다. 예를 들어 이 JSON은 다음 맵을 나타낼 수 있습니다.

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

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

KVM은 KeyValueMapOperations 정책을 통해, 또는 직접적으로는 Apigee API를 통해 조작할 수 있습니다. 예를 들어 API를 사용하여 대규모 데이터 세트를 키-값 저장소에 업로드하거나 스크립트를 만들어 키-값 맵 항목을 관리할 수 있습니다. KeyValueMapOperations 정책으로 API에 액세스하려면 API를 사용하여 KVM을 만들어야 합니다.

키 이름 지정 및 검색

<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의 키 이름이 my_key인 경우 <Parameter>my_key</Parameter>를 사용하여 리터럴 값을 지정하거나 <Parameter ref="variable.containing.foo"/>와 같이 정확한 값 mny_key를 포함하는 변수를 지정할 수 있습니다.

관련 주제

KVM에 대한 자세한 내용은 다음 주제를 참조하세요.