5分钟阅读

KVS (键值存储) API 指南 (v2.1)

通过 GIIP 平台的灵活数据存储 KVS（Key-Value Store），完整说明写入和查询基础设施状态数据（factor）的全部 API。

🔌 前往 KVS 列表 →

📋 概述

KVS 是存储代理收集的性能指标、网络连接信息、库存、进程列表等各种时序和结构化数据的通用键值存储。

API	角色	认证方式	端点
KVSPut	数据记录（写入）	Body `token` 字段 (SK)	`giipApiSk2` / `giipApiSk3`
KVSFactorLast	最新数据 1 条查询	AK 标头或 Body `token` (SK)	`giipApi`(AK) / `giipApiSk2`(SK)
KVSFactorList	历史列表查询	`x-giip-ak` / `x-giip-sk` 标头	`giipApi`

🔑 开始前的准备工作

使用 KVS API 需要以下两项。

1. SK (Secret Key)

giipAgent.cfg 文件的 sk 字段值。KVSPut 请求时作为 Body 的 token 字段传递。

获取方式: 在 GIIP 管理页面的 lsvrdetail（服务器详情）或 corpgroup（法人·组管理）页面中查看。

// giipAgent.cfg 示例
{
  "sk": "your-secret-key-here"
}

2. LSSN (服务器识别编号)

tLSvr.LSsn 列值。当 kType 为 "lssn" 时用作 kKey。

SK 发放及 LSSN 确认方法，请参考网络拓扑 API 指南。

✍️ KVSPut — 写入数据

概念

KVSPut 是将代理收集的数据存储到 KVS 的写入 API。通过 kType + kKey + kFactor 的组合指定存储位置，kValue 中存放实际数据。

请求结构

端点: POST https://YOUR_API_URL/api/giipApiSk2（或 giipApiSk3）
Content-Type: application/x-www-form-urlencoded

Body 字段	必须	说明
`token`	✅	SK 值 (`giipAgent.cfg` 的 `sk`)
`text`	✅	字面字符串: `KVSPut kType kKey kFactor kValue` (非变量，原样发送此字符串)
`jsondata`	✅	JSON 字符串: `{"kType":"...","kKey":"...","kFactor":"...","kValue":...}`

注意: text 字段的值原样发送 KVSPut kType kKey kFactor kValue 这个固定字符串。实际数据标识符全部放在 jsondata 中。

jsondata 字段说明

字段	类型	说明	示例
`kType`	string	键类型 (`"lssn"` 或 `"database"`)	`"lssn"`
`kKey`	string	服务器 LSSN 或 DB ID（必须是数字格式的字符串）	`"123456"`
`kFactor`	string	数据分类类别名	`"netstat"`
`kValue`	any	实际存储的数据（JSON 数组或对象）	`[{...}]`

kType / kKey 规则

kType	含义	kKey 值
`"lssn"`	服务器级数据	`tLSvr.LSsn` 列值（数字字符串）
`"database"`	DB 级数据	`tManagedDatabase.mdb_id` 列值（数字字符串）

kKey 必须是数字格式的字符串。 主机名（"myserver"）或 UUID（"abc-123-..."）不被接受。

主要 kFactor 列表

kFactor	说明	kValue 格式
`netstat`	服务器间 TCP 连接信息	`[{remote_ip, remote_port, process_name, state}]`
`db_connections`	DB 连接信息	`[{client_net_address, program_name, cpu_load, last_sql}]`
`heartbeat`	代理存活信号	`{"status":"alive","timestamp":"..."}`
`netinv`	服务器库存	`{hostname, os, cpu_cores, ipv4_local}`
`processlist`	运行中进程列表	`[{pid, name, cpu_percent, memory_mb}]`
`custom_factor`	用户自定义数据	自由格式 JSON

代码示例

以下示例将 LSSN 123456 服务器的 netstat 数据写入 KVS。将 YOUR_API_URL 和 YOUR_SK 替换为实际值。

curl

curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[{"remote_ip":"10.0.0.5","remote_port":5432,"process_name":"python","state":"ESTABLISHED"}]}'

PowerShell

$body = @{
    token    = "YOUR_SK"
    text     = "KVSPut kType kKey kFactor kValue"
    jsondata = '{"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[{"remote_ip":"10.0.0.5","remote_port":5432,"process_name":"python","state":"ESTABLISHED"}]}'
}

$response = Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApiSk2" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

$response | ConvertTo-Json

Bash

SK="YOUR_SK"
API_URL="https://YOUR_API_URL/api/giipApiSk2"

JSONDATA=$(cat <<'EOF'
{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "netstat",
  "kValue": [
    {
      "remote_ip": "10.0.0.5",
      "remote_port": 5432,
      "process_name": "python",
      "state": "ESTABLISHED"
    }
  ]
}
EOF
)

curl -X POST "$API_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=$SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode "jsondata=$JSONDATA"

Python

import requests
import json

API_URL = "https://YOUR_API_URL/api/giipApiSk2"
SK = "YOUR_SK"

kv_data = {
    "kType": "lssn",
    "kKey": "123456",
    "kFactor": "netstat",
    "kValue": [
        {
            "remote_ip": "10.0.0.5",
            "remote_port": 5432,
            "process_name": "python",
            "state": "ESTABLISHED"
        }
    ]
}

payload = {
    "token": SK,
    "text": "KVSPut kType kKey kFactor kValue",
    "jsondata": json.dumps(kv_data)
}

