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）是識別單台伺服器的數字 ID。首次註冊伺服器（AgentAutoRegister）時，會為每台伺服器發放唯一的 LSSN。此後，在所有 KVSPut 資料發送時，都將使用該 LSSN 作為 

kKey
值。

流程概要:

伺服器註冊 (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% 一致。大小寫、空格都必須相同。
  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 的情況

以相同 

hostname
重新呼叫 AgentAutoRegister，將返回現有 LSSN。只要每台伺服器的 hostname 唯一，LSSN 也會保持唯一。

curl 中 jsondata 被截斷的情況

使用 

--data-urlencode
代替 
-d
，可安全發送包含特殊字元的 JSON 字串。大量資料請使用 
giipApiSk3
端點（參見下方 Sk3 部分）。

高效能日誌端點 (Sk3)

發送數千筆以上的連線資料或需要除錯時，請使用 

giipApiSk3
端點。

  • Endpoint: 
    https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 優勢: 防止大量 jsondata 發送時資料截斷，發生錯誤時自動記錄 Agent 環境資訊和 StackTrace
  • 使用方式: 使用 KVSPut 命令時，以相同方式僅更改端點即可。

相關文件

版本: 1.4 最後更新: 2026-06-19 來源檔案: 

giipv3/public/help/api-network-topology.zh-TW.md

← Previous
網絡安全策略 API
Next →
網絡拓撲範例腳本