giip

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

ネットワークトポロジー(Net3D)の視覚化のために、エージェントまたはサードパーティシステムからインフラ接続データを収集し、GIIPプラットフォームに送信するためのAPI仕様を案内します。

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

📋 概要

Net3Dシステムは、エージェントが収集したデータを 

tKVS
テーブルにロードし、サーバー間、サーバーとデータベース間の接続関係を3Dで視覚化します。正確な視覚化のためには、フィールド名と仕様の遵守が不可欠です.

🔐 認証とヘッダー

すべてのリクエストは application/x-www-form-urlencoded 形式で送信し、ボディに認証トークンを含める必要があります。

  • Content-Type: 
    application/x-www-form-urlencoded; charset=utf-8
  • Body Field: 
    token=[Your Secret Key]

[!IMPORTANT] 認証はHTTPヘッダー (

Authorization
) ではなく、リクエストボディの 
token
フィールドで行います。
token
には 
giipAgent.cfg
の 
sk
値を使用します。

🚀 主要データの収集と送信 (Factor別の仕様)

1. インフラインベントリの収集 (
netinv
)

サーバーの基本仕様、ネットワークインターフェース、ルーティング情報を送信します。

  • Endpoint: 
    POST /api/giipApi?cmd=AgentAutoRegister
  • Content-Type: 
    application/x-www-form-urlencoded
  • Body Fields: 
    • token
      : 
      sk
      値 (または 
      at
      値)
    • text
      : 
      "AgentAutoRegister"
    • jsondata
      : 以下のJSON構造を文字列化したもの

jsondata 構造例:

{
  "hostname": "WEB-SRV-01",
  "os": "Windows Server 2022",
  "cpu_cores": 8,
  "ipv4_local": "10.0.0.5"
}

2. サーバー間接続リスト (
netstat
)

現在のサーバーから外部サーバーへ接続されているTCPセッション情報を送信します。

  • Endpoint: 
    POST /api/giipApi?cmd=KVSPut
  • Content-Type: 
    application/x-www-form-urlencoded
  • Body Fields: 
    • token
      : 
      sk
      値
    • text
      : 
      "KVSPut kType kKey kFactor"
      (リテラル固定値)
    • jsondata
      : 以下のオブジェクト構造を文字列化したもの

jsondata 構造例:

{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "netstat",
  "kValue": [
    {
      "remote_ip": "10.0.0.10",
      "remote_port": 8080,
      "process_name": "nginx.exe",
      "state": "ESTABLISHED"
    }
  ]
}

注意: 

state
が 
ESTABLISHED
の項目のみ、トポロジー上に線（リンク）として表示されます。

3. データベース接続情報 (
db_connections
)

アプリケーションサーバーからDBサーバーへ送信されるクエリおよび負荷情報を管理します。

  • kFactor: 
    db_connections
  • Payload 仕様: | フィールド名 | 説明 | 備考 | |:---|:---|:---| | 
    client_net_address
    | ソースサーバーIP | 
    tLSvr.ips
    と一致する必要があります | | 
    program_name
    | 実行プログラム名 | Outgoingノードのラベルとして使用 | | 
    cpu_load
    | クエリ負荷 | リンクの太さとパーティクル速度を決定 | | 
    last_sql
    | 実行中のSQL | 詳細表示モーダルに表示 | | 
    query_hash
    | SQL文のハッシュ | 同一クエリのグループ化に使用 |

4. データベースリストの取得 (
ManagedDatabaseList
)

プロジェクト(csn)に紐づく管理対象データベースの一覧を取得します。

  • text: 
    "ManagedDatabaseList [db_type]"
    (例: 
    ManagedDatabaseList mssql
    )
  • csn 指定について: 
    token
    (sk) にプロジェクト情報が含まれているため、APIコール時に 
    csn
    を明示的に渡す必要はありません。サーバー側で自動的に解決されます。

🔍 データ整合性の注意事項 (AIガイド)

