giip

問題管理 API 參考

本文件提供在 GIIP 平台上以程式化方式管理問題及錯誤日誌的技術規範。

🔌 前往問題管理功能頁 →

📋 概述

問題管理 API 供自動化腳本或 AI 代理查詢與處理伺服器故障、錯誤日誌及任務狀態。主要有兩種呼叫方式。

🔐 認證 (Authentication)

每個請求都必須包含有效的 Secret Key (SK)。

  • Header: 
    x-api-key: [Your_SK]
  • Body: 
    { "token": "[Your_SK]" }
    (JSON 請求時)
  • Query: 
    ?token=[Your_SK]

🚀 方式 1: 專用端點 (REST API)

與問題互動最直觀的方式。REST 端點使用 

x-api-key
請求標頭進行認證，Content-Type 為 
application/json
。

1. 建立問題 (新增)

  • URL: 
    POST /api/giipIssues
  • 說明: 省略 
    isn
    (或傳送 
    0
    ) 即會 INSERT 一筆新問題，回應會回傳新產生的 
    isn
    。
  • 請求主體 (JSON):
{
  "title": "標題 (必填)",
  "content": "內容",
  "status": "PENDING",
  "csn": 47,
  "target_lssn": null,
  "agent_workflow": null
}
  • 成功回應:
{ "isn": 577, "message": "Issue created", "success": true }

2. 新增留言 (Add Comment)

  • URL: 
    POST /api/giipIssueComments
  • 請求主體 (JSON):
{
  "isn": 7890,
  "content": "...",
  "author": "api-tester",
  "issuetype": "comment"
}
  • 成功回應:
{ "success": true }

3. 查詢問題列表

  • URL: 
    GET /api/giipIssues
  • 查詢參數: 
    • status
      : (選填) 問題狀態 (
      READY
      , 
      PENDING
      , 
      DONE
      等)
    • isn
      : (選填) 特定問題的序號
  • 回應: 
    { "issues": [...] }

4. 更新問題狀態

  • URL: 
    POST /api/giipIssues
    或 
    PUT /api/giipIssues
  • 請求主體 (JSON):
{
  "isn": "7890",
  "status": "DONE",
  "comment": "無法重現，已關閉。"
}

🚀 方式 2: 通用 API 包裝器 (giipApiSk2)

直接呼叫 GIIP 儲存程序的強大方式，適合 AI 代理進行讀取與代理動作（列表查詢、詳情取得、遠端派工/執行）。⚠️ 請勿用 Sk2 進行寫入（狀態變更、建立、編輯）；寫入請一律使用方式 1 的專用 REST 端點。

  • URL: 
    POST /api/giipApiSk2
  • Content-Type: 
    application/x-www-form-urlencoded
  • 欄位: 
    • token
      : 
      [Your_SK]
      — SK 只放在這裡，絕對不要放進 
      text
      或 
      jsondata
      。
    • text
      : 
      [命令] [參數...]
    • jsondata
      : (選填) 例如 
      {}
      或 
      {"isn":7890,"status":"DONE"}

⚠️ 關鍵警告：
text
只列出 SP 實際接受的參數

在 

text
中，只依序列出該儲存程序 (SP) 實際接受的參數。引擎 (
run.ps1
) 會自動附加認證 (
@sk
) 與 
jsondata
，因此絕對不要把它們列進去。 一旦多列參數，就會超出 SP 的引數數量，導致錯誤 
has too many arguments specified
。

常用命令範例

功能SP 參數 (列於 text)
text
參數值		說明
查詢問題列表
status
GiipIssueList READY
僅取得 READY 狀態的問題
取得詳情
isn
GiipIssueGet 7890
取得 ISN 7890 的詳細資訊
遠端執行
isn
GiipIssueDispatch 7890
派工/執行 ISN 7890 的動作 (成功時 
data[0].RstVal = 200
)

🚫 危險：切勿用 Sk2 
GiipIssuePut
變更狀態

