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. 添加评论

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 代理使用。仅用于读取和代理动作(查询列表、获取详情、远程执行),不用于写入(状态变更)。 写入请使用方式 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)真正接受的参数，且按顺序排列。 引擎 (run.ps1) 会自动追加认证参数 (@sk) 和 jsondata，因此绝不要在 text 中列出它们。一旦多列参数，就会超出 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 不可用于写入(状态变更)。 它映射到存储过程 pApiGiipIssuePutbySK(@sk, @isn, @title, @content, @status, @csn)，这是一个全量覆盖(full-overwrite)、不做保留合并的 SP。因此 GiipIssuePut 7890 DONE 会把 "DONE" 写入 @title、把 jsondata 写入 @content，摧毁原有的标题和正文，却仍返回一个虚假的 RstVal:200(已在实测中破坏 577/578 号问题)。要安全地变更状态，请使用专用 REST 端点 PUT /api/giipIssues {isn, status}(映射到 pApiGiipIssuePutbyAK，采用 ISNULL(@title, title) 保留既有值 —— 这也是 giipv3 前端所用的路径)。

🔍 响应标准

成功时返回 200 OK 及 JSON 数据。两种调用方式的响应结构不同：

giipApiSk2 (SP 包装器) 成功响应 —— 成功标志为 RstVal = 200：

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

该示例代表读取/动作结果：读取类命令在 data 中返回记录，动作类命令返回 RstVal = 200。

专用 REST 端点成功响应 —— 响应体中没有 RstVal：

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

说明: 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`
`... 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
`500 Internal Server Error` ("The term 'if' is not recognized")	服务器端 PowerShell 兼容性问题	确认已应用最新补丁 (v1.0.1+)
项目组的问题未返回	API 密钥缺少该 CSN/项目的权限	为密钥授予相应项目的权限

版本: 1.4 最后更新: 2026-08-20 源文件: giipv3/public/help/giip-issue-api.zh-CN.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): 与生产环境实时 API 核对校准 (参考任务 20260708183049)。① 新增 Sk2 写入路径危险警告 —— GiipIssuePut 是全量覆盖(full-overwrite)SP,会摧毁标题与正文(经破坏并恢复 577/578 号问题验证);写入应走 REST 端点,Sk2 仅用于读取/动作；② 成功代码为 RstVal = 200 而非 0；③ 新增问题创建流程,并明确安全的状态变更走 REST PUT /api/giipIssues {isn, status}。

相关文档:

API 结果代码指南 (RstVal)