AIエージェントがデータを生成または検証する際は、必ず以下の条件を確認してください。

  1. IPマッピング: 
    tLSvr.ips
    フィールドは必ず 
    [{"CIDR":"10.0.0.5/24"}]
    のようなJSON配列構造である必要があります。単純な文字列の場合、トポロジー上で 'External' ノードとして分離されます。
  2. DBホストの一致: 
    tManagedDatabase.db_host
    の値は、エージェントが送信する 
    client_net_address
    とテキストレベルで100%一致する必要があります。
  3. JSON Depth: データを送信する際、下位オブジェクトが切れないように十分な深さ（Depth 10以上）でエンコードしてください。

💻 言語別送信サンプルスクリプト

実際のインフラ環境でデータを収集して送信するためのサンプルコードです。

giipAgentWin
の構成に合わせて、**サーバー登録(AgentAutoRegister)**はJSON形式、**データ送信(KVSPut)**はForm-urlencoded形式を使用します。

1. PowerShell (Windows)

Windowsエージェント(

giipAgentWin
)の動作を模倣したスクリプトです。

# 1. サーバー登録 (AgentAutoRegister)
$sk = "YOUR_SECRET_KEY"
$apiUrl = "https://your-api.azurewebsites.net/api/giipApi?cmd=AgentAutoRegister"

$discoveryData = @{
    hostname   = $env:COMPUTERNAME
    os         = (Get-CimInstance Win32_OperatingSystem).Caption
    cpu_cores  = (Get-CimInstance Win32_Processor).NumberOfLogicalProcessors
    ipv4_local = (Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.IPAddress -ne '127.0.0.1' } | Select-Object -First 1).IPAddress
} | ConvertTo-Json -Compress

$regBody = @{ 
    token    = $sk
    text     = "AgentAutoRegister"
    jsondata = $discoveryData 
}
$resp = Invoke-RestMethod -Uri $apiUrl -Method Post -ContentType "application/x-www-form-urlencoded" -Body $regBody
$lssn = $resp.lssn  # 登録後に発行されたLSSNを保存