response = requests.post(
    API_URL,
    data=payload,
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

print(response.json())

响应解析

成功时

{
  "RstVal": 200,
  "RstMsg": "Success"
}

失败示例

{
  "RstVal": 401,
  "RstMsg": "Unauthorized"
}

完整响应代码列表，请参考 API 结果代码指南。

🔍 KVSFactorLast — 查询最新数据

返回特定来源的指定 factor 的最近 1 条记录。

认证

Header: x-giip-ak: YOUR_AK / x-giip-sk: YOUR_SK

请求格式

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

text=KVSFactorLast <factorType>, <lssn>, <factor>

示例

查询 LSSN 123456 服务器的最新 netstat 数据:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, netstat"

PowerShell:

$headers = @{
    "x-giip-ak" = "YOUR_AK"
    "x-giip-sk" = "YOUR_SK"
}

$body = @{
    text = "KVSFactorLast lssn, 123456, netstat"
}

Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApi" `
    -Headers $headers `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

基于 SK 的查询（`giipApiSk2`）

无需 AK，仅凭 SK 即可查询同一法人组（CGSn）内的服务器数据。

curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, netstat"

Invoke-RestMethod `
    -Method Post `
    -Uri "https://YOUR_API_URL/api/giipApiSk2" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body @{
        token = "YOUR_SK"
        text  = "KVSFactorLast lssn, 123456, netstat"
    }

权限范围: 仅可查询 SK 所属 CGSn（法人组）内的服务器。

📜 KVSFactorList — 查询历史列表

返回符合特定条件的 factor 数据的历史列表。使用 * 可以查询该来源的所有 factor 历史。

请求格式

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

text=KVSFactorList <factorType>, <lssn>, <factor>

示例

查询 LSSN 123456 服务器的所有 factor 历史:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorList lssn, 123456, *"

仅查询特定 factor（heartbeat）的历史:

curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorList lssn, 123456, heartbeat"

🛡️ Sk3 高性能日志

写入大量数据或数据完整性至关重要时，请使用 giipApiSk3 端点。

端点: https://giipfaw.azurewebsites.net/api/giipApiSk3
优势:
- 防止传输大量 jsondata 时数据丢失
- 写入失败时同步保存代理的详细错误日志（StackTrace），确保完整性
使用技巧: 使用 KVSPut 时，在 jsondata 中包含 kType、kKey、kFactor、kValue 字段，Sk3 引擎将自动映射，稳定写入 DB。

# 通过 Sk3 端点调用 KVSPut 示例
curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk3" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"netstat","kValue":[...]}'

🔧 故障排查

KVSPut 返回 401 的情况

确认 token 字段的 SK 值是否正确。
SK 必须通过 Body 的 token 字段传递，而非标头。

KVSPut 返回 400 的情况

确认 text 字段的值是否准确为 KVSPut kType kKey kFactor kValue（原样此字符串）。
确认 jsondata 是否为有效的 JSON 字符串。
确认 kKey 是否为数字格式的字符串（"123456"）。主机名和 UUID 不被接受。

确认数据是否已存储的方法

KVSPut 后立即用 KVSFactorLast 查询相同的 kType/kKey/kFactor 组合，即可确认存储的数据。

# 1. 写入数据
curl -X POST "https://YOUR_API_URL/api/giipApiSk2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=YOUR_SK" \
  --data-urlencode "text=KVSPut kType kKey kFactor kValue" \
  --data-urlencode 'jsondata={"kType":"lssn","kKey":"123456","kFactor":"heartbeat","kValue":{"status":"alive","timestamp":"2026-06-19T10:00:00Z"}}'

# 2. 确认写入
curl -X POST "https://YOUR_API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-giip-ak: YOUR_AK" \
  -H "x-giip-sk: YOUR_SK" \
  --data-urlencode "text=KVSFactorLast lssn, 123456, heartbeat"

KVSFactorLast / KVSFactorList 返回空结果的情况

该 kType/kKey/kFactor 组合尚无存储的数据。
请先用 KVSPut 写入数据后再查询。
确认 LSSN 编号是否正确。

故障排除

症状	原因	解决
KVSPut 返回 401	SK 以标头发送，或 `token` 值不正确	将 SK 通过 Body 的 `token` 字段传递并确认值正确
KVSPut 返回 400	`text` 与字面量 `KVSPut kType kKey kFactor kValue` 不符，或 `jsondata` 不是有效 JSON	`text` 原样发送固定字符串，并将 `jsondata` 序列化为有效 JSON
写入失败或 kKey 错误	`kKey` 不是数字格式的字符串（使用了主机名或 UUID）	使用 `tLSvr.LSsn` 等数字字符串作为 `kKey`
KVSFactorLast/List 返回空结果	该 `kType`/`kKey`/`kFactor` 无数据记录，或 LSSN 错误	先用 KVSPut 写入再查询，并确认 LSSN 值

版本: 2.1 最后更新: 2026-06-19 源文件: giipv3/public/help/api-kvs.zh-CN.md

相关文档:

网络拓扑 API 指南 — SK 发放和 LSSN 确认方法
API 结果代码指南 (RstVal)

KVS (键值存储) API 指南 (v2.1)

📋 概述

🔑 开始前的准备工作

1. SK (Secret Key)

2. LSSN (服务器识别编号)

✍️ KVSPut — 写入数据

概念

请求结构

jsondata 字段说明

kType / kKey 规则

主要 kFactor 列表

代码示例

curl

PowerShell

Bash

Python

响应解析

🔍 KVSFactorLast — 查询最新数据

认证

请求格式

示例

基于 SK 的查询（giipApiSk2）

📜 KVSFactorList — 查询历史列表

请求格式

示例

🛡️ Sk3 高性能日志

🔧 故障排查

KVSPut 返回 401 的情况

KVSPut 返回 400 的情况

确认数据是否已存储的方法

KVSFactorLast / KVSFactorList 返回空结果的情况

故障排除

相关指南

基于 SK 的查询（`giipApiSk2`）