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

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

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

---

시작 전 준비물

항목	설명	얻는 방법
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인 항목만 토폴로지 연결선으로 표시됩니다.

---

트러블슈팅

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

---

관련 문서

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

---

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