KVS(키-값 저장소) API 가이드 (v2.0)

GIIP 플랫폼의 유연한 데이터 저장소인 KVS(Key-Value Store)를 통해 인프라 상태 데이터(factor)를 기록하고 조회하는 전체 API를 설명합니다.

🔌 KVS 목록 페이지로 이동 →

---

📋 개요

KVS는 에이전트가 수집한 성능 메트릭, 네트워크 연결 정보, 인벤토리, 프로세스 목록 등 다양한 시계열 및 정형 데이터를 저장하는 범용 키-값 저장소입니다.

API	역할	인증 방식	엔드포인트
KVSPut	데이터 기록(쓰기)	Body token 필드 (SK)	giipApiSk2 / giipApiSk3
KVSFactorLast	최신 데이터 1건 조회	AK 헤더 또는 Body token (SK)	giipApi(AK) / giipApiSk2(SK)
KVSFactorList	이력 목록 조회	x-giip-ak / x-giip-sk 헤더	giipApi

---

🔑 시작 전 준비물

KVS API를 사용하려면 다음 두 가지가 필요합니다.

1. SK (Secret Key)

giipAgent.cfg 파일의 sk 필드 값입니다. KVSPut 요청 시 Body의 token 필드로 전달합니다.

취득 방법: GIIP 관리 화면의 lsvrdetail(서버 상세) 또는 corpgroup(법인·그룹 관리) 페이지에서 확인할 수 있습니다.

// giipAgent.cfg 예시
{
  "sk": "your-secret-key-here"
}

2. LSSN (서버 식별 번호)

tLSvr.LSsn 컬럼 값입니다. kType이 "lssn"일 때 kKey로 사용합니다.

SK 발급 및 LSSN 확인 방법은 네트워크 토폴로지 API 가이드를 참조하세요.

---

✍️ KVSPut — 데이터 기록하기

개념

KVSPut은 에이전트가 수집한 데이터를 KVS에 저장하는 쓰기 API입니다. kType + kKey + kFactor의 조합으로 저장 위치를 지정하고, kValue에 실제 데이터를 담습니다.

요청 구조

• 엔드포인트: POST https://YOUR_API_URL/api/giipApiSk2 (또는 giipApiSk3)
• Content-Type: application/x-www-form-urlencoded

Body 필드	필수	설명
token	✅	SK 값 (giipAgent.cfg의 sk)
text	✅	리터럴 문자열: KVSPut kType kKey kFactor kValue (변수 아님, 이 그대로 전송)
jsondata	✅	JSON 문자열: {"kType":"...","kKey":"...","kFactor":"...","kValue":...}

주의: text 필드의 값은 KVSPut kType kKey kFactor kValue라는 고정 문자열 그대로 전송합니다. 실제 데이터 식별자는 모두 jsondata 안에 들어갑니다.

jsondata 필드 설명

필드	타입	설명	예시
kType	string	키 유형 ("lssn" 또는 "database")	"lssn"
kKey	string	서버 LSSN 또는 DB ID (반드시 숫자형 문자열)	"123456"
kFactor	string	데이터 분류 카테고리명	"netstat"
kValue	any	실제 저장할 데이터 (JSON 배열 또는 객체)	[{...}]

kType / kKey 규칙

kType	의미	kKey 값
"lssn"	서버 단위 데이터	tLSvr.LSsn 컬럼 값 (숫자 문자열)
"database"	DB 단위 데이터	tManagedDatabase.mdb_id 컬럼 값 (숫자 문자열)

kKey는 반드시 숫자형 문자열이어야 합니다. 호스트명("myserver")이나 UUID("abc-123-...")는 허용되지 않습니다.

주요 kFactor 목록

kFactor	설명	kValue 형식
netstat	서버 간 TCP 연결 정보	[{remote_ip, remote_port, process_name, state}]
db_connections	DB 연결 정보	[{client_net_address, program_name, cpu_load, last_sql}]
heartbeat	에이전트 생존 신호	{"status":"alive","timestamp":"..."}
netinv	서버 인벤토리	{hostname, os, cpu_cores, ipv4_local}
processlist	실행 프로세스 목록	[{pid, name, cpu_percent, memory_mb}]
custom_factor	사용자 정의 데이터	자유 형식 JSON

코드 예시

아래 예시는 LSSN 123456 서버의 netstat 데이터를 KVS에 기록합니다. YOUR_API_URL과 YOUR_SK를 실제 값으로 교체하세요.

curl

curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[{"remote_ip":"10.0.0.5","remote_port":5432,"process_name":"python","state":"ESTABLISHED"}]}'

PowerShell

$body = @{
    token    = "YOUR_SK"
    text     = "KVSPut kType kKey kFactor kValue"
    jsondata = '{"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[{"remote_ip":"10.0.0.5","remote_port":5432,"process_name":"python","state":"ESTABLISHED"}]}'
}

$response = Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApiSk2" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

$response | ConvertTo-Json

Bash

SK="YOUR_SK"
API_URL="https://YOUR_API_URL/api/giipApiSk2"
LSSN="123456"

JSONDATA=$(cat <<'EOF'
{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "netstat",
  "kValue": [
    {
      "remote_ip": "10.0.0.5",
      "remote_port": 5432,
      "process_name": "python",
      "state": "ESTABLISHED"
    }
  ]
}
EOF
)

curl -X POST "$API_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=$SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode "jsondata=$JSONDATA"

Python

import requests
import json

API_URL = "https://YOUR_API_URL/api/giipApiSk2"
SK = "YOUR_SK"

kv_data = {
    "kType": "lssn",
    "kKey": "123456",
    "kFactor": "netstat",
    "kValue": [
        {
            "remote_ip": "10.0.0.5",
            "remote_port": 5432,
            "process_name": "python",
            "state": "ESTABLISHED"
        }
    ]
}

