22分で読了

イシュー管理 API リファレンス

GIIPプラットフォーム上のイシューおよびエラーログをプログラミング方式で管理するための技術仕様です。

🔌 イシュー管理機能ページへ →

📋 概要

イシュー管理APIは、自動化スクリプトやAIエージェントがサーバー障害、エラーログ、タスク状態を照会・処理するために使用します。呼び出し方法は主に2種類あります。

🔐 認証 (Authentication)

このAPIが受け付ける鍵の種類、鍵の渡し方、そしてエラーの原因の3点を、すべて実際のソースコード (giipfaw/giipIssues/run.ps1, giipfaw/giipIssueComments/run.ps1, 対応する pApiGiipIssue*byAK SP群)とライブAPI実測(giipfaw、2026-08-20)の両方で確認した内容に基づいて説明します。共通のAK/SK用語定義は **APIリファレンス概要 → 認証**を参照してください。

x-api-key はHTTPヘッダーの「名前」であって、別種の資格情報ではありません。 有効なプロジェクトSK・ユーザー固定キー・ログインセッションAKのいずれかを、このヘッダーの値として直接入れてください。プロジェクト SKを使う場合、別途「APIキー」を発行する必要はありません。

鍵の渡し方 — ヘッダーのみ(実測)

渡し方	対応状況
`x-api-key: <key>` ヘッダー	✅ 対応(推奨)
`Authorization: Bearer <key>` ヘッダー	✅ 対応(代替可)
JSONボディ `{ "token": "<key>" }`	❌ 非対応(サーバーコードが読み取らない。渡しても`401 Auth required`)
クエリ文字列 `?token=<key>`	❌ 非対応/廃止(同上。しかもクエリ文字列に鍵を載せる方式はサーバーログ・ブラウザ履歴・プロキシログに鍵が残るためセキュリティ上使うべきではありません)

以前の版のこのドキュメントには「Body/Queryでも渡せる」という記載がありましたが、giipIssues/giipIssueComments のrun.ps1は$Request.Headers["x-api-key"]→Authorizationヘッダーの2択しか読み取っておらず、実際には機能しません(2026-08-20、コード確認+ライブ実測で削除確定)。鍵は必ずヘッダーで渡してください。

鍵の種類(3種類、権限範囲が異なる)

種類	実体	発行単位	権限範囲	発行/確認	検証方法
プロジェクトSK(推奨・エージェント用)	`tSecretKey.SKey`	プロジェクト(csn)ごと1本	そのcsnのみ。呼び出し者個人は特定されない共有鍵(コメント投稿時の`author`はクライアント指定値がそのまま使われる — 実測確認)	`/svclist`(サービス一覧)画面で発行/再発行	下記「キー検証手順」参照
ユーザー固定キー(`tCorpUser.uSecretKey`)	同上	ユーザー(usn)ごと1本	そのユーザー本人の所属csn(`tUserPerCorp`/`tCorpUserRel`)。管理者権限(uLevel≧99)を持つユーザーなら全csn	管理者が発行(giipv3ユーザー管理画面)	同上
ログインセッションAK	`tUserLogin.AccToken`	ログインのたびに新規発行、24時間で失効	ログインユーザー本人と同一権限	ブラウザログイン時に自動発行(`sessionStorage`)	同上

3種類とも同じx-api-keyヘッダーに渡すだけで、サーバー側が自動判別します(lwGetUSNbyat→失敗時 lwGetUSNbyskのフォールバックチェーン)。レスポンスだけでは呼び出し元がどの種類を使ったか区別できません (成功/失敗の挙動は同一)が、権限範囲(どのcsnにアクセスできるか)は種類によって異なります。

本セッションでの実測は主にプロジェクトSK(giip-accounts.json登録の実運用SK)で行いました。ユーザー固定キー・ログインセッションAKは、ブラウザログインでの新規発行がこのセッションから実行できなかったため、ソースコード分析による確認にとどまります(lwGetUSNbyat.sqlの3段階フォールバックロジックで存在を確認済み。ライブでの新規発行・実測は未実施)。

