问题管理 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. 添加评论

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
命令被忽略或返回空结果	`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.3 最后更新: 2026-07-09 源文件:

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

变更记录 (v1.3): 与生产环境实时 API 核对校准 (参考任务 20260708183049)。① 新增 Sk2 写入路径危险警告 ——

GiipIssuePut

是全量覆盖(full-overwrite)SP,会摧毁标题与正文(经破坏并恢复 577/578 号问题验证);写入应走 REST 端点,Sk2 仅用于读取/动作；② 成功代码为

RstVal = 200

而非 0；③ 新增问题创建流程,并明确安全的状态变更走 REST

PUT /api/giipIssues {isn, status}

。

相关文档:

API 结果代码指南 (RstVal)