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-CN.md

← Previous
网络安全策略 API
Next →
网络拓扑示例脚本