11分鐘閱讀

網路拓撲 (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）是識別單台伺服器的數字 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`	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) 各語言完整範例腳本

資料確認方式

執行腳本後，請依以下步驟確認資料。

伺服器註冊確認: 在 基本資訊管理 > 伺服器清單 選單中確認對應主機名稱的伺服器已註冊。
DB 映射確認: 確認 client_net_address 值與 tManagedDatabase.db_host 完全一致。
拓撲檢視器: 前往 /admin/network-topology 頁面，確認節點間連線已啟用。資料在發送後約 1~2 分鐘內即時反映。

資料完整性規則

插入資料前，請務必確認以下條件。

IP 映射: tLSvr.ips 欄位必須是 [{"CIDR":"10.0.0.5/24"}] 形式的 JSON 陣列。如果是簡單字串，拓撲中會將其分離為 'External' 節點。
DB 主機一致: db_connections 的 client_net_address 值必須在文字層級與 tManagedDatabase.db_host 100% 一致。大小寫、空格都必須相同。
JSON Depth: 序列化包含 kValue 陣列的 jsondata 時，請使用 Depth 10 以上進行編碼。深度不足會導致子物件被截斷。
state 值: 僅 netstat kValue 中 state 為 ESTABLISHED 的項目顯示為拓撲連線。
kFactor 無法變更: 查詢 SP (pApiNet3dDatabyAK) 被硬編碼為只讀取 netstat 與 db_connections 這兩個字面量。若以任意 kFactor(例如 my_graph)執行 KVSPut，回應會是 RstVal 200(儲存成功)，但拓撲介面上不會報錯，也不會出現任何內容。 tKVS 本身是接受任何值的通用儲存區，因此請勿把儲存成功誤解為「會顯示在介面上」。
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 格式是否有效，檢查巢狀引號跳脫

拓撲中未顯示連線的情況

確認 netstat kValue 的 state 值是否為準確的 ESTABLISHED（大寫）
確認 db_connections 的 client_net_address 與 GIIP 中註冊的 DB 主機 IP 完全一致
確認 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 命令時，以相同方式僅更改端點即可。

附錄: 用此佈局呈現非網路資料 (通用重複利用)

先講結論

目前不存在直接接收任意 {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" "出貨請求"

執行後開啟 /zh-TW/network-topology，即可看到訂單接收 → 付款核准 → 出貨指令 3 個節點由邊相連(反映需 1~2 分鐘)。

自我驗證方式

是否已儲存 — 確認每次 KVSPut 的回應是否為 {"RstVal":200}。

是否查詢得到 — 開啟介面前先用 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。 如果這裡看不到，介面上也不會出現 — 請查看下方的失敗案例。

在介面上 — 查看 /zh-TW/network-topology 右下角的節點數 / 連線數是否如預期增加。

失敗案例及其症狀

所做操作	症狀	原因	解決方式
把 `kFactor` 指定為 `my_graph` 等任意值	是 `RstVal 200`，但介面毫無變化	查詢 SP 只讀取 `netstat`/`db_connections`	把 `kFactor` 改為 `netstat`
把任意 ID(訂單編號等)當作 `kKey` 使用	儲存成功，介面無變化	`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 中推進設計。

網路拓撲 (Net3D) API 參考

開始前的準備工作

什麼是 LSSN?

認證方式

Step 1: 伺服器註冊 (AgentAutoRegister) — 取得 LSSN

Step 2: 伺服器間連線發送 (netstat KVSPut)

Step 3: DB 連線資訊發送 (db_connections KVSPut)

Step 4: DB 清單查詢 (ManagedDatabaseList)

各語言完整範例腳本

資料確認方式

資料完整性規則

故障排查

回應 RstVal 不為 200 的情況

拓撲中未顯示連線的情況

遺失 LSSN 的情況

curl 中 jsondata 被截斷的情況

高效能日誌端點 (Sk3)

附錄: 用此佈局呈現非網路資料 (通用重複利用)

先講結論

對應規則 — 把自己的領域套到 Net3D 模型上

輸入結構

複製貼上即可執行的完整範例 — 訂單處理流程 3 個步驟

自我驗證方式

失敗案例及其症狀

此變通方式的限制 (請了解後再使用)

相關文件

相關指南