系統管理 API 參考

引導您如何透過系統級自動化 API 向伺服器發送指令或控制代理狀態。

📋 概述

此 API 模組提供了一系列端點，用於透過 GIIP 代理直接向各伺服器下達指令，或管理伺服器的元數據（如標籤等）。

🔐 認證與請求頭

所有請求必須包含通用的認證請求頭。

Header:
```
x-giip-ak: [Your Access Key]
```
Header:
```
x-giip-sk: [Your Secret Key]
```

🚀 核心 API 端點

1. 遠端執行命令 (Run Remote Command)

URL:
```
POST /api/system/command/run
```
描述: 在指定的伺服器上執行特定的 Shell 腳本或指令。
請求體 (Request Body):

{
  "serverIsn": 456,
  "command": "ls -al /var/log",
  "timeout": 30
}

2. 代理控制 (Agent Control)

URL:
```
POST /api/system/agent/control
```
描述: 遠端重啟安裝在伺服器上的 GIIP 代理或同步配置。
請求體 (Request Body):

{
  "serverIsn": 456,
  "action": "restart"
}

3. 管理伺服器標籤 (Manage Server Tags)

URL:
```
POST /api/system/server/tags
```
描述: 更新用於分類伺服器的標籤列表。
請求體 (Request Body):

{
  "serverIsn": 456,
  "tags": ["Production", "Web", "Region-KR"]
}

🔍 響應數據示例 (Command Run)

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "jobId": "JOB-10293",
    "output": "total 1024\ndrwxr-xr-x 2 root root ...",
    "exitCode": 0
  }
}

💡 使用場景

自動補丁管理: 針對發現漏洞的軟體包，向所有伺服器下達批量更新指令。
動態資源分配: 透過標籤管理 API 自動指定新創建 VM 的用途並應用相應策略。

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

在進行遠端命令執行 (

Run Remote Command

) 或代理控制等敏感的系統管理操作時，為了確保操作的完整性並保留詳細的執行歷史，建議使用

giipApiSk3

端點。

端點:

https://giipfaw.azurewebsites.net/api/giipApiSk3

優勢: 若命令執行失敗，系統會立即記錄調用者的詳細環境資訊 (IP, UA) 和堆疊追蹤 (StackTrace)，助力快速、清晰地識別非法請求或網絡故障狀況。
使用技巧: 靈活運用
```
jsondata
```
替換功能，確保在管理複雜的 Shell 命令字串或包含特殊字符的標籤資訊時數據不丟失且安全。

🔧 疑難排解

症狀	原因	解決
請求因認證錯誤被拒絕	缺少 `x-giip-ak` / `x-giip-sk` 請求頭或金鑰錯誤	在兩個請求頭中均包含有效的 Access Key 與 Secret Key 後重試
遠端命令未執行	`serverIsn` 錯誤，或目標伺服器的代理離線	確認伺服器標識符，並透過代理控制 API( `action: restart` )重啟代理
回應中的 `RstVal` 不為 0	命令執行失敗或超過 `timeout`	檢查 `RstMsg` 與 `Data.exitCode` ，必要時調高 `timeout` 值
發送含特殊字符的標籤時數據丟失	未使用 `jsondata` 替換功能	透過 `giipApiSk3` 端點的 `jsondata` 欄位發送以防止數據丟失

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

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

相關文檔:

API 結果代碼指南 (RstVal)