KVS(キー・バリュー形式) APIガイド (v2.0)

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を使用するには次の2つが必要です。

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はHeaderではなく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.ja.md

関連ドキュメント:

ネットワークトポロジーAPIガイド — SK発行とLSSN確認方法
API結果コードガイド (RstVal)

← PreviousGraphify データ追加 API Next →Vercel管理API

KVS(キー・バリュー形式) APIガイド (v2.0)

📋 概要

🔑 開始前の準備物

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