# 2. 接続情報の送信 (KVSPut netstat)
$connUrl = "https://your-api.azurewebsites.net/api/giipApi"
$connections = Get-NetTCPConnection -State Established | Select-Object -First 100 | ForEach-Object {
    @{
        remote_ip    = $_.RemoteAddress
        remote_port  = $_.RemotePort
        state        = "ESTABLISHED"
        process_name = (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName
    }
}
$payload = @{ 
    kType   = "lssn"
    kKey    = $lssn
    kFactor = "netstat"
    kValue  = $connections 
} | ConvertTo-Json -Compress -Depth 10

$putBody = @{
    token    = $sk
    text     = "KVSPut kType kKey kFactor"
    jsondata = $payload
}
Invoke-RestMethod -Uri $connUrl -Method Post -ContentType "application/x-www-form-urlencoded" -Body $putBody

2. Bash Shell (Linux)

Linux環境で 

curl
と 
jq
を使用して送信する方法です。

#!/bin/bash
AT="YOUR_SECRET_KEY"
API_URL="https://your-api.azurewebsites.net/api/giipApi"

# 1. サーバー登録
JSON_DATA=$(cat <<EOF
{
  "hostname": "$(hostname)",
  "os": "$(cat /etc/os-release | grep PRETTY_NAME | cut -d'"' -f2)",
  "cpu_cores": $(nproc),
  "ipv4_local": "$(hostname -I | awk '{print $1}')"
}
EOF
)
RESP=$(curl -s -X POST "$API_URL?cmd=AgentAutoRegister" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=$SK" \
     --data-urlencode "text=AgentAutoRegister" \
     --data-urlencode "jsondata=$JSON_DATA")
LSSN=$(echo $RESP | jq -r '.lssn')

# 2. 接続情報の送信 (KVSPut netstat)
CONNS=$(ss -tunp | grep ESTAB | head -n 50 | awk '{print $5}' | awk -F'[: ]' '{print "{\"remote_ip\":\""$1"\",\"remote_port\":\""$2"\",\"state\":\"ESTABLISHED\"}"}' | paste -sd, -)
PAYLOAD=$(cat <<EOF
{
  "kType": "lssn",
  "kKey": "$LSSN",
  "kFactor": "netstat",
  "kValue": [$CONNS]
}
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" \
     --data-urlencode "jsondata=$PAYLOAD"

3. Python (Cross-platform)

requests
ライブラリを使用した汎用スクリプトです。

import requests
import json
import platform
import socket

AT = "YOUR_SECRET_KEY"
BASE_URL = "https://your-api.azurewebsites.net/api/giipApi"

# 1. サーバー登録
import urllib.parse, urllib.request

registration_data = {
    "hostname": socket.gethostname(),
    "os": platform.platform(),
    "cpu_cores": 8,
    "ipv4_local": socket.gethostbyname(socket.gethostname())
}

reg_payload = urllib.parse.urlencode({
    "token":    SK,
    "text":     "AgentAutoRegister",
    "jsondata": json.dumps(registration_data),
}).encode("utf-8")

req = urllib.request.Request(
    f"{BASE_URL}?cmd=AgentAutoRegister",
    data=reg_payload,
    headers={"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},
)
with urllib.request.urlopen(req) as f:
    resp = json.loads(f.read().decode("utf-8"))
    lssn = resp.get('lssn')

# 2. 接続情報の送信 (KVSPut netstat)
payload_data = {
    "kType": "lssn",
    "kKey": lssn,
    "kFactor": "netstat",
    "kValue": [
        {"remote_ip": "10.0.0.10", "remote_port": 80, "state": "ESTABLISHED", "process_name": "python"}
    ]
}

put_payload = urllib.parse.urlencode({
    "token":    SK,
    "text":     "KVSPut kType kKey kFactor",
    "jsondata": json.dumps(payload_data),
}).encode("utf-8")

req_put = urllib.request.Request(
    BASE_URL,
    data=put_payload,
    headers={"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},
)
urllib.request.urlopen(req_put)

✅ データ送信の確認

スクリプト実行後、データが正常に収集されたか以下の手順で確認してください。

  1. サーバーリストの確認: 
    基本情報の管理 > サーバーインベントリ
    メニューで、該当のホスト名のサーバーが登録され、「最終ステータスチェック」時間が現在に更新されているか確認します。
  2. データベースマッピング: DB接続情報を送信する場合、
    client_net_address
    が該当サーバーのIPと正確に一致しているか確認してください。
  3. トポロジービューアー: 
    /admin/network-topology
    ページに移動し、ノード間のリンク（線）が有効になっているか確認します。（データは送信後、約1〜2分以内にリアルタイムで反映されます。）

🛡️ Sk3（高性能ロギング）の活用

サーバー間接続（ 

netstat
）やDB接続（ 
db_connections
）のような大容量トポロジーデータを転送する際、データ損失の防止と詳細な転送エラー分析のために、 
giipApiSk3
エンドポイントを使用することをお勧めします。

  • エンドポイント: 
    https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 利点: 数千件の接続データを 
    jsondata
    で送信する際に発生しうるデータ切断現象を防止し、エラー発生時にエージェントの詳細な環境情報と StackTrace を自動記録することで、トポロジー視覚化エラーを迅速に解決できます。
  • 活用チップ: 
    KVSPut
    コマンド使用時に 
    jsondata
    内に 
    kType
    、
    kKey
    、
    kFactor
    、
    kValue
    をオブジェクト形式で含めて Sk3 を呼び出すと、複雑なエンコーディングプロセスなしでトポロジーデータを安定してサーバーにロードできます。

版本: 1.3 最終更新日: 2026-04-11 ソースファイル: 

giipv3/public/help/api-network-topology.ja.md

関連ドキュメント:

← Previous
ネットワークセキュリティポリシーAPI
Next →
システム管理API