7分で読了

Graphify データ追加 API

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

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

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

📦 データ保存とフロー — tKB が「本当のデータストア」

⚠️ 最もよくある誤解: 「issueを登録したのにグラフに出ない」は、ほとんどの場合 tKBにまだ投入されていない ことが原因です。tBlogGraphNodes/tBlogGraphEdges(グラフテーブル)自体はデータを保持しておらず、再構築を呼ぶたびに tKB から作り直される派生結果です。グラフテーブルを直接書き込む方法はなく、常に tKB → 再構築の順を経る必要があります。

[issue / ナレッジソース]
   │ ① 投入: POST /api/giipKb (x-api-key: ak/sk)
   │   → tKB テーブルに1行保存 (csn, refType, title, content, tags, extRefId)
   │   → refType='ISSUE'(外部/自社issue) または 'k-layer-daily'(K-Layer日次同期、下記参照)
   │   → extRefId で冪等 upsert(同じ extRefId を再送すると新規行ではなく既存行を UPDATE)
   ▼
  tKB  (グラフの「本当のデータストア」— グラフテーブル自体は派生結果に過ぎない)
   │ ② 再構築: POST /api/giipGraphifyRebuild {csn} (x-api-key)
   │   → SP pApiGraphifyRebuildbyAk がその csn の tBlogGraphNodes/tBlogGraphEdges を
   │     まるごと DELETE してから tKB から再生成(投入だけして再構築しないとグラフは
   │     変わらない)
   │   → DOCノード(tKBの各行=文書1件) + TAGノード(2件以上の文書が共有するタグのみ、
   │     ヘアボール防止のため過度に一般的なタグは自動除外) + doc→tagエッジ
   │   → (新規)このcsnに設定された言語(tCorp.cLang)にノードラベルを自動翻訳して保存
   ▼
 tBlogGraphNodes / tBlogGraphEdges  (csnスコープ、画面が実際に読むテーブル)
   │ ③ 参照: GET /api/giipGraphifyTenant?csn= (厳格な分離、ak認可) または画面 /graphify?csn=
   ▼
 3Dナレッジグラフ可視化

①投入だけではグラフに何も現れません。 ②再構築まで呼んで初めて反映されます。
再構築は毎回全量再生成です。以前のグラフ状態を引き継ぐのではなく、その時点の tKB 内容全体から描き直します。そのため tKB から項目を削除(または refType 単位で一括削除)すると、次の再構築で自然にグラフから消えます。
分離: すべての段階が csn(プロジェクト境界)と x-api-key(ak/sk認可)でスコープされます。他の csn の tKB やグラフにはアクセスできません。

K-Layer 自動投入(既に稼働中、`refType='k-layer-daily'`)

giip セッションが蓄積する エンジニアリングノウハウ(K-Layer) は、すでに毎日自動で tKB に投入されています(新機能ではなく既存の運用機能です)。

スケジューラ: giipdb/mgmt/run_klayer_daily_wiki.ps1 が毎日 00:15 UTC に Windows タスクスケジューラのジョブ GIIP_Daily_KLayerWiki として実行されます。
動作: giip イシューがある全 csn について、前日1日分のイシュー+コメントを収集し、MiniMax で要約したうえで giipKb 経由で tKB に INSERT します。
フィールド値: refType='k-layer-daily'、tags='k-layer-wiki,daily'、title='K-Layer Wiki {csn} - {yyyy-MM-dd}'。
マスキング: 機微情報は giipdb/mgmt/lib/Mask-SensitiveInfo.ps1 により二重マスキングされてから保存されます。
グラフでの見え方: これらの tKB 行も他の項目と同様、次回の再構築時に DOC ノードとして取り込まれます。共有タグ k-layer-wiki、daily が TAGノードとなり、日付ごとに蓄積された K-Layer ドキュメントが自然に1つのクラスターとしてまとまって見えます。
フィルタ・削除時は refType='k-layer-daily' で範囲を絞れます(§1表の refType 参照)。

csn 言語ベース自動翻訳 (新規)

giipGraphifyRebuild 呼び出し時、その csn のプロジェクト言語設定(tCorp.cLang、例: ko-KR, en-US — プロジェクト管理画面で既に設定可能な既存値) に合わせてノードラベルを自動翻訳して保存します。

動作タイミング: tKB の元データ(title/content)は言語に関わらずそのまま保存され、再構築の実行時点で その csn の cLang 値を読み取ってノードラベルを翻訳します。
ユーザー視点の要約: プロジェクト管理画面で csn の言語設定(cLang)を変更すると、次回の giipGraphifyRebuild 呼び出しからグラフに表示されるテキストの言語が変わります。 元の tKB データを変更する必要はありません。
同じ tKB データでも、cLang が異なる csn ごとにグラフのノードが異なる言語で表示され得ます。
翻訳は再構築のたびに毎回やり直されます(キャッシュ・蓄積なし) — 元の title/content が常に最新のソースです。

クイックスタート (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)