키-값 맵 사용

Apigee X 문서를 보고 있습니다.
Apigee Edge 문서 보기

이 섹션에서는 키-값 맵(KVM)을 사용하는 방법을 설명합니다.

개요

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

다음에는 KVM에 데이터를 저장하는 광범위한 사용 사례 세 가지가 나와 있습니다.

  • 사용자 세션 데이터: 런타임에서만 생성되고 삭제된 데이터이며 런타임 외부에서 KVM 항목을 보거나 관리할 수 없습니다. 예를 들어 장바구니 콘텐츠가 있습니다.
  • 구성(예: 라우팅 규칙 및 테이블 조회): 일반적으로 런타임 외부에서 생성되지만 런타임에서 읽는 데이터입니다. UI 또는 API를 사용하여 이 데이터를 구성한 후 게이트웨이에서 변수 또는 읽기 전용 콘텐츠로 사용할 수 있습니다.

    예를 들어 테스트 환경에서 하나의 타겟(또는 서비스 콜아웃) URL과 프로덕션 환경의 또 다른 대상 URL을 호출해야 하는 API 프록시가 있습니다. API 프록시에 URL을 하드 코딩하는 대신 URL의 환경을 감지하고 관련 KeyValueMapOperations 정책을 실행하며 적절한 KVM에서 올바른 대상 URL을 검색할 수 있습니다.

    나중에 대상 하나 또는 둘 다 변경되면 KVM을 새 URL로 업데이트하기만 하면 됩니다. API 프록시는 새 값을 선택하며 재배포가 필요하지 않습니다.

  • 사용자 인증 정보: 외부 서비스의 토큰, OAuth 토큰을 생성하는 데 필요한 사용자 인증 정보, 암호화 또는 JWT(JSON Web Token) 서명을 위해 자바 콜아웃이나 자바스크립트에 사용되는 비공개 키와 같은 사용자 인증 정보, 개인 키 또는 토큰을 저장합니다. 요청에 사용자 인증 정보, 키 또는 토큰을 전달하거나 프록시 로직으로 하드 코딩하는 대신 KVM에 저장하고 이를 필요로 하는 대상으로 호출에서 동적으로 검색합니다.

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

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

경우에 따라서 속성 세트는 KVM보다 사용하기 쉬우므로 KVM의 훌륭한 대안이 될 수 있습니다. 자세한 내용은 속성 집합 사용을 참조하세요.

KVM 범위 정보

범위는 KVM을 사용할 수 있는 위치를 정의합니다. 다음 범위에서 KVM을 만들 수 있습니다.

범위 설명
API 프록시 API 프록시만 KVM에 액세스할 수 있습니다.
환경 특정 환경의 모든 API 프록시는 KVM에 액세스할 수 있습니다. 예를 들어 prod 환경에 배포된 API 프록시가 test 환경의 KVM에 액세스하지 못하도록 할 수 있습니다. 프로덕션에서 동일한 KVM 키를 사용할 수 있게 하려면 범위가 prod 환경으로 지정된 병렬 KVM을 만듭니다.
조직 모든 환경의 모든 API 프록시가 KVM에 액세스할 수 있습니다.

KVM 암호화 정보

Apigee X에서 API 프록시의 모든 KVM 항목, 조직, 환경 범위는 Apigee 조직이 프로비저닝될 때 제공되는 Cloud KMS 키를 사용하여 보호됩니다(조직 리소스의 runtimeDatabaseEncryptionKey 필드 참조). Apigee에서는 AES256이 암호화 표준으로 사용됩니다.

Apigee Hybrid에서는 API 프록시, 조직, 환경 범위의 모든 KVM 항목에 대해 개별 암호화 키를 제공할 수 있습니다. Apigee에서는 AES128, AES196, AES256의 암호화 크기가 암호화 표준으로 허용됩니다.

KVM 만들기

다음 섹션의 설명대로 KVM을 만듭니다.

Apigee UI

새로운 (빈) KVM을 만들거나 KVM 목록을 보려면 다음 단계를 따르세요.

  1. Apigee UI에 로그인합니다.
  2. 관리 > 환경 > 키-값 맵을 선택합니다.
  3. 환경 드롭다운 목록에서 KVM을 만들려는 환경을 선택합니다.

    키-값 맵 페이지에 기존 KVM 목록이 표시됩니다. KVM을 만들지 않으면 목록이 비어 있습니다.

  4. 비어 있는 새 KVM을 만들려면 +키-값 맵을 클릭합니다.

    키-값 맵 추가 대화상자가 열립니다.

  5. 이름 필드에 KVM 이름을 입력합니다.

    이름은 문자, 숫자, 하이픈만 포함할 수 있습니다. 공백이나 다른 특수문자를 포함할 수 없습니다. 예: my-kvm-1

  6. Add(추가)를 클릭합니다.

    새 KVM이 목록에 표시됩니다.

Apigee API

Apigee API를 사용하여 다음 범위의 KVM을 만들고 나열하고 삭제합니다.

KVM 정책

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

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

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

디버깅

KeyValueMapOperations 정책을 사용하여 암호화된 KVM 값을 검색할 때 값을 저장할 변수 이름을 제공합니다. 모든 KVM 값이 암호화되므로 KVM 키-값 쌍이 디버그 세션에 표시되지 않도록 변수 이름에 private. 프리픽스를 추가해야 합니다.

KVM 검색

KeyValueMapOperations 정책의 <Get> 요소를 사용하여 KVM을 검색합니다. 모든 KVM 값은 암호화되므로 private. 프리픽스를 검색된 값이 포함될 변수 이름에 추가합니다. 이 프리픽스는 API 프록시를 디버깅하는 동안 디버그 세션에서 값을 숨깁니다. 자세한 내용은 <Get> 요소를 참조하세요.

KVM 삭제

다음 섹션의 설명대로 KVM을 삭제합니다.

Apigee UI

KVM을 삭제하려면 다음 안내를 따르세요.

  1. Apigee UI에 로그인합니다.
  2. 관리 > 환경 > 키-값 맵을 선택합니다.
  3. 환경 드롭다운 목록에서 KVM을 삭제할 환경을 선택합니다.

    키-값 맵 페이지에 기존 KVM 목록이 표시됩니다.

  4. 삭제하려는 KVM 위에 커서를 놓습니다.
  5. 삭제를 클릭합니다.
  6. 삭제를 클릭하여 작업을 확인합니다.

    KVM이 삭제되고 목록에서 삭제됩니다.

Apigee API

다음 Apigee API 중 하나를 사용하여 범위에 따라 KVM을 삭제합니다.