5分鐘閱讀

伺服器 API 參考指南 (v1.5)

用於查詢 GIIP 平臺管理的伺服器資產詳細資訊的 API 詳細規範。

🔌 前往伺服器列表功能頁 →

📋 概述

利用伺服器 API，您可以檢查庫存中註冊的伺服器物理/邏輯狀態。

🔐 認證方式（依實際實作，2026-08-20 giip #1277 實測）

目前唯一經實測驗證可用的是下方的 LsvrDetail（經由 giipApiSk2 通用 SP 包裝器呼叫）。此包裝器不透過 HTTP 標頭認證，僅透過 POST 內文欄位認證。

端點: POST https://giipfaw.azurewebsites.net/api/giipApiSk2
Content-Type: application/x-www-form-urlencoded
欄位:
- text: [命令名稱] [參數名稱...]
- token: [Your_SK] — SK 必須透過此欄位傳遞，不要放入 text 或 jsondata
- jsondata: 參數值（不同命令格式不同 — 見下文「2. LsvrDetail」）
⚠️ 直接查閱 giipfaw/giipApiSk2/run.ps1（2026-08-20）確認，此端點完全不解析任何 HTTP 標頭。傳送 x-giip-ak 等標頭會被靜默忽略；該 Azure Function 本身以 authLevel: anonymous 部署，因此也不需要 Function Key（?code=）。認證完全依賴上述 token 欄位的值。

⚠️ 關於舊記載（`api.giip.io` / `x-giip-ak`）

本文件此前記載的 https://api.giip.io/v3 主機與 x-giip-ak 標頭，在對整個程式碼庫（giipfaw Azure Functions、giipv3 原始碼）進行搜尋後，確認在實際實作中完全不存在（0 筆相符）。同一段範例文字還出現在其他多份 API 指南文件中，高度疑似是範本佔位符而非真實端點。請勿在正式環境中使用。 請改用上方「認證方式」中已驗證的端點。

🔍 端點

單台伺服器詳情查詢（LsvrDetail）— 已實測驗證（giip #1277）

命令: text=LsvrDetail
說明: 回傳按 LSSN（伺服器內部編號）查詢的單筆伺服器詳情。內部呼叫 pApiLSVRDetailbySk(@sk, @lssn bigint, @jsondata=NULL) → pLSvrDescOptbyAT。

請求範例:

POST https://giipfaw.azurewebsites.net/api/giipApiSk2
Content-Type: application/x-www-form-urlencoded

text=LsvrDetail&token={SK}&jsondata=71289

（71289 為欲查詢伺服器的 LSSN）

回應範例（lssn=71289）:

{ "data": [ { "LSsn": 71289, "LSHostname": "shinsema0104", "CSn": 70418, "CGCode": "smtodr-group", "lsRegdt": "2026-...", "LSLastHeartbeat": null } ] }

🚨 jsondata 必須是原始數字字串，用物件包裹會失敗:
- ✅ 成功: jsondata=71289
- ❌ 失敗: jsondata={"lssn":71289}、{"id":71289}、{"isn":71289} 等 — 無論用哪個鍵包裹都會出現 Error converting data type nvarchar to bigint 錯誤。
- 原因: 由於 text 僅為單字 LsvrDetail（後面沒有參數名稱），run.ps1 會將此呼叫當作「無參數名稱的單一命令」路徑處理。此路徑不會從 jsondata 中擷取個別鍵值，而是把 jsondata 字串整體轉義後，作為字串常值直接附加為 SP 的第二個位置參數（@lssn bigint）（即 giipApiSk2 的自動 jsondata 附加邏輯，run.ps1 內註解標記為 ISN 161）。若該常值是純數字（如 71289），SQL Server 的 nvarchar→bigint 隱式轉換會成功；若含有大括號（如 {"lssn":71289}），則轉換失敗。

🛠️ 使用範例（Shell 指令碼，已實測可用）

