イシュー管理 API リファレンス
GIIPプラットフォーム上のイシューおよびエラーログをプログラミング方式で管理するための技術仕様です。
📋 概要
イシュー管理APIは、自動化スクリプトやAIエージェントがサーバー障害、エラーログ、タスク状態を照会・処理するために使用します。呼び出し方法は主に2種類あります。
🔐 認証 (Authentication)
すべてのリクエストは有効な Secret Key (SK) を含める必要があります。
- Header:
x-api-key: [Your_SK] - Body:
{ "token": "[Your_SK]" }(JSONリクエスト時) - Query:
?token=[Your_SK]
以下の両経路とも正常に動作します。イシュー新規登録やコメントなどのCRUDは専用RESTエンドポイント（giipv3管理UIが実際に使用する経路）を、SP直接呼び出しはgiipApiSk2ラッパーを使用します。
🚀 方法1: 専用エンドポイント (REST API)
イシューを操作する最も直感的な方法で、giipv3管理UIが実際に使用する経路です。認証はx-api-keyヘッダー、Content-Typeはapplication/json。
1. イシュー新規登録
- URL:
POST /api/giipIssues—isnを省略（または0）すると新規イシューがINSERTされ、新しいisnが返ります。 - Body (JSON):
{ "title": "タイトル（必須）", "content": "本文", "status": "PENDING",
"csn": 47, "target_lssn": null, "agent_workflow": null }- 成功:
{ "isn": 577, "message": "Issue created", "success": true }
2. イシュー一覧照会
- URL:
GET /api/giipIssues - クエリパラメータ:
status: (任意) イシュー状態 (READY,PENDING,DONEなど)isn: (任意) 特定イシューのシリアル番号
- レスポンス:
{ "issues": [...] }
3. イシュー状態更新
- URL:
PUT /api/giipIssues（POSTも可） - Body (JSON):
{ "isn": 7890, "status": "DONE" }→{ "success": true }
4. コメント登録
- URL:
POST /api/giipIssueComments - Body (JSON):
{ "isn": 7890, "content": "対応完了。", "author": "api-tester", "issuetype": "comment" }→{ "success": true }
🚀 方法2: 汎用APIラッパー (giipApiSk2)
GIIPのStored Procedureを直接呼び出すskベースの強力な方法で、AIエージェントに推奨されます。一覧・詳細・状態更新すべてこの経路で正常に動作します。
- URL:
POST /api/giipApiSk2 - Content-Type:
application/x-www-form-urlencoded - フィールド:
token:[Your_SK]— SKは必ずこのフィールドのみで渡す（text・jsondataには入れない）text:[コマンド] [パラメータ...]jsondata: (任意) 値マッピング用JSON。例:{}または{"isn":7890,"status":"DONE"}
⚠️
text記述ルール（厳守）:textには当該SPが受け取る正確なパラメータのみを順に列挙します。認証（@sk）とjsondataはエンジン（run.ps1）が自動処理するため、絶対に列挙しないでください。 過剰に列挙するとSPの引数数を超過し、has too many arguments specifiedエラーになります。
主なコマンド例（安全）
| 機能 | SPパラメータ（=textに列挙） | text 例 | 成功 |
|---|---|---|---|
| イシュー一覧 | status | GiipIssueList READY | data（イシュー配列） |
| 詳細取得 | isn | GiipIssueGet 7890 | data[0]（イシュー1件） |
| リモート実行 | isn | GiipIssueDispatch 7890 | data[0].RstVal = 200 |
🚫 Sk2
GiipIssuePutで状態変更をしないでください（データ破壊のリスク）。 Sk2GiipIssuePutは内部SPpApiGiipIssuePutbySK(@sk, @isn, @title, @content, @status, @csn)にマッピングされる全体上書き（full overwrite）です（coalesceなし）。GiipIssuePut 7890 DONEと呼ぶと2番目の値DONEが@titleに、3番目（jsondata）が**@content**に入り、タイトルと本文が破壊されます。レスポンスはRstVal:200（偽の成功）となりますが、実際にはレコードが破損しています（実測: 2026-07-09, task 20260708183049）。 状態のみ安全に変更するには、専用RESTPUT /api/giipIssues {isn, status}を使用してください。内部のpApiGiipIssuePutbyAKがISNULL(@title, title)で既存のタイトル・本文を保持します（=giipv3フロントが実際に使う経路）。
🔍 レスポンス標準
giipApiSk2 (SPラッパー) レスポンス — 照会はdata配列にレコード、SPアクション（Dispatch等）は成功時 RstVal = 200:
{ "data": [ { "RstVal": 200, "Proc_MSG": "Dispatched", "isn": 7890 } ] }照会コマンド（GiipIssueList/GiipIssueGet）はdata配列にイシューレコードが入ります。
専用RESTエンドポイント レスポンス — 成功時は success: true（本文にRstValなし）:
{ "isn": 7890, "message": "Issue updated", "success": true }ℹ️ 成功判定の注意: SP成功コードは
RstVal = 200であり0ではありません。失敗時は400/401/403/404を返します（K-Layer CLAIM-006）。専用エンドポイントはRstValの代わりにsuccessブール値を返します。
⚠️ 重要な注意事項
- 500 Internal Server Error: 「The term 'if' is not recognized」が発生した場合、サーバー側のPowerShell互換性の問題です。最新パッチ (v1.0.1+) が適用されているか確認してください。
- CSN制限: 特定プロジェクトグループに属するイシューへアクセスするには、APIキーに該当プロジェクトの権限が付与されている必要があります。
トラブルシューティング
| 症状 | 原因 | 解決 |
|---|---|---|
| 認証失敗 / 401 | Secret Key(SK)の欠落または誤り | x-api-key ヘッダーまたは token パラメータに有効なSKを設定 |
| コマンドが無視される/空の結果 | text パラメータの形式誤り(コマンドとパラメータが未分離) | GiipIssueList READY のように [コマンド] [パラメータ] 形式を遵守 |
... has too many arguments specified エラー | textにSPパラメータを過剰に列挙 | SPの正確なパラメータのみを列挙。@sk・jsondataはエンジンが自動処理するため列挙禁止 |
状態変更したらタイトル・本文が DONE/{} などに破壊された | Sk2 GiipIssuePut（全体上書きSP）で状態変更を試みた | 状態変更は専用REST PUT /api/giipIssues {isn,status} を使用（方法1）。Sk2 GiipIssuePut はwriteに使わない |
レスポンスの data[0].RstVal が 200ではない | Stored Procedure実行エラーまたは不正な isn | Proc_MSG を確認のうえ API結果コードガイド を参照（成功は 0 ではなく 200） |
| プロジェクトグループのイシューが返らない | APIキーに該当CSN/プロジェクトの権限がない | キーに該当プロジェクトの権限を付与 |
バージョン: 1.3
最終更新: 2026-07-09
ソースファイル: giipv3/public/help/giip-issue-api.ja.md
v1.3 変更履歴 (2026-07-09, task 20260708183049): 実プロダクションAPI（giipv3フロント・giipApiSk2・SPソース）と照合して整合化。 ① Sk2 書き込み経路の危険警告を追加: Sk2
GiipIssuePutは全体上書きSPpApiGiipIssuePutbySK(@sk,@isn,@title,@content,@status,@csn)にマッピングされ、GiipIssuePut 7890 DONEがタイトル・本文を破壊する（偽のRstVal:200）。実測確認（577/578破損→復旧）。書き込み（作成/状態/コメント）は専用RESTエンドポイントへ、Sk2は照会・アクション専用として案内。（旧レポートの「too many arguments/非互換」は部分的観察で、実際の危険はSPが全体上書きである点。） ② 成功コードはRstVal = 200（0ではない） — レスポンス例・トラブルシューティング表を修正。 ③ イシュー新規登録（POST /api/giipIssues、isn省略で新規）と安全な状態変更（PUT /api/giipIssues {isn,status}、ISNULL保持）を追加。
関連ドキュメント: