giip

伺服器 API 參考指南

用於查詢 GIIP 平臺管理的伺服器資產詳細資訊並發送控制指令的 API 詳細規範。

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

📋 概述

利用伺服器 API，您可以檢查庫存中註冊的伺服器物理/邏輯狀態，並能透過代理遠端執行指令或重啟服務。

🔍 核心端點

1. 查詢伺服器列表

獲取按專案或客戶維度註冊的所有伺服器資訊。

  • URL: 
    GET /server/list
  • 主要參數: 
    • prj_isn
      (Integer): 僅查詢特定專案所屬的伺服器
    • status
      (String): 按 
      Running
      , 
      Stop
      , 
      Unknown
      等狀態進行過濾
  • 響應數據: 主機名、IP 地址、作業系統類型、CPU/內存規格等

2. 查詢心跳與實時狀態

確認安裝在伺服器上的代理的存活信號及實時負載資訊。

  • URL: 
    GET /server/heartbeat
  • 必填參數: 
    server_isn
    (伺服器唯一編號)
  • 響應數據: 最後接收時間、當前 CPU 使用率、可用內存等

3. 遠端執行指令 (execCommand)

向特定伺服器發送 Shell 指令並非同步接收結果。

  • URL: 
    POST /server/command
  • 負載 (Payload): 
    • server_isn
      : 目標伺服器編號
    • command
      : 要執行的指令（如 
      systemctl restart nginx
      ）
  • 響應: 返回指令接收 ID (
    cmd_isn
    )（執行結果請在 
    /server/command/result
    中查詢）

🛠️ 代碼示例 (Shell 腳本)

# 查看特定伺服器當前的 CPU 使用率
curl -X GET "https://api.giip.io/v3/server/heartbeat?server_isn=123" \
     -H "x-giip-ak: YOUR_AK"

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

在進行新增伺服器註冊 (

LSvrPut
) 或變更詳細資訊 (
LSVRDetail
校驗) 等基礎設施資產管理的核心操作時，為了確保操作的一致性並獲取詳細的審計日誌 (Audit Log)，建議使用 
giipApiSk3
端點。

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

疑難排解

症狀原因解決
查詢伺服器列表/心跳時發生認證錯誤缺少或無效的 
x-giip-ak
請求標頭		確認請求標頭中包含有效的 AK。
GET /server/list
返回空列表
prj_isn
過濾條件有誤或 
status
過濾過於嚴格		核對 
prj_isn
值並放寬 
status
過濾（如去掉 
Running
）。
GET /server/heartbeat
未返回數據
server_isn
有誤或代理尚未上報		使用有效的 
server_isn
並確認目標伺服器上的代理正在執行。
遠端執行指令後未立即獲得結果
execCommand
為非同步，僅返回接收 ID（
cmd_isn
）		使用返回的 
cmd_isn
查詢 
/server/command/result
獲取結果。

版本: 1.1 最後更新: 2026-04-11 源碼: 

giipv3/public/help/api-server.zh-TW.md

相關文檔:

← Previous
Sk3 高性能日誌 API
Next →
資料庫管理 API