SKの条件(すべて実測+コード確認)

発行場所: giipv3の/svclist(サービス一覧)画面。プロジェクト(csn)ごとに1本。
アクティブ確認: tSecretKey.SKStatus = 1のときのみ有効。再発行/ローテーションすると旧SKは即座に SKStatus = 0になり、以後401 Invalid sessionを返します(giip #1265で実測: 有効SK→200、無効化済みSK→401を両方確認)。
連結csn: tSecretKey.CSnに1対1で固定。他のcsnへは(管理者権限がない限り)アクセスできません (下記「csn権限の不一致」参照)。
必要権限: SK自体がcsnへのアクセス権を表すため、追加の権限設定は不要です。
有効期限: 時間経過による自動失効はありません(セッションAKと違って24時間制限なし)。無効化されるのは再発行/ローテーション時のみです。
許可エンドポイント: GET/POST/PUT /api/giipIssues、GET/POST /api/giipIssueCommentsのすべてで使用可能(実測確認)。ただしgiipApiSk2経由のGiipIssuePutコマンドは全体上書きSPで別物なので、書き込みには使わないでください(下記「方法2」参照)。
キー検証用の読み取りAPI: 書き込み系(POST/PUT)を呼ぶ前に、まず読み取り専用のGET /api/giipIssuesでキーが有効か安全に確認できます(下記「認証確認の手順」参照)。
再発行方法: /svclist画面で対象csnのSKを再生成します(旧SKは即無効化されるため、依存する自動化があれば同時に更新してください)。

認証確認の手順(書き込み前に安全に検証)

書き込みAPI(POST/PUT)を呼ぶ前に、副作用のないGETでキーの有効性を確認してください。

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://giipfaw.azurewebsites.net/api/giipIssues?csn=47" \
  -H "x-api-key: ${GIIP_API_KEY}"

成功時(200): {"issues":[...]} — このキーはそのまま生成/状態変更APIに使えます。
失敗時(401): {"error":"Auth required"}(ヘッダー自体が無い/読み取れない) または {"error":"Invalid session"}(キーはあるが無効 — 詳細は下記「401 Invalid sessionの原因分類」)。 この場合は生成APIを実行しないでください。

以下の両経路とも正常に動作します。イシュー新規登録やコメントなどの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が返ります。

curl -s -X POST "https://giipfaw.azurewebsites.net/api/giipIssues" \
  -H "x-api-key: ${GIIP_API_KEY}" -H "Content-Type: application/json" \
  -d '{ "title": "タイトル（必須）", "content": "本文", "status": "PENDING",
        "csn": 47, "target_lssn": null, "agent_workflow": null }'

成功: { "isn": 577, "message": "Issue created", "success": true }(実測: 2026-08-20, isn 1282で確認後削除)

2. イシュー一覧照会