# 取得 LSSN 71289 的伺服器詳情
curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk2" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "text=LsvrDetail" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "jsondata=71289"

🛡️ 巧用 Sk3 (高性能日誌)

在進行新增伺服器註冊或變更詳細資訊等基礎設施資產管理的核心操作時，為了確保操作的一致性並獲取詳細的審計日誌 (Audit Log)，建議使用 giipApiSk3 端點。

端點: https://giipfaw.azurewebsites.net/api/giipApiSk3
優勢: 若伺服器註冊失敗，系統會立即記錄調用者的詳細環境資訊 (IP, UA) 和堆疊追蹤 (StackTrace)，助力快速分析助理對接問題或配置錯誤。
使用技巧: 靈活運用 text 命令和 jsondata 的參數替換功能，確保伺服器用途或複雜的配置值能完整、穩定地反映到平臺中。

疑難排解

症狀	原因	解決
`LsvrDetail` 查詢出現 `Error converting data type nvarchar to bigint` 錯誤	`jsondata` 被包裹為物件，如 `{"lssn":71289}` — 由於 `text=LsvrDetail` 沒有參數名稱，`jsondata` 整體會原樣賦值給 `@lssn bigint` 參數	僅傳遞 LSSN 的原始數字（如 `jsondata=71289`），不要用物件包裹
`LsvrDetail` 查詢時認證被拒絕	POST 內文中 `token` 欄位缺失/錯誤，或使用了已失效（重新簽發/輪替）的 SK。`x-giip-ak` 等標頭在此端點完全不起作用，無論如何設定都無效。	確認 POST 內文的 `token` 欄位包含目前有效的 SK。
`LsvrDetail` 查詢結果為空	使用了不存在的 LSSN	使用有效的 LSSN 重新查詢

🚫 不可用命令（giip #1281）

以下命令在 giipApiSk2 調度器中沒有對應 SP，無法使用。請使用 UI 替代。

命令	原因	替代方案
`LSVRList <CSN>`	giipdb 中不存在 `pApiLSVRListbySk` SP	請使用伺服器列表頁面
`LSvrPut '<lsUsage>', <CSN>`	不存在 SK 版本的 `pApiLSvrPutbySk` SP（僅存在 AK 版本的 `pApiLSvrPutbyAK`，無法透過 giipApiSk2 呼叫）	請使用伺服器列表頁面

版本: 1.5 最後更新: 2026-08-20 源碼: giipv3/public/help/api-server.zh-TW.md

v1.5 變更歷史（2026-08-20, giip #1281）：從 API 詳情中刪除了不可用的 LSVRList 和 LSvrPut，添加了「不可用命令」表並註明 UI 替代方案。 v1.4 變更歷史（2026-08-20, giip #1277）：根據外部使用者（smartorder-works, csn 70418）的實測回報，發現並修正了文件與實作不一致的問題。 ① 新增 LsvrDetail（單台伺服器詳情查詢）端點 — 此前本文件完全沒有記載（回報的核心問題）。 ② 修正認證方式：此前記載的 https://api.giip.io/v3 主機 + x-giip-ak 標頭，經全程式碼庫搜尋確認在實作中完全不存在（0 筆相符）。已替換為真實的主機/認證格式（POST /api/giipApiSk2、Content-Type: application/x-www-form-urlencoded、token/text/jsondata 欄位，不使用標頭認證）。 ③ 依實測說明了 LsvrDetail 特有的規則——jsondata 必須是原始數字而非物件，以及其根本原因（run.ps1 的單參數處理路徑 + ISN 161 自動 jsondata 附加邏輯）。 ④ /server/list、/server/heartbeat、/server/command 因本次調查未能確認對應實作，標記為「未驗證 / 舊文件遺留」（即時測試超出本 Issue 範圍）— 後續追蹤見 giip #1281。

相關文件:

API 結果代碼指南 (RstVal)