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-TW.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`）