ネットワークトポロジー(Net3D) APIリファレンス

このガイドを読むだけで、GIIPネットワークトポロジー(Net3D)の視覚化に必要なデータを直接作成・送信できます。

🔌 ネットワークトポロジーページへ →

---

開始前の準備物

項目	説明	取得方法
SK (Secret Key)	API認証に使用する秘密鍵	GIIP管理画面の lsvrdetail(サーバー詳細) または corpgroup(法人・グループ管理) ページで確認
API URL	GIIPサーバーのアドレス	例: https://your-api.azurewebsites.net
LSSN	サーバー登録後に発行される固有セッション番号	Step 1完了後のレスポンスから取得

LSSNとは?

LSSN(Long-term Session Serial Number)は、1台のサーバーを識別する数値IDです。サーバーを初めて登録(AgentAutoRegister)すると、サーバーごとに固有のLSSNが発行されます。以降、すべてのKVSPutデータ送信時に kKey の値としてこのLSSNを使用します。

フロー概要:

サーバー登録 (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	string	SQL構文ハッシュ。同一クエリのグループ化に使用

---

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を紛失した場合

AgentAutoRegisterを同じ hostname で再呼び出しすると既存のLSSNが返されます。サーバーごとにhostnameが固有であれば、LSSNも固有に維持されます。

curlでjsondataが切り捨てられる場合

-d の代わりに --data-urlencode を使用すると、特殊文字を含むJSON文字列も安全に送信できます。大容量データは giipApiSk3 エンドポイントを使用してください(下記Sk3項目参照)。

---

高性能ロギングエンドポイント (Sk3)

数千件以上の接続データを送信したり、デバッグが必要な場合は giipApiSk3 エンドポイントを使用してください。

• Endpoint: https://giipfaw.azurewebsites.net/api/giipApiSk3
• メリット: 大容量jsondata送信時のデータ切断防止、エラー発生時にエージェント環境情報とStackTraceを自動記録
• 使用方法: KVSPutコマンド使用時と同様の方法でエンドポイントのみ変更すればOKです。

---

関連ドキュメント

• API結果コードガイド (RstVal)

---

バージョン: 1.4 最終更新: 2026-06-19 ソースファイル: giipv3/public/help/api-network-topology.ja.md