14分で読了

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

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

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

⚠️ このドキュメントの適用範囲 — 最初にお読みください

このドキュメントはサーバー・データベースのネットワークトポロジー専用の手順です。ここに記載された2つの形式 (netstat, db_connections) が、Net3D画面が読み取る唯一の2形式です。

ネットワークではない任意のデータ(受注フロー、組織図、サービス依存関係など)をこの3Dレイアウトで表示したい場合は → 付録: ネットワークではないデータをこのレイアウトで表示する を先にお読みください。 kFactor だけを任意の値に変えてtKVSへ投入する方法は動作しません — 保存は RstVal 200 で成功しますが、画面にはエラーもなく何も表示されません。

開始前の準備物

項目	説明	取得方法
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) 言語別サンプルスクリプト

データ確認方法

スクリプト実行後、以下の手順でデータを確認してください。

サーバー登録確認: 基本情報管理 > サーバーインベントリメニューで該当ホスト名のサーバーが登録されているか確認します。
DBマッピング確認: client_net_address の値が tManagedDatabase.db_host と完全に一致しているか確認します。
トポロジービュー: /admin/network-topology ページに移動して、ノード間の接続線がアクティブになるか確認します。データは送信後約1〜2分以内にリアルタイムで反映されます。

データ整合性ルール

データを入力する前に、必ず以下の条件を確認してください。

IPマッピング: tLSvr.ips フィールドは必ず [{"CIDR":"10.0.0.5/24"}] 形式のJSON配列である必要があります。単純な文字列だとトポロジーで'External'ノードとして分離されます。
DBホスト一致: db_connections の client_net_address 値が tManagedDatabase.db_host とテキストレベルで100%一致する必要があります。大文字小文字、スペースまで同一である必要があります。
JSON Depth: kValue 配列を含むjsondata全体をシリアライズする際、Depth 10以上でエンコードします。深さが不足すると子オブジェクトが切り捨てられます。
state値: netstat kValueで state が ESTABLISHED の項目のみトポロジーの接続線として表示されます。
kFactor は変更できません: 照会SP(pApiNet3dDatabyAK)は netstat と db_connections の2つのリテラルのみを読み取るようハードコードされています。任意の kFactor(例: my_graph)でKVSPutすると、レスポンスは RstVal 200(保存成功)ですが、トポロジー画面にはエラーもなく何も現れません。 tKVS自体はどんな値でも受け付ける汎用ストレージなので、保存の成功を「画面に出る」という意味に誤解しないでください。
kKey は既に登録済みの資産IDである必要があります: netstat は kKey が現在のCSNに登録された tLSvr.LSsn である必要があり、db_connections は tManagedDatabase.mdb_id である必要があります。登録されていない任意のキー(注文番号、アカウントIDなど)を kKey に入れると、その行は照会対象から静かに除外されます。

トラブルシューティング

レスポンスRstValが200でない場合

RstVal	意味	対処
401	認証失敗	`token` 値(SK)が正しいか確認。HTTPヘッダーではなくボディにあるか確認
400	不正なリクエスト	`text` フィールドの値が正確か確認 (`KVSPut kType kKey kFactor` リテラル)
500	サーバーエラー	`jsondata` のJSON形式が有効か確認。ネストされた引用符のエスケープを確認

トポロジーに接続線が表示されない場合

netstat kValueの state 値が正確に ESTABLISHED (大文字)であるか確認
db_connections の client_net_address がGIIPに登録されたDBホストIPと完全に同一か確認
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です。

付録: ネットワークではないデータをこのレイアウトで表示する (汎用再利用)

結論から