URL: GET /api/giipIssues
クエリパラメータ:
- status: (任意) イシュー状態 (READY, PENDING, DONE など)
- isn: (任意) 特定イシューのシリアル番号
- csn: (任意だが指定を推奨) 取得するプロジェクト番号。省略すると鍵の権限範囲内の全csnが返ります。
レスポンス: { "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 }
コメント取得: GET /api/giipIssueComments?isn=7890 → { "comments": [...] }

送信方法まとめ(実測、2026-08-20)

エンドポイント	`x-api-key`ヘッダー	`Authorization: Bearer`ヘッダー	JSONボディ`token`	クエリ`?token=`
`GET /api/giipIssues`	✅ 実測200	✅ 実測200	❌ 未読取(401)	❌ 実測401
`POST /api/giipIssues`(生成)	✅ 実測200	コード同一(未実測・高確度)	❌ 実測401	❌ 実測401
`PUT /api/giipIssues`(状態変更)	✅ 実測200	コード同一(未実測・高確度)	❌ 実測401	コード同一(未実測・高確度)
`POST /api/giipIssueComments`	✅ 実測200	コード同一(未実測・高確度)	❌ 実測401	❌ 実測401
`GET /api/giipIssueComments`	✅ 実測200	コード同一(未実測・高確度)	❌ 未読取	❌ 未読取(未実測・高確度)

「コード同一(未実測・高確度)」は、4エンドポイントすべての認証抽出コード ($Request.Headers["x-api-key"] → 失敗時Authorizationヘッダー、以上2択のみ)が giipfaw/giipIssues/run.ps1・giipIssueComments/run.ps1で完全に同一であることをソースで確認した上での推定です(全20セルを毎回実行はしていません — 主要セルを実測し、残りはコードレビューで代替)。

認証エラー時の挙動(2026-08-24 ライブ実測): 以前の版のこのドキュメントには、GET /api/giipIssueCommentsが無効な鍵でもHTTP 200を返すという既知の不具合の記載がありましたが、これは修正済みです(giip #1285)。現在は GET /api/giipIssuesと同様に動作し、無効な鍵ではHTTP 401 {"error":"Invalid session"}を返します (2026-08-24、giipfaw APIに対してライブ実測で確認)。認証の成否はHTTPステータスで判定して問題ありません。

csn権限の不一致の挙動(非 401)

鍵は有効だが対象csnへのアクセス権がない場合、401にはなりません(実測確認、2026-08-20)。

呼び出し	実測結果
`GET /api/giipIssues?csn=<権限外>`	`200 {"issues":[]}`(空配列。エラーではない)
`POST /api/giipIssues`で`csn`に権限外の値を指定	`200`で成功するが、指定した`csn`は無視され鍵自身のホームcsnに黙って上書き(clamp)される(実測: csn70335のSKで`csn:47`指定→実際は`cSn:70335`で作成された)
特定`isn`のGET/PUT/コメント登録で対象issueのcsnに権限がない	`404 {"error":"Issue not found or no permission"}`

サポートされるステータス値と複数ステータス取得パターン

サポートされるステータス値(実測確認, 2026-08-27):

ステータス値	意味
`PENDING`	登録済み、未処理
`READY`	処理準備完了
`IN_PROGRESS`	処理中
`REVIEW`	人によるレビュー待ち
`TESTED`	テスト完了、最終検収待ち
`WARN`	警告・条件付き完了
`DONE`	完了

複数ステータス取得 — 単一フィルタの完全一致のみ対応(重要):

GET /api/giipIssues?status=TESTED,REVIEW や status=TESTED|REVIEW の形式のOR取得は対応していません。カンマ・パイプ・パラメータの繰り返しはすべて単一の完全一致文字列として認識され、意図どおりに動作しません。

大量処理ワークフロー(例: /gissue-final-review)でTESTEDとREVIEWの両方を処理する必要がある場合は、各ステータスを個別に取得してからクライアント側で順に結合します:

# 1. まずTESTEDを取得
TESTED_ISSUES=$(curl -s "https://giipfaw.azurewebsites.net/api/giipIssues?status=TESTED&csn=47" \
  -H "x-api-key: ${GIIP_API_KEY}")

# 2. REVIEWを取得
REVIEW_ISSUES=$(curl -s "https://giipfaw.azurewebsites.net/api/giipIssues?status=REVIEW&csn=47" \
  -H "x-api-key: ${GIIP_API_KEY}")

# 3. クライアント側でTESTED → REVIEW の順に結合
# (jq, Python, JS など)

注意: 取得時点のキュースナップショットのため、TESTED処理中に新しいREVIEWが入る可能性があります。ワークフローの「最初のスナップショット」基準を守るには、2つのクエリを同時に実行し、以降追加されたイシューは次の実行サイクルの処理対象とします。

コメント全件取得:

GET /api/giipIssueComments?isn=<isn> は対象イシューの全コメントを時系列で返します。AIエージェントの最終検収ワークフロー(/gissue-final-review)では、作業者の完了報告や Actionflow SUCCESS コメントを検証すべき主張であり合格の証拠として扱いません — repo・PR・画面・DBを直接突き合わせて独立した証拠を確保する必要があります。

🤖 AIエージェント向け完全手順(作成→確認→部分更新→コメント)

ChatGPT/Codex等のAIエージェントが、イシューの新規登録・部分更新・コメント追加を安全に実行するための一連の手順です。すべての書き込みの前後にGETで確認します。秘密情報はx-api-keyヘッダーにのみ入れ、body/queryには入れないでください。

部分更新(title/content/status)— 全体上書きではない

専用REST PUT /api/giipIssues は部分更新です。内部SP pApiGiipIssuePutbyAK が各フィールドを ISNULL(@value, existing) で更新するため、JSONに含めなかったフィールドは既存値を保持します(2026-08-24、SPソース確認)。更新可能フィールド: title / content / status / target_lssn / agent_workflow(および権限がある場合のcsn)。

# titleとcontentだけを更新(statusや他フィールドは既存のまま)
curl -sS -X PUT "https://giipfaw.azurewebsites.net/api/giipIssues" \
  -H "x-api-key: ${GIIP_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"isn":1474,"title":"Revised title","content":"Revised body"}'

変更しないフィールドはJSONに含めない(含めると上書きされます)。
空文字は「未指定」ではありません。 "title":"" を送るとタイトルが空に上書きされます。空にする意図がない限り送らないでください。
Sk2のGiipIssuePutは全体上書きSP(pApiGiipIssuePutbySK)なので、編集には使用禁止です(タイトル・本文が破壊されます。方法2参照)。専用REST PUTを使ってください。

長文content(4,000文字超も可)

contentはSP側でOPENJSON ... NVARCHAR(MAX)として読み取られるため、4,000文字を超えるMarkdown本文も登録・更新できます(2026-08-24、SPソース確認)。長い作業指示書をそのままイシュー化できます。

UTF-8のJSONで送信します。
シェルに長文を直接埋め込まず、ファイルからJSON化して送るのが安全です:

# body.json に {"isn":1474,"content":"...(長文)..."} を用意
curl -sS -X PUT "https://giipfaw.azurewebsites.net/api/giipIssues" \
  -H "x-api-key: ${GIIP_API_KEY}" -H "Content-Type: application/json" \
  --data-binary @body.json

登録後、GET /api/giipIssues?isn=<isn>で本文の長さやハッシュ(例: sha256)を照合して、全文が保存されたことを確認します。

コメント追加(必須項目と保存後の確認)

{ "isn": 1474, "content": "Comment body", "author": "ChatGPT Work", "issuetype": "comment" }

必須: isn, content。
既定値: author=Agent, issuetype=comment。
保存author正規化に注意: 資格情報の種類とサーバー側のidentity解決により、送信したauthorが保存時にユーザー名へ正規化されることがあります(2026-08-24実測: author="ChatGPT Work"で送信したコメントがauthor="Lowy Shin"として保存)。送信authorの固定保存を前提にせず、追加後にGET /api/giipIssueComments?isn=<isn>でcontentと実際の保存authorを確認してください。
コメント前にもGET /api/giipIssues?isn=<isn>で対象CSNを確認してください。

End-to-End 例(作成 → 確認 → 部分更新 → 再確認 → コメント → 確認)

# 1. 認証・CSN scope確認(read-only preflight)
curl -sS "https://giipfaw.azurewebsites.net/api/giipIssues?csn=47" -H "x-api-key: ${GIIP_API_KEY}"

# 2. 新規登録(戻り値の isn を取得)
curl -sS -X POST "https://giipfaw.azurewebsites.net/api/giipIssues" \
  -H "x-api-key: ${GIIP_API_KEY}" -H "Content-Type: application/json" \
  -d '{"title":"AI test issue","content":"initial body","csn":47}'

# 3. 実際のcSnを確認(CSN不一致は黙ってホームCSNへclampされるため必須)
curl -sS "https://giipfaw.azurewebsites.net/api/giipIssues?isn=<isn>" -H "x-api-key: ${GIIP_API_KEY}"

# 4. 部分更新(titleのみ。contentはISNULLで保持される)
curl -sS -X PUT "https://giipfaw.azurewebsites.net/api/giipIssues" \
  -H "x-api-key: ${GIIP_API_KEY}" -H "Content-Type: application/json" \
  -d '{"isn":<isn>,"title":"AI test issue (edited)"}'

# 5. 再GETで未指定フィールド(content)が保持されていることを確認
curl -sS "https://giipfaw.azurewebsites.net/api/giipIssues?isn=<isn>" -H "x-api-key: ${GIIP_API_KEY}"

# 6. コメント追加
curl -sS -X POST "https://giipfaw.azurewebsites.net/api/giipIssueComments" \
  -H "x-api-key: ${GIIP_API_KEY}" -H "Content-Type: application/json" \
  -d '{"isn":<isn>,"content":"done","author":"ChatGPT Work","issuetype":"comment"}'

# 7. コメント確認(保存authorとcontentをGETで照合)
curl -sS "https://giipfaw.azurewebsites.net/api/giipIssueComments?isn=<isn>" -H "x-api-key: ${GIIP_API_KEY}"

CSN silent clampの検出: POSTで指定したcsnが権限外の場合、エラーにはならず鍵のホームCSNへ黙ってclampされます。手順3の再GETでcSnが意図通りか必ず確認してください。

🚀 方法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 で状態変更をしないでください（データ破壊のリスク）。 Sk2 GiipIssuePut は内部SP pApiGiipIssuePutbySK(@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）。 状態のみ安全に変更するには、専用REST PUT /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キーに該当プロジェクトの権限が付与されている必要があります(実際の挙動は上記「csn権限の不一致の挙動」参照 — 401ではなく空配列/404/黙ったclampになります)。

401 "Invalid session" の原因分類

401には2種類のエラーメッセージがあり、意味が異なります(実測確認、2026-08-20)。

レスポンス	原因
`{"error":"Auth required"}`	鍵がサーバーに届いていない — `x-api-key`/`Authorization`ヘッダーが無い、または対応していない渡し方(JSONボディの`token`、クエリ`?token=`、間違ったヘッダー名など)を使った
`{"error":"Invalid session"}`	鍵は届いたが無効 — 下記のいずれか

Invalid sessionになる具体的な原因:

キーの値が誤字・存在しない(どのAK/SKテーブルにもマッチしない)
有効だったプロジェクトSKが再発行/ローテーションで無効化された(SKStatus=0) — giip #1265で実測
ログインセッションAKが24時間の有効期限を過ぎた(tUserLogin.AccToken、コード確認のみ・未実測)

該当しないケース(誤解しやすい点):

AK専用エンドポイントにSKを使った/その逆 → 該当なし。giipIssues/giipIssueCommentsはAK・SKのどちらでも動作するよう実装されており、種類による専用エンドポイント分けはありません(実測+コード確認)。
対象csnへの権限がない → 401ではなく、上記「csn権限の不一致の挙動」の通り200(空配列)/200(黙ったclamp)/404になります。

トラブルシューティング

症状	原因	解決
`{"error":"Auth required"}` (401)	ヘッダーに鍵が無い、またはボディ/クエリなど非対応の渡し方をした	`x-api-key: <key>` ヘッダー(または`Authorization: Bearer <key>`)で渡す。ボディ`token`・クエリ`?token=`は使えない
`{"error":"Invalid session"}` (401)	鍵の誤字、無効化済み(再発行/ローテーション)、セッション期限切れのいずれか	上記「認証確認の手順」の`GET`でキーを再検証。`/svclist`で対象csnの現在有効なSKを確認
プロジェクトのイシューが `[]`(空配列)で返る	鍵は有効だが対象csnへの権限がない(401にはならない)	対象csn用の鍵を使う、または管理者に権限付与を依頼
`POST`でcsnを指定したのに違うcsnに作成された	権限外のcsnを指定すると鍵のホームcsnへ黙ってclampされる(実測: 上記参照)	生成後に`GET /api/giipIssues?isn=<isn>`で実際の`cSn`を確認する。別csnへの作成が必要な場合は管理者に`tUserPerCorp`権限付与を依頼
コマンドが無視される/空の結果(Sk2)	`text` パラメータの形式誤り(コマンドとパラメータが未分離)	`GiipIssueList READY` のように `[コマンド] [パラメータ]` 形式を遵守
`... has too many arguments specified` エラー(Sk2)	`text`にSPパラメータを過剰に列挙	SPの正確なパラメータのみを列挙。`@sk`・`jsondata`はエンジンが自動処理するため列挙禁止
状態変更したらタイトル・本文が `DONE`/`{}` などに破壊された(Sk2)	Sk2 `GiipIssuePut`（全体上書きSP）で状態変更を試みた	状態変更は専用REST `PUT /api/giipIssues {isn,status}` を使用（方法1）。Sk2 `GiipIssuePut` はwriteに使わない
レスポンスの `data[0].RstVal` が 200ではない(Sk2)	Stored Procedure実行エラーまたは不正な `isn`	`Proc_MSG` を確認のうえ API結果コードガイドを参照（成功は `0` ではなく `200`）

バージョン: 1.7 最終更新: 2026-08-27(テスト対象API: giipfaw本番, pApiGiipIssue*byAK SP群 — 上記に明記した各実測はこの日付でライブAPIに対して実施) ソースファイル: giipv3/public/help/giip-issue-api.ja.md

v1.7 変更履歴 (2026-08-27, giip #1484): イシュー処理ワークフロー(/gissue-final-review)完了のため次の項目を追加。 ① サポートされるステータス値の表(TESTED/WARN含む、7種類)。② 複数ステータス取得 — 運用APIは単一の完全一致フィルタのみ対応(TESTED,REVIEW／TESTED|REVIEW等の形式は動作しない)のため、各ステータスを個別取得してクライアント側で結合するパターン。③ コメント全件取得の時系列説明と、FINAL-REVIEWワークフローで作業者の完了報告を「主張」として扱い、repo/PR/画面/DBを直接突き合わせた独立した証拠のみを合格として認める検証原則。

v1.6 変更履歴 (2026-08-24, giip #1475): AIエージェント向け完全手順セクションを追加(部分更新／長文content／コメントのauthor正規化／作成→確認→部分更新→コメントのEnd-to-End例)。x-api-keyがヘッダー名であって別種の資格情報ではないことを明記。GET /api/giipIssueCommentsがHTTP 200を返すという旧「既知の不具合」の記載を、修正済み(giip #1285、2026-08-24ライブ実測でHTTP 401を確認)として削除。

v1.5 変更履歴 (2026-08-20, giip #1280): 認証まわりを大幅拡充。① JSONボディtoken・クエリ?token=が giipIssues/giipIssueCommentsでは実際には機能しないことをコード確認+ライブ実測(4エンドポイント)で確定し、誤った記載を削除(クエリ文字列方式はセキュリティ上も非推奨として明記)。② SK/ユーザー固定キー/ログインセッションAKの3種類を発行元テーブル単位で整理(tSecretKey/tCorpUser.uSecretKey/tUserLogin.AccToken)。 ③ 書き込み前にキーを安全確認する手順を追加。④ 401の原因を「Auth required(鍵未達)」と「Invalid session(鍵無効)」に分類し、csn権限不一致は401にならない(空配列/404/黙ったclamp)ことを実測で明記。 ⑤ GET /api/giipIssueCommentsが無効な鍵でもHTTP 200を返す既知の不具合を発見・記載(後続issue登録済み)。 ⑥ 生成例をハードコード鍵から環境変数(${GIIP_API_KEY})に変更。

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 変更履歴 (2026-07-09, task 20260708183049): 実プロダクションAPI（giipv3フロント・giipApiSk2・SPソース）と照合して整合化。 ① Sk2 書き込み経路の危険警告を追加: Sk2 GiipIssuePut は全体上書きSP pApiGiipIssuePutbySK(@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保持）を追加。

関連ドキュメント: