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

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

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

⚠️ 이 문서의 적용 범위 — 먼저 읽으세요

이 문서는 서버·데이터베이스의 네트워크 토폴로지 전용 절차입니다. 여기 적힌 두 형식 (netstat, db_connections)은 Net3D 화면이 읽는 유일한 두 가지 형식입니다.

네트워크가 아닌 임의의 데이터(주문 흐름, 조직도, 서비스 의존 관계 등)를 이 3D 레이아웃으로 보여주고 싶다면 → 부록: 네트워크가 아닌 데이터를 이 레이아웃으로 보여주기 를 먼저 읽으세요. kFactor 만 임의 값으로 바꿔 tKVS 에 넣는 방법은 동작하지 않습니다 — 저장은 RstVal 200 으로 성공하지만 화면에는 에러 없이 아무것도 표시되지 않습니다.

---

시작 전 준비물

항목	설명	얻는 방법
SK (Secret Key)	API 인증에 사용하는 비밀 키	GIIP 관리 화면의 lsvrdetail(서버 상세) 또는 corpgroup(법인·그룹 관리) 페이지에서 확인
API URL	GIIP 서버 주소	예: 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	string	SQL 구문 해시. 동일 쿼리 그룹화에 사용

---

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인 항목만 토폴로지 연결선으로 표시됩니다.
5. kFactor는 바꿀 수 없습니다: 조회 SP(pApiNet3dDatabyAK)는 netstat과 db_connections 두 리터럴만 읽도록 하드코딩되어 있습니다. 임의의 kFactor(예: my_graph)로 KVSPut 하면 응답은 RstVal 200(저장 성공)이지만 토폴로지 화면에는 에러 없이 아무것도 나타나지 않습니다. tKVS 자체는 범용 저장소라 어떤 값이든 받아들이므로, 저장 성공을 "화면에 나온다"는 뜻으로 오해하지 마세요.
6. kKey는 이미 등록된 자산 ID여야 합니다: netstat은 kKey가 현재 CSN에 등록된 tLSvr.LSsn이어야 하고, db_connections는 tManagedDatabase.mdb_id여야 합니다. 등록되지 않은 임의의 키(주문번호, 계정 ID 등)를 kKey로 넣으면 그 행은 조회 대상에서 조용히 제외됩니다.

---

트러블슈팅

응답 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 명령 사용 시 동일한 방식으로 엔드포인트만 변경하면 됩니다.

---

부록: 네트워크가 아닌 데이터를 이 레이아웃으로 보여주기 (범용 재사용)

결론 먼저

