6分鐘閱讀

網路拓撲 (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）是識別單台伺服器的數字 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 的項目顯示為拓撲連線。

故障排查

回應 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 命令時，以相同方式僅更改端點即可。

網路拓撲 (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)

相關文件

相關指南