giip
SES 商机登记
6分钟阅读

网络拓扑 (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 字段:

字段值
tokenYOUR_SK
textAgentAutoRegister
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 字段:

字段值说明
tokenYOUR_SK认证密钥
textKVSPut 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_ipstring连接目标服务器 IP
remote_portinteger连接目标端口
process_namestring创建连接的进程名
statestring连接状态。仅 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 字段:

字段值说明
tokenYOUR_SK认证密钥
textKVSPut 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_addressstring源服务器 IP。必须与 tManagedDatabase.db_host 完全一致才能创建 DB 链接
program_namestring执行程序名。在拓扑 Outgoing 节点标签中显示
cpu_loadinteger查询负载(%)。决定连接线粗细及粒子速度
last_sqlstring当前执行中的 SQL 语句。在详情查看弹窗中显示
query_hashstringSQL 语句哈希。用于相同查询的分组

Step 4: DB 列表查询 (ManagedDatabaseList)

查询项目中注册的受管数据库列表。

  • Endpoint: POST https://YOUR_API_URL/api/giipApi
  • Content-Type: application/x-www-form-urlencoded

请求 Body 字段:

字段值
tokenYOUR_SK
textManagedDatabaseList 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

相关指南

API 结果代码 (RstVal)基于 tDefRst 表的 API 结果值和消息标准定义API概览与认证通用响应格式、错误代码和 AK/SK 身份验证Sk3 高性能日志 API用于智能体错误检测和数据完整性校验的日志桥接器
← Previous网络安全策略 APINext →网络拓扑示例脚本