payload = {
    "token": SK,
    "text": "KVSPut kType kKey kFactor kValue",
    "jsondata": json.dumps(kv_data)
}

response = requests.post(
    API_URL,
    data=payload,
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

print(response.json())

응답 해석

성공 시

{
  "RstVal": 200,
  "RstMsg": "Success"
}

실패 예시

{
  "RstVal": 401,
  "RstMsg": "Unauthorized"
}

전체 응답 코드 목록은 API 결과 코드 가이드를 참조하세요.

---

🔍 KVSFactorLast — 최신 데이터 조회

특정 소스의 지정된 factor에 대해 가장 최근 기록 1건을 반환합니다.

인증

• Header: x-giip-ak: YOUR_AK / x-giip-sk: YOUR_SK

요청 형식

POST https://YOUR_API_URL/api/giipApi
Content-Type: application/x-www-form-urlencoded

text=KVSFactorLast <factorType>, <lssn>, <factor>

예시

LSSN 123456 서버의 최신 netstat 데이터 조회:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, netstat"

PowerShell:

$headers = @{
    "x-giip-ak" = "YOUR_AK"
    "x-giip-sk" = "YOUR_SK"
}

$body = @{
    text = "KVSFactorLast lssn, 123456, netstat"
}

Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApi" `
    -Headers $headers `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

SK 기반 조회 (giipApiSk2)

AK 없이 SK만으로 동일 법인 그룹(CGSn) 내 서버 데이터를 조회할 수 있습니다.

curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, netstat"

Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApiSk2" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body @{
        token = "YOUR_SK"
        text  = "KVSFactorLast lssn, 123456, netstat"
    }

권한 범위: SK의 CGSn(법인 그룹)에 속한 서버만 조회할 수 있습니다.

---

📜 KVSFactorList — 이력 목록 조회

특정 조건에 맞는 factor 데이터의 이력 목록을 반환합니다. *를 사용하면 해당 소스의 모든 factor 이력을 조회할 수 있습니다.

요청 형식

POST https://YOUR_API_URL/api/giipApi
Content-Type: application/x-www-form-urlencoded

text=KVSFactorList <factorType>, <lssn>, <factor>

예시

LSSN 123456 서버의 모든 factor 이력 조회:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorList lssn, 123456, *"

특정 factor(heartbeat)만 이력 조회:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorList lssn, 123456, heartbeat"

---

🛡️ Sk3 고성능 로깅

대용량 데이터를 기록하거나 데이터 정합성이 중요한 경우 giipApiSk3 엔드포인트를 사용하세요.

• 엔드포인트: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 장점:
  • 대량의 jsondata 전송 시 데이터 손실 방지
  • 기록 실패 시 에이전트의 상세 에러 로그(StackTrace)를 함께 저장하여 정합성 확보
• 활용 팁: KVSPut 사용 시 jsondata 내에 kType, kKey, kFactor, kValue 필드를 포함하면 Sk3 엔진이 자동으로 매핑하여 안정적으로 DB에 기록합니다.

# Sk3 엔드포인트로 KVSPut 호출 예시
curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk3" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[...]}'

---

🔧 트러블슈팅

KVSPut이 401 응답을 반환하는 경우

• token 필드의 SK 값이 올바른지 확인하세요.
• SK는 Header가 아닌 Body의 token 필드로 전달해야 합니다.

KVSPut이 400 응답을 반환하는 경우

• text 필드의 값이 정확히 KVSPut kType kKey kFactor kValue인지 확인하세요 (이 문자열 그대로).
• jsondata가 유효한 JSON 문자열인지 확인하세요.
• kKey가 숫자형 문자열("123456")인지 확인하세요. 호스트명이나 UUID는 허용되지 않습니다.

데이터가 저장되었는지 확인하는 방법

KVSPut 직후 KVSFactorLast로 동일한 kType/kKey/kFactor 조합을 조회하면 저장된 데이터를 확인할 수 있습니다.

# 1. 데이터 기록
curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"heartbeat","kValue":{"status":"alive","timestamp":"2026-06-19T10:00:00Z"}}'

# 2. 기록 확인
curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, heartbeat"

KVSFactorLast / KVSFactorList가 빈 결과를 반환하는 경우

• 해당 kType/kKey/kFactor 조합으로 저장된 데이터가 없는 경우입니다.
• KVSPut으로 먼저 데이터를 기록한 후 조회하세요.
• LSSN 번호가 올바른지 확인하세요.

---

문제 해결

증상	원인	해결
KVSPut이 401 반환	SK를 헤더로 전송했거나 token 값이 올바르지 않음	SK를 Body의 token 필드로 전달하고 값이 정확한지 확인
KVSPut이 400 반환	text가 리터럴 KVSPut kType kKey kFactor kValue와 다르거나 jsondata가 유효한 JSON이 아님	text는 고정 문자열 그대로 전송하고 jsondata를 올바른 JSON으로 직렬화
저장 실패 또는 kKey 오류	kKey가 숫자형 문자열이 아님(호스트명·UUID 사용)	tLSvr.LSsn 등 숫자 문자열을 kKey로 사용
KVSFactorLast/List가 빈 결과 반환	해당 kType/kKey/kFactor 데이터 미기록 또는 LSSN 오류	KVSPut으로 먼저 기록한 뒤 조회하고 LSSN 값을 확인

---

버전: 2.1 최종 업데이트: 2026-06-19 소스 파일: giipv3/public/help/api-kvs.ko.md

---

관련 문서:

• 네트워크 토폴로지 API 가이드 — SK 발급 및 LSSN 확인 방법
• API 결과 코드 가이드 (RstVal)