費用分析 API 參考指南

用於查詢 GIIP 平臺彙總的雲及基礎設施費用數據以及 AI 優化建議的 API 詳細規範。

📋 概述

費用分析 API 整合並提供多個雲（Azure、AWS 等）及本地資源的費用數據。可用於與財務系統整合或自動生成報告。

⚠️ 實作狀態（請先閱讀） 下面的通用 /cost/* 端點（/cost/summary、/cost/breakdown、/cost/recommendations，位於 https://api.giip.io/v3，使用 x-giip-ak 標頭）為計畫中/未實作 — 請暫勿呼叫。 Azure 費用請使用已部署的實際 API azureCost / azureCostServers（https://giipfaw.azurewebsites.net/api，認證標頭 x-api-key）。可複製執行的快速開始見 Azure 費用指南 的「🤖 AI/API 快速開始」一節。

✅ 已實作：Azure 費用 API (x-api-key)

API	Method	URL
伺服器清單	GET	https://giipfaw.azurewebsites.net/api/azureCostServers?csn={csn}
費用明細	GET	https://giipfaw.azurewebsites.net/api/azureCost?csn={csn}&lssn={lssn}

僅透過 x-api-key 標頭進行驗證（切勿把密鑰放入 URL·請求主體）。請求/回應契約、錯誤表以及 cURL/PowerShell/Python 範例見 Azure 費用指南。

🔍 核心端點 (🚧 計畫中/未實作)

下面三個端點是計畫中的通用費用 API，尚未實作。僅作設計參考保留；實際查詢請使用上面的 Azure 費用 API。

1. 查詢日/月費用摘要 — 🚧 計畫中/未實作

獲取特定時期內產生的總費用。

• URL: GET /cost/summary
• 主要參數:
  • date_from, date_to: 設置查詢期間
  • prj_isn (Integer): 僅查詢特定專案的費用
• 響應數據: 總金額、貨幣 (Currency)、較前一日的變動率等

2. 按資產查詢費用佔比 — 🚧 計畫中/未實作

分析哪些伺服器或資料庫產生的費用最高。

• URL: GET /cost/breakdown
• 響應數據: 按資產類型（虛擬機、資料庫、網絡等）排列的費用列表

3. 查詢 AI 費用優化建議 — 🚧 計畫中/未實作

獲取透過 AI 分析的資源調整 (Rightsizing) 帶來的預期費用節省額度。

• URL: GET /cost/recommendations
• 響應數據: 目標資產、當前規格、推薦規格、預計節省金額

🛠️ 代碼示例 (cURL) — Azure 費用 API（已實作）

# 僅使用環境變數，切勿把密鑰放入 URL/請求主體
export GIIP_CSN=47
export GIIP_API_KEY=***your_key***

# 伺服器清單 + 預設伺服器
curl -s "https://giipfaw.azurewebsites.net/api/azureCostServers?csn=${GIIP_CSN}" \
     -H "x-api-key: ${GIIP_API_KEY}"

# 單伺服器費用明細
curl -s "https://giipfaw.azurewebsites.net/api/azureCost?csn=${GIIP_CSN}&lssn=71197" \
     -H "x-api-key: ${GIIP_API_KEY}"

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

若需要驗證費用數據採集的完整性以及獲取詳細的審計日誌，建議使用 giipApiSk3 端點。

• 端點: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 獨特優勢: 自動記錄錯誤日誌、追蹤調用者元數據（如 IP 等）、透過 jsondata 替換功能優化複雜的查詢條件。
• 使用技巧: 在進行大規模基礎設施費用分析時，可將 text 命令與 jsondata 結合使用，確保在調用過程中查詢的完整性。

疑難排解

症狀	原因	解決
出現 401 認證錯誤或返回空響應	缺少 x-api-key 請求標頭或輸入了錯誤的密鑰	確認請求標頭 x-api-key 中設置了有效的密鑰（Azure 費用 API 使用 x-api-key，而非 x-giip-ak）
響應中的 RstVal 返回非 200 代碼	參數或查詢條件錯誤	參考 API 結果代碼指南 確認原因代碼並修正參數
Sk3 的 text 命令調用失敗	text 命令簽名錯誤	確認 text 命令與 jsondata 的組合格式是否正確
傳遞 jsondata 時出現 JSON 解析錯誤	jsondata 內的引號未正確轉義	正確轉義 jsondata 值中的引號後重新發送

---

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

---

相關文檔:

• API 結果代碼指南 (RstVal)