giip

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

관련 문서:

← Previous
시스템 관리 API
Next →
Vercel 관리 API