3分鐘閱讀

Graphify 資料寫入 API

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

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

資料流程分兩步: ① 寫入項目(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>/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