Sk2 的 

GiipIssuePut
對應到 SP 
pApiGiipIssuePutbySK(@sk, @isn, @title, @content, @status, @csn)
，這是全量覆寫 (full-overwrite)、不做 coalesce。 因此 
GiipIssuePut 7890 DONE
會把 
DONE
寫進 
@title
、把 
jsondata
寫進 
@content
，摧毀原本的標題與內文，卻仍回傳假的 
RstVal:200
（已實測破壞 577／578 號問題）。 要安全變更狀態，請改用方式 1 的 REST 
PUT /api/giipIssues {isn,status}
，其對應 SP 
pApiGiipIssuePutbyAK
使用 
ISNULL(@title, title)
保留既有值 — 這也是 giipv3 前端實際採用的路徑。

🔍 回應標準

兩種呼叫方式的成功回應形狀不同，請分別確認。

giipApiSk2 (SP 包裝器) 成功回應

{
  "data": [
    { "RstVal": 200, "Proc_MSG": "Dispatched", "isn": 7890 }
  ]
}

此為讀取／動作 (read/action) 結果：讀取會在 

data
中回傳記錄；動作則回傳成功代碼 
RstVal = 200
。

專用 REST 端點成功回應

{ "isn": 7890, "message": "Issue updated", "success": true }

回應主體中沒有 

RstVal
。

📌 成功代碼說明: SP 的成功代碼為 

RstVal = 200
（不是 0）；失敗會回傳 400 / 401 / 403 / 404。專用端點則以 
success
布林值取代 
RstVal
。

⚠️ 重要提示

  • 500 Internal Server Error: 若出現 "The term 'if' is not recognized"，為伺服器端 PowerShell 相容性問題。請確認已套用最新修補程式 (v1.0.1+)。
  • CSN 限制: 要存取屬於特定專案群組的問題，API 金鑰必須具備相應專案的權限。

疑難排解

症狀原因解決
認證失敗 / 401缺少或錯誤的 Secret Key在 
x-api-key
請求標頭或 
token
參數中填入有效的 SK
命令被忽略或回傳空結果
text
參數格式錯誤(命令與參數未分隔)		遵循 
[命令] [參數]
格式，如 
GiipIssueList READY
500 Internal Server Error
("The term 'if' is not recognized")		伺服器端 PowerShell 相容性問題確認已套用最新修補程式 (v1.0.1+)
... has too many arguments specified
text
中列出的參數過多		只列出該 SP 實際接受的參數；
@sk
與 
jsondata
會自動附加
狀態變更後標題／內文被破壞為 DONE／{} 等用 Sk2 
GiipIssuePut
（全量覆寫 SP）改狀態		改用專用 REST 
PUT /api/giipIssues {isn,status}
（方式 1）；Sk2 
GiipIssuePut
不用於寫入
回應 
data[0].RstVal
不是 200		SP 錯誤或 isn 錯誤檢查 
Proc_MSG
；成功代碼為 200 而非 0
專案群組的問題未回傳API 金鑰缺少該 CSN/專案的權限為金鑰授予相應專案的權限

版本: 1.3 最後更新: 2026-07-09 原始檔: 

giipv3/public/help/giip-issue-api.zh-TW.md

變更紀錄 (v1.3): 已與正式環境 (live production) API 對照校正 (task 20260708183049)。 ① 新增 Sk2 寫入路徑的危險警告：

GiipIssuePut
背後是全量覆寫 SP 
pApiGiipIssuePutbySK
，會摧毀標題／內文（已透過破壞並復原 577／578 號問題實測驗證）。寫入一律走 REST 端點，Sk2 僅用於讀取／動作。 ② 成功代碼為 
RstVal = 200
，而非 0。 ③ 新增問題建立 (Create Issue) 程序，並說明狀態變更請透過 REST 
PUT /api/giipIssues
安全進行。

相關文件:

← Previous
資料庫管理 API
Next →
費用分析API