任意の {nodes, links} をそのまま受け取る専用の「汎用グラフ」入力経路は、現在存在しません。 (giip #2526 にて設計を推進中)

❌ できないこと: kFactor を my_graph のような任意の値に変えて {nodes, links} をtKVSへ投入する。 → KVSPutは RstVal 200 を返します(tKVSはどんなkFactorでも保存する汎用ストレージです)。しかしNet3Dの照会SPがその行を読み取りません。 画面はエラーもなく空のままです。
✅ 今できること: 自分のデータのエンティティを「サーバー」に、関係を「接続」にマッピングすれば、任意の有向グラフを今日すぐに描けます。以下がその手順です。

マッピングルール — 自分のドメインをNet3Dモデルに合わせる

自分のデータ	Net3Dでの表現	投入方法
エンティティ(ノード)1つ	サーバーノード(球)1つ	`AgentAutoRegister` で登録 → LSSNを取得
エンティティの表示名	ノードラベル	`hostname` の値がそのままノード名になります
エンティティの一意識別子	合成IP	`ipv4_local` に重複しないIPを割り当てる(例: `10.99.0.1`)
関係(エッジ)1つ	接続線(Link)	`netstat` KVSPutの `remote_ip` に相手エンティティの合成IP
関係のラベル	リンクのプロセス名	`process_name` の値

💡 相手エンティティを必ず登録しなければならないわけではありません。 remote_ip が登録済みのどのサーバーの IPとも一致しない場合、Net3DがそのIP名のExternalノードを自動生成します。ただし名前がIP文字列そのままになるため、名前を指定したいエンティティは AgentAutoRegister で登録してください。

入力スキーマ

① エンティティ登録 — AgentAutoRegister

フィールド	型	必須	制約	例
`hostname`	string	✅	CSN内で一意。この値がノードラベルになります	`"受注受付"`
`ipv4_local`	string	✅	有効なIPv4。エンティティごとに一意でないとエッジが正確につながりません	`"10.99.0.1"`
`os`	string	—	自由文字列。ノード詳細に表示	`"OrderFlow"`
`cpu_cores`	integer	—	表示用	`1`

② 関係の送信 — KVSPut kType kKey kFactor

フィールド	型	必須	制約	例
`kType`	string	✅	`"lssn"` 固定	`"lssn"`
`kKey`	string	✅	出発エンティティのLSSN。登録済みのLSsnでないと無視されます	`"123456"`
`kFactor`	string	✅	`"netstat"` 固定。他の値は画面に出ません	`"netstat"`
`kValue`	array	✅	エッジの配列	下記参照
`kValue[].remote_ip`	string	✅	到着エンティティの合成IP。 `127.*`/`0.0.0.0`/`::1` は除外されます	`"10.99.0.2"`
`kValue[].state`	string	✅	`"ESTABLISHED"` でないとエッジが生成されません(`"ESTAB"` も許容)	`"ESTABLISHED"`
`kValue[].process_name`	string	—	エッジのラベルとして表示	`"決済要求"`
`kValue[].remote_port`	integer	—	ノードバブルに表示	`443`

コピー&ペーストでそのまま動く完結サンプル — 受注処理フロー3ステップ

SK、API_URL の2行だけを変えればそのまま実行できます。

#!/bin/bash
set -e
SK="YOUR_SK"
API_URL="https://YOUR_API_URL"

# --- ① エンティティ3件を「サーバー」として登録しLSSNを取得 ---
register() {
  curl -s -X POST "$API_URL/api/giipApi?cmd=AgentAutoRegister" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "token=$SK" \
    --data-urlencode "text=AgentAutoRegister" \
    --data-urlencode "jsondata={\"hostname\":\"$1\",\"os\":\"OrderFlow\",\"cpu_cores\":1,\"ipv4_local\":\"$2\"}"
}

LSSN_A=$(register "ORDERFLOW-受注受付" "10.99.0.1" | grep -oE '"lssn":[0-9]+' | cut -d: -f2)
LSSN_B=$(register "ORDERFLOW-決済承認" "10.99.0.2" | grep -oE '"lssn":[0-9]+' | cut -d: -f2)
LSSN_C=$(register "ORDERFLOW-配送指示" "10.99.0.3" | grep -oE '"lssn":[0-9]+' | cut -d: -f2)
echo "LSSN: A=$LSSN_A B=$LSSN_B C=$LSSN_C"

# --- ② 関係(エッジ)の送信: 受注受付 → 決済承認 → 配送指示 ---
link() {
  curl -s -X POST "$API_URL/api/giipApi" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "token=$SK" \
    --data-urlencode "text=KVSPut kType kKey kFactor" \
    --data-urlencode "jsondata={\"kType\":\"lssn\",\"kKey\":\"$1\",\"kFactor\":\"netstat\",\"kValue\":[{\"remote_ip\":\"$2\",\"remote_port\":443,\"process_name\":\"$3\",\"state\":\"ESTABLISHED\"}]}"
  echo
}

link "$LSSN_A" "10.99.0.2" "決済要求"
link "$LSSN_B" "10.99.0.3" "配送要求"

実行後に /ja/network-topology を開くと、受注受付 → 決済承認 → 配送指示 の3ノードがエッジでつながって表示されます(反映まで1〜2分)。

自己検証の方法

保存されたか — 各KVSPutのレスポンスが {"RstVal":200} であることを確認します。
照会できるか — 画面を開く前にAPIで直接確認します。
```
curl -s -X POST "$API_URL/api/giipApi" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=$SK" \
  --data-urlencode "text=Net3dData csn" \
  --data-urlencode "jsondata={\"csn\":YOUR_CSN,\"targetTime\":null}"
```
レスポンスの servers の中に今登録した hostname が、netstat_data の中に合成IPが見えるはずです。 ここで見えない場合は画面にも出ません — 下記の失敗事例を確認してください。
画面で — /ja/network-topology 右下のノード数 / リンク数が期待どおり増えたかを見ます。

失敗事例とそのときの症状

やったこと	症状	原因	解決
`kFactor` を `my_graph` など任意の値に指定	`RstVal 200` なのに画面に何も変化なし	照会SPが `netstat`/`db_connections` のみ読み取る	`kFactor` を `netstat` に
`kKey` に任意のID(注文番号など)を使用	保存成功、画面に変化なし	`kKey` は登録済みの `LSsn` である必要がある	先に `AgentAutoRegister` でLSSNを取得
`{"nodes":[...],"links":[...]}` をそのまま `kValue` に	画面に変化なし	Net3Dは `nodes`/`links` を入力形式として受け付けない	上記のマッピングルールに従う
`state` を `TIME_WAIT` などに	ノードは出るがエッジがない	`ESTABLISHED`/`ESTAB` のみエッジになる	`"ESTABLISHED"` を使用
エンティティごとに同じ `ipv4_local` を使用	ノードが1つに統合される	IPがノード識別に使われる	エンティティごとに一意のIPを割り当てる
`remote_ip` を `127.0.0.1` に	エッジがない	ループバック/`0.0.0.0`/`::1` は明示的に除外される	実際の合成IPを使用
エッジが非常に多い大きなグラフ	一部しか表示されないか全体が空画面	レスポンスが `FOR JSON` の2033文字単位で分割される	レスポンスを自分でパースするなら `JSON_...` カラムの断片をすべて連結してからパースする

この回避方法の限界 (理解した上で使ってください)

すべてのエンティティが**サーバーノード(球)**として描画されます。データ種別ごとに形を変えることはできません。
ノードをクリックするとサーバー詳細モーダルが開きます(自分のドメイン情報の画面ではありません)。
登録したエンティティはサーバーインベントリ一覧にも現れます。 実際のサーバーと混ざるため、hostname にプレフィックス(例: ORDERFLOW-)を付けて区別することを推奨します。
エッジの色・粒子速度はCPU負荷基準のため、常に既定の状態に見えます。

この限界なしに任意の {nodes, links} を直接投入できる汎用エントリポイントは、giip #2526 にて設計を進行中です。

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

開始前の準備物

LSSNとは?

認証方式

Step 1: サーバー登録 (AgentAutoRegister) — LSSN取得

Step 2: サーバー間接続送信 (netstat KVSPut)

Step 3: DB接続情報送信 (db_connections KVSPut)

Step 4: DBリスト照会 (ManagedDatabaseList)

言語別完全サンプルスクリプト

データ確認方法

データ整合性ルール

トラブルシューティング

レスポンスRstValが200でない場合

トポロジーに接続線が表示されない場合

LSSNを紛失した場合

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

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

付録: ネットワークではないデータをこのレイアウトで表示する (汎用再利用)

結論から

マッピングルール — 自分のドメインをNet3Dモデルに合わせる

入力スキーマ

コピー&ペーストでそのまま動く完結サンプル — 受注処理フロー3ステップ

自己検証の方法

失敗事例とそのときの症状

この回避方法の限界 (理解した上で使ってください)

関連ドキュメント

関連ガイド