5分鐘閱讀

Graphify 資料寫入 API

🔌 前往 Graphify →](/zh-TW/graphify)

Graphify 將知識庫(tKB)項目視覺化為 3D 知識圖譜。本文說明如何 透過 API 新增資料,以及如何呼叫才能讓 資訊顯示得更好。

資料流程分兩步: ① 寫入項目(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 會先整體 DELETE 該 csn 的 tBlogGraphNodes/tBlogGraphEdges,
   │     再從 tKB 重新產生(只寫入而不重建,圖譜不會變化)
   │   → DOC 節點(tKB 每列對應一個文件) + 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 issue 的 csn,彙整前一天的 issue 與留言,以 MiniMax 產生摘要,再透過 giipKb INSERT 寫入 tKB。
欄位值: 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 文件自然聚合成一個聚類。
可依 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>/zh-TW/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>

從 tKB 重建指定 csn 的圖譜(DOC 節點 + 有辨識度的 TAG 節點 + doc→tag 邊)。

欄位	型別	必填	說明
`csn`	int	✅	要重建的專案編號
`maxTagDF`	int		通用標籤閾值(文件頻率上限,預設 50);比此更常見的標籤被排除
`maxNodes`	int		DOC 節點安全上限(預設 20000)

回應

{ "success": true, "nodes": 838, "edges": 11, "docNodes": 835, "tagNodes": 3, "message": "Graph rebuilt (tag-bipartite)" }

疑難排解

現象	原因	解決
圖譜看起來為空	未呼叫重建 / csn 錯誤	呼叫 `giipGraphifyRebuild`,檢查 `?csn=`
節點很多但幾乎沒有邊	標籤獨有(DF=1)或通用(過於頻繁)	用 2〜50 個共享的有意義標籤重新寫入後重建
同一項目重複建立	未使用 `extRefId`	加入 `extRefId` 實現冪等寫入
401/403	無金鑰 / 不同 csn	使用有效的 `x-api-key` 和自己的 `csn`

中繼資料

原始檔: giipv3/public/help/api-graphify.zh-TW.md
raw 原文路徑: /help/api-graphify.zh-TW.md
相關 API: giipfaw/giipKb, giipfaw/giipGraphifyRebuild
相關頁面: /[locale]/graphify