giip

네트워크 토폴로지(Net3D) API 레퍼런스

이 가이드만 읽으면 GIIP 네트워크 토폴로지(Net3D) 시각화에 필요한 데이터를 직접 만들어 넣을 수 있습니다.

🔌 네트워크 토폴로지 페이지로 이동 →

시작 전 준비물

항목설명얻는 방법
SK (Secret Key)API 인증에 사용하는 비밀 키GIIP 관리 화면의 
lsvrdetail
(서버 상세) 또는 
corpgroup
(법인·그룹 관리) 페이지에서 확인
API URLGIIP 서버 주소예: 
https://your-api.azurewebsites.net
LSSN서버 등록 후 발급되는 고유 세션 번호Step 1 완료 후 응답에서 취득

LSSN이란?

LSSN(Long-term Session Serial Number)은 서버 1대를 식별하는 숫자 ID입니다. 서버를 처음 등록(AgentAutoRegister)하면 서버마다 고유한 LSSN이 발급됩니다. 이후 모든 KVSPut 데이터 전송 시 

kKey
값으로 이 LSSN을 사용합니다.

흐름 요약:

서버 등록 (AgentAutoRegister) → LSSN 발급 → LSSN을 kKey로 사용하여 netstat/db_connections 전송

인증 방식

  • Content-Type: 
    application/x-www-form-urlencoded
  • 인증 위치: HTTP 헤더가 아닌 요청 바디의 
    token
    필드    에 SK 값을 포함
  • 잘못된 방식: 
    Authorization: Bearer YOUR_SK
    (사용 불가)
  • 올바른 방식: 바디에 
    token=YOUR_SK
    포함

Step 1: 서버 등록 (AgentAutoRegister) — LSSN 획득

서버를 GIIP에 등록하고 LSSN을 받습니다. 이 LSSN을 반드시 저장하세요.

  • Endpoint: 
    POST https://YOUR_API_URL/api/giipApi?cmd=AgentAutoRegister
  • Content-Type: 
    application/x-www-form-urlencoded

요청 Body 필드:

필드값
token
YOUR_SK
text
AgentAutoRegister
jsondata
아래 JSON을 문자열로 직렬화한 값

jsondata 예시:

{
  "hostname": "WEB-SRV-01",
  "os": "Windows Server 2022",
  "cpu_cores": 8,
  "ipv4_local": "10.0.0.5"
}

curl 예시:

curl -X POST "https://YOUR_API_URL/api/giipApi?cmd=AgentAutoRegister" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "text=AgentAutoRegister" \
     --data-urlencode 'jsondata={"hostname":"WEB-SRV-01","os":"Windows Server 2022","cpu_cores":8,"ipv4_local":"10.0.0.5"}'

응답 예시:

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

중요: 응답의 

lssn
값(예: 
123456
)을 반드시 저장하세요. Step 2, 3의 모든 요청에서 
kKey
로 사용합니다.

Step 2: 서버 간 연결 전송 (netstat KVSPut)

현재 서버에서 외부 서버로 향하는 TCP 연결 정보를 전송합니다.

  • Endpoint: 
    POST https://YOUR_API_URL/api/giipApi
    (cmd 파라미터 없음)
  • Content-Type: 
    application/x-www-form-urlencoded

요청 Body 필드:

필드값설명
token
YOUR_SK인증 키
text
KVSPut kType kKey kFactor
리터럴 고정 문자열 (그대로 입력)
jsondata
아래 JSON을 문자열로 직렬화한 값실제 데이터

jsondata 예시:

{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "netstat",
  "kValue": [
    {
      "remote_ip": "10.0.0.10",
      "remote_port": 8080,
      "process_name": "nginx.exe",
      "state": "ESTABLISHED"
    },
    {
      "remote_ip": "10.0.0.20",
      "remote_port": 3306,
      "process_name": "myapp.exe",
      "state": "ESTABLISHED"
    }
  ]
}

curl 예시:

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

응답 예시:

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

kValue 항목별 필드 설명:

필드타입설명
remote_ip
string연결 대상 서버 IP
remote_port
integer연결 대상 포트
process_name
string연결을 생성한 프로세스명
state
string연결 상태. 
ESTABLISHED
인 항목만 토폴로지에 선(Link)으로 표시

주의: 

state
가 
ESTABLISHED
인 항목만 토폴로지 화면에 연결선으로 표시됩니다.

Step 3: DB 연결 정보 전송 (db_connections KVSPut)

애플리케이션 서버에서 DB 서버로 전송하는 쿼리 및 부하 정보를 전송합니다.

  • Endpoint: 
    POST https://YOUR_API_URL/api/giipApi
    (netstat과 동일)
  • Content-Type: 
    application/x-www-form-urlencoded

요청 Body 필드:

필드값설명
token
YOUR_SK인증 키
text
KVSPut kType kKey kFactor
리터럴 고정 문자열 (그대로 입력)
jsondata
아래 JSON을 문자열로 직렬화한 값실제 데이터

jsondata 예시:

{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "db_connections",
  "kValue": [
    {
      "client_net_address": "10.0.0.5",
      "program_name": "MyApp.exe",
      "cpu_load": 15,
      "last_sql": "SELECT * FROM users WHERE id = 1",
      "query_hash": "0xAB12CD34"
    },
    {
      "client_net_address": "10.0.0.5",
      "program_name": "MyApp.exe",
      "cpu_load": 42,
      "last_sql": "UPDATE orders SET status = 'shipped' WHERE order_id = 9901",
      "query_hash": "0xCD56EF78"
    }
  ]
}

curl 예시:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "text=KVSPut kType kKey kFactor" \
     --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"db_connections","kValue":[{"client_net_address":"10.0.0.5","program_name":"MyApp.exe","cpu_load":15,"last_sql":"SELECT * FROM users WHERE id = 1","query_hash":"0xAB12CD34"}]}'

