6分鐘閱讀

問題管理 API 參考

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

🔌 前往問題管理功能頁 →

📋 概述

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

🔐 認證 (Authentication)

⚠️ 本節為精簡版(完整版含逐端點實測矩陣、金鑰類型對照表、401 原因分類等，請參見英文版或日文版、韓文版，2026-08-20 起為最新，本頁尚待完整翻譯)。

僅支援請求標頭：x-api-key: <key>(建議)或 Authorization: Bearer <key>。
❌ 不支援 JSON 請求主體 { "token": "<key>" }，也不支援查詢字串 ?token=<key>——伺服器端程式碼 (giipfaw/giipIssues/run.ps1、giipIssueComments/run.ps1)只讀取上述兩種請求標頭，其餘方式一律回傳 401 {"error":"Auth required"}(已於 2026-08-20 透過原始碼核查 + 正式環境實測確認，先前版本中關於 Body/Query 可用的說明有誤，已刪除)。以查詢字串傳遞金鑰本身也是安全反模式(會殘留在伺服器日誌/瀏覽器歷史記錄/代理日誌中),已正式棄用。
金鑰必須處於「啟用」狀態: POST /api/giipIssues 的伺服器端邏輯(pApiGiipIssuePutbyAK)在登入工作階段 AK 認證失敗時會自動退回到 SK 認證(已針對 giip #1265 現場重新驗證)。但 SK 是依 giipv3 專案(csn)從 /svclist(服務清單)頁面簽發的,重新簽發/輪替會立即讓舊 SK 失效,失效的(舊)SK 呼叫會回傳 401 Invalid session。遇到 401 時,請先到 /svclist 確認目前有效的 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
用 SK 呼叫 `POST /api/giipIssues` 卻回傳 `401 Invalid session`	伺服器已正確支援 SK 認證(已現場重新驗證,giip #1265)。真正原因通常是該 SK 已失效(被重新簽發/輪替)、打錯字,或是其他 csn 的 SK	到 `/svclist`(服務清單)確認目標 csn 目前有效的 SK 後重試;也可暫時改用登入工作階段 AK
命令被忽略或回傳空結果	`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.4 最後更新: 2026-08-20 原始檔: giipv3/public/help/giip-issue-api.zh-TW.md

變更紀錄 (v1.4, 2026-08-20, giip #1265): 針對「用 SK 呼叫 POST /api/giipIssues 卻回傳 401 Invalid session」的回報做了現場驗證。正式環境 Azure SQL 上部署的 pApiGiipIssuePutbyAK 定義與程式庫原始碼完全一致,SK 回退認證(lwGetUSNbyat 失敗後回退到 lwGetUSNbysk)已正確部署(不是部署缺口)。實測重現:用啟用狀態的 SK 呼叫回傳 200 Issue created;用已失效(被輪替/重新簽發)的舊 SK 呼叫則回傳 401 Invalid session(2026-08-20,直接對正式環境 giipfaw API 兩種情況分別驗證)。因此這不是程式碼缺陷,而是文件沒有說明「哪個 SK 才有效」。已在認證章節與疑難排解表補上 SK 啟用狀態要求及 /svclist 複核路徑。

變更紀錄 (v1.3): 已與正式環境 (live production) API 對照校正 (task 20260708183049)。 ① 新增 Sk2 寫入路徑的危險警告：GiipIssuePut 背後是全量覆寫 SP pApiGiipIssuePutbySK，會摧毀標題／內文（已透過破壞並復原 577／578 號問題實測驗證）。寫入一律走 REST 端點，Sk2 僅用於讀取／動作。 ② 成功代碼為 RstVal = 200，而非 0。 ③ 新增問題建立 (Create Issue) 程序，並說明狀態變更請透過 REST PUT /api/giipIssues 安全進行。

相關文件:

API 結果代碼指南 (RstVal)

問題管理 API 參考

📋 概述

🔐 認證 (Authentication)

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

1. 建立問題 (新增)

2. 新增留言 (Add Comment)

3. 查詢問題列表

4. 更新問題狀態

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

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

常用命令範例

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

🔍 回應標準

giipApiSk2 (SP 包裝器) 成功回應

專用 REST 端點成功回應

⚠️ 重要提示

疑難排解

相關指南

問題管理 API 參考

📋 概述

🔐 認證 (Authentication)

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

1. 建立問題 (新增)

2. 新增留言 (Add Comment)

3. 查詢問題列表

4. 更新問題狀態

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

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

常用命令範例

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

🔍 回應標準

giipApiSk2 (SP 包裝器) 成功回應

專用 REST 端點成功回應

⚠️ 重要提示

疑難排解

相關指南

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

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