임의의 {nodes, links} 를 그대로 받는 전용 "범용 그래프" 입력 경로는 현재 존재하지 않습니다. (giip #2526 에서 설계 추진 중)

• ❌ 되지 않는 것: kFactor 를 my_graph 같은 임의 값으로 바꿔 {nodes, links} 를 tKVS 에 넣기. → KVSPut 은 RstVal 200 을 돌려줍니다(tKVS 는 어떤 kFactor 든 저장하는 범용 저장소입니다). 하지만 Net3D 조회 SP 가 그 행을 읽지 않습니다. 화면은 에러 없이 비어 있습니다.
• ✅ 지금 되는 것: 내 데이터의 개체를 "서버"로, 관계를 "연결"로 매핑하면 임의의 방향 그래프를 오늘 바로 그릴 수 있습니다. 아래가 그 절차입니다.

매핑 규칙 — 내 도메인을 Net3D 모델에 맞추기

내 데이터	Net3D 에서의 표현	넣는 방법
개체(노드) 1개	서버 노드(구) 1개	AgentAutoRegister 로 등록 → LSSN 획득
개체의 표시 이름	노드 라벨	hostname 값이 그대로 노드 이름이 됩니다
개체의 고유 식별자	합성 IP	ipv4_local 에 겹치지 않는 IP 부여(예: 10.99.0.1)
관계(간선) 1개	연결선(Link)	netstat KVSPut 의 remote_ip 에 상대 개체의 합성 IP
관계의 라벨	링크의 프로세스명	process_name 값

💡 상대 개체를 반드시 등록해야 하는 것은 아닙니다. remote_ip 가 등록된 어느 서버의 IP 와도 일치하지 않으면 Net3D 가 그 IP 이름의 External 노드를 자동 생성합니다. 다만 이름이 IP 문자열 그대로이므로, 이름을 지정하고 싶은 개체는 AgentAutoRegister 로 등록하세요.

입력 스키마

① 개체 등록 — AgentAutoRegister

필드	타입	필수	제약	예시
hostname	string	✅	CSN 내 고유. 이 값이 노드 라벨이 됩니다	"주문접수"
ipv4_local	string	✅	유효한 IPv4. 개체마다 고유해야 간선이 정확히 이어집니다	"10.99.0.1"
os	string	—	자유 문자열. 노드 상세에 표시	"OrderFlow"
cpu_cores	integer	—	표시용	1

② 관계 전송 — KVSPut kType kKey kFactor

필드	타입	필수	제약	예시
kType	string	✅	"lssn" 고정	"lssn"
kKey	string	✅	출발 개체의 LSSN. 등록된 LSsn 이 아니면 무시됩니다	"123456"
kFactor	string	✅	"netstat" 고정. 다른 값은 화면에 나오지 않습니다	"netstat"
kValue	array	✅	간선 배열	아래 참조
kValue[].remote_ip	string	✅	도착 개체의 합성 IP. 127.*/0.0.0.0/::1 은 제외됩니다	"10.99.0.2"
kValue[].state	string	✅	"ESTABLISHED" 여야 간선이 생성됩니다("ESTAB" 도 허용)	"ESTABLISHED"
kValue[].process_name	string	—	간선 라벨로 표시	"결제요청"
kValue[].remote_port	integer	—	노드 버블에 표시	443

복붙하면 그대로 도는 완결 예시 — 주문 처리 흐름 3단계

SK, API_URL 두 줄만 바꾸면 그대로 실행됩니다.

#!/bin/bash
set -e
SK="YOUR_SK"
API_URL="https://YOUR_API_URL"

# --- ① 개체 3개를 "서버"로 등록하고 LSSN 획득 ---
register() {
  curl -s -X POST "$API_URL/api/giipApi?cmd=AgentAutoRegister" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "token=$SK" \
    --data-urlencode "text=AgentAutoRegister" \
    --data-urlencode "jsondata={\"hostname\":\"$1\",\"os\":\"OrderFlow\",\"cpu_cores\":1,\"ipv4_local\":\"$2\"}"
}

LSSN_A=$(register "ORDERFLOW-주문접수" "10.99.0.1" | grep -oE '"lssn":[0-9]+' | cut -d: -f2)
LSSN_B=$(register "ORDERFLOW-결제승인" "10.99.0.2" | grep -oE '"lssn":[0-9]+' | cut -d: -f2)
LSSN_C=$(register "ORDERFLOW-배송지시" "10.99.0.3" | grep -oE '"lssn":[0-9]+' | cut -d: -f2)
echo "LSSN: A=$LSSN_A B=$LSSN_B C=$LSSN_C"

# --- ② 관계(간선) 전송: 주문접수 → 결제승인 → 배송지시 ---
link() {
  curl -s -X POST "$API_URL/api/giipApi" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "token=$SK" \
    --data-urlencode "text=KVSPut kType kKey kFactor" \
    --data-urlencode "jsondata={\"kType\":\"lssn\",\"kKey\":\"$1\",\"kFactor\":\"netstat\",\"kValue\":[{\"remote_ip\":\"$2\",\"remote_port\":443,\"process_name\":\"$3\",\"state\":\"ESTABLISHED\"}]}"
  echo
}

link "$LSSN_A" "10.99.0.2" "결제요청"
link "$LSSN_B" "10.99.0.3" "배송요청"

실행 후 /ko/network-topology 를 열면 주문접수 → 결제승인 → 배송지시 3개 노드가 간선으로 이어져 나타납니다(반영까지 1~2분).

자기검증 방법

1. 저장됐는지 — 각 KVSPut 응답이 {"RstVal":200} 인지 확인합니다.
2. 조회되는지 — 화면을 열기 전에 API 로 직접 확인합니다.

   curl -s -X POST "$API_URL/api/giipApi" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=$SK" \
     --data-urlencode "text=Net3dData csn" \
     --data-urlencode "jsondata={\"csn\":YOUR_CSN,\"targetTime\":null}"

   응답의 servers 안에 방금 등록한 hostname 이, netstat_data 안에 합성 IP 가 보여야 합니다. 여기서 보이지 않으면 화면에도 나오지 않습니다 — 아래 실패 사례를 확인하세요.
3. 화면에서 — /ko/network-topology 우측 하단의 노드 수 / 링크 수 가 기대한 만큼 늘었는지 봅니다.

실패 사례와 그때의 증상

한 일	증상	원인	해결
kFactor 를 my_graph 등 임의 값으로 지정	RstVal 200 인데 화면에 아무 변화 없음	조회 SP 가 netstat/db_connections 만 읽음	kFactor 를 netstat 으로
kKey 에 임의 ID(주문번호 등) 사용	저장 성공, 화면 변화 없음	kKey 가 등록된 LSsn 이어야 함	먼저 AgentAutoRegister 로 LSSN 획득
{"nodes":[...],"links":[...]} 를 그대로 kValue 에	화면 변화 없음	Net3D 는 nodes/links 를 입력 형식으로 받지 않음	위 매핑 규칙을 따를 것
state 를 TIME_WAIT 등으로	노드는 뜨는데 간선이 없음	ESTABLISHED/ESTAB 만 간선이 됨	"ESTABLISHED" 사용
개체마다 같은 ipv4_local 사용	노드가 하나로 합쳐짐	IP 가 노드 식별에 쓰임	개체마다 고유 IP 부여
remote_ip 를 127.0.0.1 로	간선이 없음	루프백/0.0.0.0/::1 은 명시적으로 제외됨	실제 합성 IP 사용
간선이 아주 많은 큰 그래프	일부만 표시되거나 전부 빈 화면	응답이 FOR JSON 2033자 단위로 분할됨	응답을 직접 파싱한다면 JSON_... 컬럼 조각을 모두 이어붙인 뒤 파싱할 것

이 우회 방법의 한계 (알고 쓰세요)

• 모든 개체가 서버 노드(구) 로 그려집니다. 데이터 종류별로 모양을 다르게 할 수 없습니다.
• 노드를 클릭하면 서버 상세 모달이 열립니다(내 도메인 정보 화면이 아닙니다).
• 등록한 개체는 서버 인벤토리 목록에도 나타납니다. 실제 서버와 섞이므로 hostname 에 접두어(예: ORDERFLOW-)를 붙여 구분하는 것을 권장합니다.
• 간선의 색·입자 속도는 CPU 부하 기준이라 항상 기본 상태로 보입니다.

이 한계 없이 임의의 {nodes, links} 를 직접 넣는 범용 진입점은 giip #2526 에서 설계를 진행 중입니다.

---

관련 문서

• API 결과 코드 가이드 (RstVal)

---

버전: 1.5 최종 업데이트: 2026-09-14 소스 파일: giipv3/public/help/api-network-topology.ko.md