이 페이지는 Cloud Translation API를 통해 번역되었습니다.

키-값 맵 작업

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

런타임 시 검색을 위해 데이터를 저장하고자 하는 경우가 있습니다. 이러한 데이터는 API 프록시 로직에서 하드 코딩해서는 안 되는 만료되지 않는 데이터입니다. 여기에는 키 값 맵 (KVM)이 적합합니다. KVM은 암호화되거나 암호화되지 않은 키-값 문자열 쌍의 커스텀 컬렉션입니다. 다음은 두 가지 예입니다.

다른 유형의 지속성에 대해 알아보려면 캐싱 및 지속성 추가를 참조하세요.

KVM 시나리오

다음과 같은 상황에서 KVM이 유용합니다.

테스트 환경에서 하나의 대상 (또는 서비스 콜아웃) URL을 호출하고 프로덕션 환경에서 다른 대상 URL을 호출해야 하는 API 프록시가 있습니다. 프록시에 URL을 하드 코딩하는 대신 프록시가 어떤 환경에 있는지 감지하고, 관련 키-값 맵 작업 정책을 실행하고, 생성한 KVM 중 하나에서 올바른 타겟 URL을 검색하도록 할 수 있습니다. 나중에 타겟 중 하나 또는 모두가 변경되면 새 URL로 KVM을 업데이트하면 됩니다. 프록시가 새 값을 선택하므로 프록시 재배포는 필요하지 않습니다.
외부 서비스용 토큰, OAuth 토큰을 생성하는 데 필요한 사용자 인증 정보 또는 암호화 또는 JSON 웹 토큰 (JWT) 서명을 위해 Java 콜아웃 또는 자바스크립트에 사용되는 비공개 키와 같은 사용자 인증 정보, 비공개 키 또는 토큰을 저장하려고 합니다. 요청에 사용자 인증 정보, 키, 토큰을 전달하거나 프록시 로직으로 하드 코딩하는 대신 KVM(항상 암호화됨)에 저장하고, 이를 필요로 하는 대상에 대한 호출에서 동적으로 검색합니다.

키-값 문자열 쌍의 스토리지가 유용할 수 있는 다른 경우도 있을 수 있습니다. 일반적으로 다음과 같은 경우에 KVM을 사용하는 것이 좋습니다.

런타임 시 코드의 특정 위치에 다른 값이 필요한 경우
민감한 정보는 하드 코딩하지 않고 전달해야 하는 경우
캐시처럼 만료되지 않는 값을 저장하려는 경우

KVM에는 범위가 있음

범위는 'KVM이 사용 가능한 위치'를 의미합니다. KVM은 organization, environment, apiproxy 범위에서 만들 수 있습니다.

예를 들어 하나의 API 프록시에서만 KVM의 데이터가 필요한 경우 해당 API 프록시만 데이터에 액세스할 수 있는 apiproxy 범위에서 KVM을 만들 수 있습니다.

또는 테스트 환경의 모든 API 프록시가 키-값 맵에 액세스하도록 할 수 있습니다. 이 경우 환경 범위에서 키-값 맵을 만듭니다. 'prod' 환경에 배포된 프록시는 '테스트' 환경 범위의 KVM에 액세스할 수 없습니다. 프로덕션에서 동일한 KVM 키를 사용할 수 있도록 하려면 'prod' 환경으로 범위가 지정된 병렬 KVM을 만듭니다.

모든 환경의 모든 프록시가 동일한 KVM에 액세스하도록 하려면 organization 범위에서 KVM을 만듭니다.

참고: 이 주제에서 다루는 관리 UI에서 키-값 맵을 만들고 관리할 때는 environment 범위에서 만듭니다.

KVM 만들기에 관한 자세한 내용은 KVM 관리 및 사용을 참고하세요.

암호화된 KVM 정보

암호화된 KVM은 Apigee에서 생성한 AES-128 암호화 키로 암호화됩니다. KVM을 암호화하는 데 사용되는 키는 KVM의 범위에 저장됩니다. 예를 들어 조직 내에서 환경 범위에서 만든 모든 암호화된 KVM은 동일한 환경 범위 키를 사용하여 생성됩니다.

Edge는 암호화된 값의 표시를 다음과 같은 방식으로 처리합니다. 암호화된 KVM을 만드는 방법에 관한 자세한 내용은 KVM 관리 및 사용을 참고하세요.

Edge UI

암호화된 키-값 맵은 UI에 별표 (*****)로 마스킹된 값을 표시합니다. 예를 들면 다음과 같습니다.

Management API

관리 API에서 암호화된 값은 마스킹된 상태로 반환됩니다. 다음은 암호화된 KVM 호출의 샘플 관리 API 응답입니다.

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Trace 및 디버그

키-값 맵 작업 정책을 사용하여 암호화된 KVM 값을 검색할 때는 값을 저장할 변수 이름을 제공합니다. 암호화된 값을 가져오려면 KVM 키/값이 Trace 및 디버그 세션에 표시되지 않도록 변수 이름에 'private.' 접두사를 추가해야 합니다.

한도

핵심 지속성 서비스 (CPS)를 사용 설정한 조직의 경우:

KVM 이름/식별자는 대소문자를 구분합니다.
키 크기는 2KB로 제한됩니다.
값 크기는 10KB로 제한됩니다.

프라이빗 클라우드용 Apigee Edge의 경우 각 KVM이 15MB (키와 값을 합친 크기)를 초과해서는 안 됩니다. 이 한도를 초과하면 Private Cloud용 Apigee Edge에서 오류를 반환합니다. KVM의 크기를 확인하려면 nodetool cfstats 명령어를 사용하면 됩니다.

KVM이 클수록 성능이 저하될 수 있습니다. 따라서 성능을 향상하려면 큰 모놀리식 KVM을 더 작은 KVM으로 분할해야 합니다.

KVM 관리 및 사용

KVM을 만들고, 관리하고, 다양한 방식으로 사용할 수 있습니다. 이 섹션에서는 암호화된 KVM과 암호화되지 않은 KVM을 만들고 검색하는 다양한 옵션을 설명합니다.

KVM 만들기 및 업데이트

다음과 같은 방법으로 KVM을 만들고 업데이트할 수 있습니다.

키-값 맵 작업 정책 (암호화 없음)

API 프록시에서 런타임 KVM을 만들고 업데이트하려면 키-값 맵 작업 정책을 사용하세요. (정책에서 상위 요소의 mapIdentifier 속성에 KVM의 이름을 지정합니다.)

참고: 정책은 현재 암호화된 KVM의 생성을 지원하지 않지만 (이를 위해 관리 UI 또는 API 사용) 정책을 통해 암호화된 KVM을 업데이트할 수 있습니다.

<InitialEntries> 요소를 사용하면 UI에 정책을 저장하거나 API 프록시를 배포하는 즉시 새 KVM에 기본 항목 집합을 만들고 채울 수 있습니다(오프라인으로 개발한 경우). 정책에서 값이 변경되면 기존 값을 덮어씁니다. 모든 새 키-값은 기존 키-값과 함께 기존 KVM에 추가됩니다.

<Put> 요소는 KVM이 없는 경우 새 KVM을 만들며 하나 이상의 값을 가지는 키를 만듭니다. KVM이 이미 있는 경우 키-값이 추가됩니다(키가 이미 있는 경우 업데이트됨). KVM 정책에는 여러 <Put> 요소를 사용할 수 있습니다.
Management API

관리 API는 API 프록시에서 런타임이 아닌 관리자로서 KVM을 사용하기 위한 것입니다. 예를 들어 관리 API를 사용하여 테스트 환경에서 KVM을 삭제하고 다시 만드는 내부 스크립트가 있거나 모든 프록시가 선택할 수 있도록 KVM의 키 값을 재설정해야 할 수 있습니다. KVM의 런타임 조작의 경우 프록시에서 키-값 맵 작업 정책을 사용하세요.

키/값 지도 관리 API를 사용하면 모든 범위 (조직, 환경, apiproxy)에서 암호화된 KVM 및 키-값을 생성, 업데이트, 삭제할 수 있습니다.

관리 API로 암호화된 KVM을 만들려면 JSON 페이로드에 "encrypted" : "true"를 추가합니다. KVM은 만들 때만 암호화할 수 있습니다. 기존 KVM은 암호화할 수 없습니다.
관리 UI

에지 관리 UI에서는 UI에 표시되는 KVM의 유일한 범위인 환경 범위 KVM을 만들고 업데이트할 수 있습니다. 관리 UI는 런타임에 API 프록시의 KVM 데이터를 수동으로 관리하는 좋은 방법입니다. 자세한 내용은 환경 키-값 맵 만들기 및 수정을 참고하세요.

KVM 검색

암호화된 키-값 맵과 암호화되지 않은 키-값 맵은 같은 방식으로 검색하지만 키-값 맵 작업 정책을 사용하여 검색할 때 약간의 차이가 있습니다.

정책: 키-값 맵 작업 정책의 <Get> 요소를 사용하여 암호화되거나 암호화되지 않은 KVM을 검색합니다. 한 가지 작은 차이점은 정책을 통해 암호화된 값을 검색한다는 점입니다. 여기서는 참조 주제의 가져오기 작업 섹션에 설명된 대로 검색된 값이 포함될 변수의 이름에 'private.' 프리픽스를 추가해야 합니다. 이 프리픽스는 API 프록시를 디버깅하는 동안 Trace 및 디버그 세션의 값을 숨깁니다.
Management API: 관리 목적으로 환경 키-값 맵 만들기 및 수정을 사용하여 KVM 및 키/값을 가져올 수 있습니다. 예를 들어 JSON 정의를 가져오고 저장하여 KVM을 백업하려면 관리 API를 사용하세요. 하지만 암호화된 값은 API 응답에 ***** 로 표시된다는 점에 유의하세요.
관리 UI: 관리 UI에서 API > 환경 구성 > 키-값 맵(Classic Edge) 또는 관리 > 환경 > 키-값 맵 (새 에지)으로 이동하여 환경 범위 KVM을 볼 수 있습니다.

KVM 예시

KVM을 사용하여 URL에 값을 채우는 예는 https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html을 참고하세요.