giip

API 參考概述 (v1.2)

本指南介紹了用於控制和監控 GIIP 平台微服務及資料庫資源的通用 API 規範和認證方式。

📋 概述

GIIP API 遵循 RESTful 架構原則，使用 JSON 格式處理請求並返回響應。為了安全起見，所有 API 只能通過 HTTPS 協議訪問，並且必須使用有效的 Access Key 和 Secret Key 才能正常調用功能。

🔐 認證 (Authentication)

所有 API 請求標頭中必須包含以下認證資訊。

標頭鍵 (Header Key)描述
x-giip-ak從 GIIP 管理員處獲取的 Access Key
x-giip-sk從 GIIP 管理員處獲取的 Secret Key

[!IMPORTANT] Secret Key 不得洩露給外部，應在伺服器端安全管理，以避免直接在用戶端 JavaScript (JS) 程式碼中暴露。

📡 通用響應格式 (Response Format)

GIIP 的所有 API 提供一致的響應格式，以便於用戶端處理。

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": { ... }
}
  • RstVal: 成功狀態 (0: 成功，其他: 錯誤)
  • RstMsg: 成功消息 (發生錯誤時包含詳細原因說明)
  • Data: 請求成功時返回的數據主體

🚀 請求格式

所有 API 請求均遵循 Azure Function 調用規範，以 

application/x-www-form-urlencoded
方式進行 POST。

主要表單數據

字段說明
text要執行的命令字串
user_id調用者用戶 ID
token會話令牌
usertoken用於實際集成的會话令牌

🚀 API 分組指南

有關各領域的詳細 API 規範，請參考以下各別指南。

  1. 伺服器管理 API：基礎設施資產查詢與命令執行
  2. 資料庫 API：資料庫效能與查詢統計
  3. 問題管理 API：故障告警與狀態更新
  4. 費用分析 API：雲端使用量與費用預測
  5. 項目/用戶 API：權限與組織管理
  6. 監控數據查詢 API：實時 CPU/MEM/Disk 指標、效能歷史記錄及進程列表
  7. 網絡安全策略 API：防火牆規則查詢、IP 允許/阻止及策略批量部署
  8. 網絡拓撲 (Net3D) API：基礎設施連接數據收集與傳輸規範 (netinv, netstat, db_connections)
  9. 系統管理 API：遠端命令執行、助理 (Agent) 控制及伺服器標籤管理
  10. KVS (鍵值存儲) API：Factor 數據查詢 (KVSFactorLast, KVSFactorList)
  11. Vercel 管理 API：Vercel 配置管理及部署歷史查詢
  12. GitHub Actions 管理 API：GitHub 倉庫集成及工作流歷史查詢
  13. 郵件伺服器管理 API：SMTP 伺服器配置及測試發送 (僅限管理員)
  14. Sk3 (高性能日誌) API：用於助理傳輸錯誤檢測和數據完整性校驗的高保真日誌橋接器
  15. 公共響應值與結果代碼指南 (RstVal)：基於 tDefRst 表的標準結果代碼說明

🛠️ 通用錯誤代碼

  • 401 Unauthorized：認證資訊無效或已過期
  • 403 Forbidden：無權調用該 API（包括基於 IP 的訪問控制）
  • 429 Too Many Requests：請求頻率超過限制 (Rate Limit)
  • 500 Internal Server Error：伺服器內部錯誤或發生暫時故障

📖 開發者注意事項

  • 端點調用模組：
    src/lib/lsvrUtils.ts
  • 會話管理：參考 
    sessionStorage
    中的 
    user_id
    , 
    token
    , 
    csn
    , 
    cname
    等
  • 所有集成均預設使用 HTTPS。

🔧 疑難排解

症狀原因解決方法
返回 401 UnauthorizedAccess Key/Secret Key 已過期或無效重新核對 
x-giip-ak
/
x-giip-sk
請求頭的值，必要時請管理員重新發放密鑰
返回 403 Forbidden無權調用該 API，或被基於 IP 的訪問控制攔截確認帳號權限及來源 IP 是否被允許
RstVal
不為 0 但不清楚原因		未查閱標準結果代碼的含義檢查 
RstMsg
並在 API 結果代碼指南 中查詢對應代碼
請求未被處理或 
text
命令被忽略		請求非 
application/x-www-form-urlencoded
格式，或缺少 
text
/
user_id
/
token
欄位		按規範以正確格式發送包含必填欄位的表單數據

版本: 1.2 最後更新: 2026-04-11 Markdown 源碼: giipv3/public/help/api-reference.zh-TW.md

← Previous
API 結果代碼 (RstVal)
Next →
Sk3 高性能日誌 API