키-값 맵 작업

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

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

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

KVM 시나리오

KVM이 유용한 상황은 다음과 같습니다.

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

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

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

KVM에 범위가 있음

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

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

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

모든 환경의 모든 프록시가 동일한 KVM에 액세스하도록 하려면 organization 범위에서 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 값을 검색할 때 값을 저장할 변수 이름을 제공합니다. 암호화된 값을 가져오려면 'private.' 프리픽스를 변수 이름에 추가해야 합니다. 그러면 KVM 키-값이 Trace 및 디버그 세션에 표시되지 않습니다.

한도

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

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

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

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

KVM 관리 및 사용

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

KVM 만들기 및 업데이트

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

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

  API 프록시를 통한 런타임 KVM 생성 및 업데이트의 경우 키-값 맵 작업 정책을 사용합니다. (정책에서 상위 요소의 mapIdentifier 속성에 KVM의 이름을 지정합니다.)

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

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

• 관리 API

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

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

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

• 관리 UI

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

KVM 검색

키 값 맵 작업 정책으로 검색할 때 약간의 차이가 있지만 암호화되거나 암호화되지 않은 키 값 맵을 같은 방식으로 검색합니다.

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

KVM 예시

KVM을 사용하여 URL의 값을 채우는 예는 환경별 KVM으로 타겟 URL 템플릿화를 참고하세요.