Graphify データ追加 API

🔌 Graphify ページへ →](/ja/graphify)

Graphify はナレッジベース(tKB)の項目を 3Dナレッジグラフとして可視化します。本書は APIでデータを追加し、情報が見やすく表示されるように呼び出す方法を説明します。

データフローは2段階です: ① 項目投入(giipKb) → ② グラフ再構築(giipGraphifyRebuild)。再構築を呼ばないと新項目はグラフに反映されません。

クイックスタート (3ステップ)

# 1) 項目投入 — giipKb POST (ホスト: giipfaw.azurewebsites.net)
curl -X POST "https://giipfaw.azurewebsites.net/api/giipKb" \
  -H "x-api-key: <YOUR_AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47,"title":"OAuthコールバック500","content":"## 原因\ntoken交換タイムアウト","tags":"auth,oauth,timeout","refType":"ISSUE","extRefId":"ISSUE-1001"}'

# 2) グラフ再構築 — giipGraphifyRebuild POST
curl -X POST "https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild" \
  -H "x-api-key: <YOUR_AK_OR_SK>" -H "Content-Type: application/json" \
  -d '{"csn":47}'

# 3) 確認 — ブラウザで https://<host>/ja/graphify?csn=47

認証キー(x-api-key)はログインユーザーの AK またはプロジェクトスコープの SK を使用します。キーは自身の csn 範囲のみ追加・再構築できます。

⭐ 情報を見やすく表示させる方法 (重要)

Graphify は タグ二部(bipartite)グラフです。つまり 文書は「共有タグ」を通じて接続されます(タグが第一級ノード)。したがって タグの付け方がグラフ品質を左右します。

良いタグ (接続が生まれる)

2〜50件が共有する意味のあるタグを使います。例: auth, billing, timeout, payment, login。
同じ話題の項目が共有タグノードを中心に クラスターを形成します。

避けるべきタグ

悪いパターン	理由	結果
項目ごとに固有のタグ(例: ファイル名 `report_2026_01.md`)	共有する項目がない(DF=1)	何も接続しない → 孤立ノード
ほぼ全項目に付く汎用タグ(例: `doc`, `sync`, `general`)	文書頻度(DF)が高すぎる	自動的にエッジから除外(ヘアボール防止)

目安: 一般的すぎず、固有すぎないタグが良い接続を作ります。既定では csn 内で DF(文書頻度)が2〜50のタグのみがタグノードになります。

その他の表示のコツ

title はグラフの ノードラベルになります。短く明確に。
content はノードクリック時に 詳細ポップアップ本文としてMarkdownレンダリングされます。
extRefId は外部システムの項目ID。再同期時に **重複せず更新(冪等)**されます。
再構築は必須: 項目追加のみで再構築しないとグラフは変わりません。バッチ投入後に giipGraphifyRebuild を一度呼びます。

詳細 · API リファレンス

1) 投入 — `giipKb`

POST https://giipfaw.azurewebsites.net/api/giipKb · ヘッダ x-api-key: <ak/sk>

フィールド	型	必須	説明
`csn`	int	✅	プロジェクト番号。キー権限範囲と一致(例: 47)
`title`	string(200)	✅	ノードラベル
`content`	string		ノード詳細本文(Markdown可)
`tags`	string(500)		カンマ区切りタグ。接続の核（「良いタグ」参照）
`refType`	string(50)	✅	項目種別。例: `ISSUE`, `GENERAL`, `GUIDE`
`extRefId`	string(100)		外部項目ID(冪等upsertキー)。あれば再同期時に更新

レスポンス

{ "success": true, "kbSn": 844, "message": "KB entry created successfully" }

同じ extRefId で再送信すると:

{ "success": true, "kbSn": 844, "message": "KB entry updated (idempotent)" }

PowerShell 例

$headers = @{ "x-api-key"="<ak/sk>"; "Content-Type"="application/json; charset=utf-8" }
$body = @{ csn=47; title="決済遅延"; content="## 症状`n承認が5秒遅延"; tags="payment,timeout"; refType="ISSUE"; extRefId="ISSUE-1002" } | ConvertTo-Json
Invoke-RestMethod -Uri "https://giipfaw.azurewebsites.net/api/giipKb" -Method POST -Headers $headers -Body ([Text.Encoding]::UTF8.GetBytes($body))

2) 再構築 — `giipGraphifyRebuild`

POST https://giipfaw.azurewebsites.net/api/giipGraphifyRebuild · ヘッダ x-api-key: <ak/sk>

指定 csn のグラフを tKB から再生成します(DOCノード + 弁別的タグノード + doc→tagエッジ)。

フィールド	型	必須	説明
`csn`	int	✅	再構築するプロジェクト番号
`maxTagDF`	int		汎用タグのカット(文書頻度上限、既定50)。これより多いタグは除外
`maxNodes`	int		DOCノード安全上限(既定20000)