이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
대상
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에 대한 정책을 알리는 식별자를 지정합니다. 이 식별자와 |
해당 사항 없음 | 선택사항 |
다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 |
---|---|---|---|
name |
정책의 내부 이름입니다. 원하는 경우 |
해당 사항 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 정책이 실패해도 흐름 실행이 계속되도록 하려면 |
거짓 | 선택사항 |
enabled |
정책을 시행하려면 정책을 중지하려면 |
참 | 선택사항 |
async |
이 속성은 지원이 중단되었습니다. |
거짓 | 지원 중단됨 |
<DisplayName> 요소
name
속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.
<DisplayName>Policy Display Name</DisplayName>
기본값 |
해당 사항 없음 이 요소를 생략하면 정책 |
---|---|
접속 상태 | 선택사항 |
유형 | 문자열 |
하위 요소
이 섹션에서는 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 캐싱
GET
작업은 'rating' 값을 검색하여 캐시에 '10' 값을 추가합니다. 정책의<ExpiryTimeInSecs>
는 60입니다.- 30초 후
GET
정책이 다시 실행되고 캐시에서10
을 가져옵니다. - 5초 후
PUT
정책은rating
값을10
으로 업데이트하고PUT
정책의<ExpiryTimeInSecs>
은 20입니다. 캐시는 새 값으로 즉시 새로고침되며, 20초 동안 캐시에 보관되는 것으로 설정됩니다.PUT
작업이 시작되지 않은 경우 첫 번째GET
작업에서 처음에 채워진 캐시는 처음 60초에서 남아서 30초 더 지속합니다. - 15초 후 또 다른
GET
이 실행되고8
값을 가져옵니다.
<Get> 요소
지정된 키의 값을 검색합니다. <Get>
, <Put>
, <Delete>
중 하나 이상을 사용해야 합니다.
Apigee는 KVM에 저장된 모든 데이터를 암호화합니다. 자세한 내용은 암호화 키 정보를 참조하세요. <Get>
을 사용하면 Apigee는 저장된 데이터를 복호화하고 메시지 컨텍스트의 변수에 할당합니다. 변수 이름은 assignTo
속성을 사용하여 지정됩니다.
루트 요소의 mapIdentifier
속성 또는 <MapName>
요소를 사용하여 KVM 이름을 지정해야 합니다.
정책에 여러 Get
블록을 포함하여 KVM에서 여러 항목을 검색할 수 있습니다.
기본값 | 해당 사항 없음 |
---|---|
접속 상태 | <Put> 또는 <Delete> 이 없는 경우 필수입니다. |
유형 | 해당 사항 없음 |
속성
다음 표에서는 <Get> 요소의 속성을 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 |
---|---|---|---|
assignTo |
검색한 값을 할당해야 하는 변수입니다. |
해당 사항 없음 | 필수 |
index |
값이 여러 개인 키에서 가져올 항목의 색인 번호(1부터 시작하는 색인)입니다.
예를 들어 예시를 보려면 샘플의 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을 만들려면 다음을 참조하세요.
- Apigee UI로 KVM을 사용하여 UI에서 암호화된 환경 범위 KVM 만들기
- 조직 범위 키 값 맵 API
- 환경 범위 키 값 맵 API
- API 프록시 범위 키 값 맵 API
<Put override="false"> <Key> <Parameter ref="mykeyvar"/> </Key> <Value ref="myvalvar1"/> </Put>
기본값 | 해당 사항 없음 |
---|---|
접속 상태 | <Get> 또는 <Delete> 이 없는 경우 필수입니다. |
유형 | 해당 사항 없음 |
속성
다음 표에서는 <Put>
요소의 속성을 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 |
---|---|---|---|
override |
|
true |
선택사항 |
<Scope> 요소
KVM에 대한 접근성의 경계를 정의합니다. 기본 범위는 environment
입니다. 즉, 기본적으로 맵 항목은 환경(예: 테스트 또는 프로덕션)에서 실행되는 모든 API 프록시에서 공유합니다. 범위를 apiproxy
로 설정하면 KVM의 항목은 맵에 값을 쓰는 API 프록시로만 액세스할 수 있습니다.
맵 또는 맵 항목에 액세스하면 맵을 만들 때 사용한 범위 값 값을 지정해야 합니다. 예를 들어 apiproxy
범위로 맵을 만든 경우 값을 검색하거나 변경사항을 적용하거나 항목을 삭제할 때 apiproxy
범위를 사용해야 합니다.
<Scope>environment</Scope>
기본값 | environment |
---|---|
접속 상태 | 선택사항 |
유형 | 문자열 |
유효한 값 |
|
<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 |
설정하려는 키 값이 포함된 변수의 이름을 지정합니다. | 해당 사항 없음 | 여는 태그와 닫는 태그 사이에 리터럴 값이 제공되지 않은 경우 필수입니다. 리터럴 값이 제공되면 금지됩니다. |
오류 참조
이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
오류 코드 | HTTP 상태 | 원인 | 해결 |
---|---|---|---|
steps.keyvaluemapoperations.UnsupportedOperationException |
500 |
이 오류는 |
build |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
오류 이름 | 원인 | 해결 |
---|---|---|
InvalidIndex |
KeyValueMapOperations 정책의 <Get> 요소에 지정된 index 속성이 0 또는 음수이면 API 프록시 배포가 실패합니다. 색인은 1 에서 시작하므로 0 또는 음수인 정수의 색인은 잘못된 것으로 간주됩니다.
|
build |
KeyIsMissing |
이 오류는 <Key> 요소가 완전히 누락되거나 <Parameter> 요소가 KeyValueMapOperations 정책의 <InitialEntries> 요소 <Entry> 아래의 <Key> 요소와 함께 누락된 경우에 발생합니다.
|
build |
ValueIsMissing |
이 오류는 KeyValueMapOperations 정책 <InitialEntries> 요소의 <Entry> 요소 아래에 <Value> 요소가 누락되면 발생합니다. |
build |
스키마
사용 참고사항
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에 대한 자세한 내용은 다음 주제를 참조하세요.