응답 예시:

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

kValue 항목별 필드 설명:

필드타입설명
client_net_address
string소스 서버 IP. 
tManagedDatabase.db_host
와 정확히 일치해야 DB 링크 생성
program_name
string실행 프로그램명. 토폴로지 Outgoing 노드 라벨로 표시
cpu_load
integer쿼리 부하(%). 링크 선의 굵기 및 파티클 속도 결정
last_sql
string현재 실행 중인 SQL 문. 상세 보기 모달에 표시
query_hash
stringSQL 구문 해시. 동일 쿼리 그룹화에 사용

Step 4: DB 목록 조회 (ManagedDatabaseList)

프로젝트에 등록된 관리 대상 데이터베이스 목록을 조회합니다.

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

요청 Body 필드:

필드값
token
YOUR_SK
text
ManagedDatabaseList mssql
(db_type 지정 가능)

curl 예시:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "text=ManagedDatabaseList mssql"

응답 예시:

{
  "RstVal": 200,
  "RstMsg": "Success",
  "data": [
    {
      "db_host": "10.0.0.30",
      "db_name": "ProductionDB",
      "db_type": "mssql"
    }
  ]
}

token
에 포함된 SK가 프로젝트 정보를 내포하므로 
csn
을 별도로 전달할 필요가 없습니다. 서버가 자동으로 처리합니다.

언어별 전체 예제 스크립트

PowerShell · Bash · Python 전체 예제 스크립트는 분량 관계로 별도 가이드로 분리했습니다.

📘 네트워크 토폴로지(Net3D) 언어별 예제 스크립트

데이터 확인 방법

스크립트 실행 후 아래 단계로 데이터를 확인하세요.

  1. 서버 등록 확인: 
    기본정보 관리 > 서버 인벤토리
    메뉴에서 해당 호스트명의 서버가 등록되었는지 확인합니다.
  2. DB 매핑 확인: 
    client_net_address
    값이 
    tManagedDatabase.db_host
    와 정확히 일치하는지 확인합니다.
  3. 토폴로지 뷰어: 
    /admin/network-topology
    페이지로 이동하여 노드 간 연결선이 활성화되는지 확인합니다. 데이터는 전송 후 약 1~2분 내 실시간 반영됩니다.

데이터 정합성 규칙

데이터를 넣기 전에 반드시 아래 조건을 확인하세요.

  1. IP 매핑: 
    tLSvr.ips
    필드는 반드시 
    [{"CIDR":"10.0.0.5/24"}]
    형태의 JSON 배열이어야 합니다. 단순 문자열이면 토폴로지에서 'External' 노드로 분리됩니다.
  2. DB 호스트 일치: 
    db_connections
    의 
    client_net_address
    값이 
    tManagedDatabase.db_host
    와 텍스트 레벨에서 100% 일치해야 DB 링크가 생성됩니다. 대소문자, 공백까지 동일해야 합니다.
  3. JSON Depth: 
    kValue
    배열을 포함한 jsondata 전체를 직렬화할 때 Depth 10 이상으로 인코딩합니다. 깊이가 부족하면 하위 객체가 잘립니다.
  4. state 값: 
    netstat
    kValue에서 
    state
    가 
    ESTABLISHED
    인 항목만 토폴로지 연결선으로 표시됩니다.

트러블슈팅

응답 RstVal이 200이 아닌 경우

RstVal의미조치
401인증 실패
token
값(SK)이 올바른지 확인. HTTP 헤더가 아닌 바디에 있는지 확인
400잘못된 요청
text
필드 값이 정확한지 확인 (
KVSPut kType kKey kFactor
리터럴)
500서버 오류
jsondata
JSON 형식이 유효한지 확인. 중첩 따옴표 이스케이프 확인

토폴로지에 연결선이 표시되지 않는 경우

  1. netstat
    kValue의 
    state
    값이 정확히 
    ESTABLISHED
    (대문자)인지 확인
  2. db_connections
    의 
    client_net_address
    가 GIIP에 등록된 DB 호스트 IP와 완전히 동일한지 확인
  3. tLSvr.ips
    가 단순 문자열이 아닌 
    [{"CIDR":"..."}]
    JSON 배열인지 확인

LSSN을 분실한 경우

AgentAutoRegister를 동일한 

hostname
으로 재호출하면 기존 LSSN이 반환됩니다. 서버마다 hostname이 고유하면 LSSN도 고유하게 유지됩니다.

curl에서 jsondata가 잘리는 경우

-d
대신 
--data-urlencode
를 사용하면 특수문자가 포함된 JSON 문자열도 안전하게 전송됩니다. 대용량 데이터는 
giipApiSk3
엔드포인트를 사용하세요 (아래 Sk3 항목 참조).

Python에서 SK 미정의(NameError) 오류

이 가이드의 Python 예제는 

AT
변수 하나를 사용합니다. 
SK
변수를 따로 정의하지 않도록 주의하세요.

고성능 로깅 엔드포인트 (Sk3)

수천 건 이상의 연결 데이터를 전송하거나 디버깅이 필요할 때 

giipApiSk3
엔드포인트를 사용하세요.

  • Endpoint: 
    https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 장점: 대용량 jsondata 전송 시 데이터 절단 방지, 오류 발생 시 에이전트 환경 정보와 StackTrace 자동 기록
  • 사용법: KVSPut 명령 사용 시 동일한 방식으로 엔드포인트만 변경하면 됩니다.

관련 문서

버전: 1.4 최종 업데이트: 2026-06-19 소스 파일: 

giipv3/public/help/api-network-topology.ko.md

← Previous
Network & Security Policy API
Next →
Network Topology (Net3D) Example Scripts