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-CN/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-CN/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 个步骤

自我验证方法

失败案例及其症状

该变通方法的局限 (请了解后再使用)

相关文档

相关指南