giip

이슈 관리 API 레퍼런스

GIIP 플랫폼에서 발생하는 이슈 및 에러 로그를 프로그래밍 방식으로 조회하고 상태를 업데이트하는 API를 안내합니다.

🔌 이슈 관리 기능 페이지로 이동 →

📋 개요

이 API 모듈은 실시간 이슈 관리 솔루션인 [이슈 관리] 메뉴의 데이터를 외부 시스템과 동기화하거나, 장애 대응 파이프라인(ITSM 등)과 연동하기 위해 사용됩니다.

🔐 인증 및 헤더 (Authentication)

모든 요청은 유효한 **Secret Key (SK)**를 포함해야 합니다.

  • 전용 REST 엔드포인트: HTTP 헤더 x-api-key: [Your_SK] (권장). x-giip-sk 헤더, ?token= 쿼리도 지원.
  • giipApiSk2 래퍼: form 필드 token: [Your_SK] 만 사용. SK를 text·jsondata에 넣지 마세요.

🚀 주요 API 엔드포인트 (실제 구현 기준)

이슈 API는 두 경로 모두 정상 동작합니다. 신규 등록·코멘트 등 CRUD는 전용 REST 엔드포인트(giipv3 어드민 UI가 실제 사용하는 경로)를, SP 직접 호출은 giipApiSk2 래퍼를 사용합니다.

1. 이슈 전용 엔드포인트 (REST API)

가장 직관적인 호출 방식이며, giipv3 어드민 UI가 실제 사용하는 경로입니다. 인증은 x-api-key 헤더, Content-Type은 application/json.

  • 신규 등록: POST /api/giipIssues — isn을 생략(또는 0)하면 신규 이슈가 INSERT되고 새 isn을 반환합니다.
    • Body: { "title":"제목(필수)", "content":"본문", "status":"PENDING", "csn":47, "target_lssn":null, "agent_workflow":null }
    • 성공: { "isn":577, "message":"Issue created", "success":true }
  • 목록 조회: GET /api/giipIssues?status=READY
  • 상세 조회: GET /api/giipIssues?isn=7890
  • 상태 업데이트/완료: PUT /api/giipIssues
    • Body: { "isn":7890, "status":"DONE" } → { "success":true }
  • 코멘트 등록: POST /api/giipIssueComments
    • Body: { "isn":7890, "content":"처리 완료", "author":"api-tester", "issuetype":"comment" } → { "success":true }

2. 범용 API 래퍼 (giipApiSk2)

GIIP의 Stored Procedure를 직접 호출하는 sk 기반 방식이며, 조회(List/Get)와 에이전트 액션(Dispatch/ReadinessCheck) 에 사용합니다. 생성·상태변경·코멘트 등 쓰기(write)는 이 경로로 하지 말고 위 §1 전용 REST 엔드포인트를 사용하세요(이유는 아래 🚫 참고).

  • URL: POST /api/giipApiSk2
  • Content-Type: application/x-www-form-urlencoded
  • 필드:
    • token: [Your_SK] — SK는 반드시 이 필드로만 전달
    • text: [Command] [파라미터...]
    • jsondata: 값 매핑용 JSON(선택). 예: {} 또는 {"lssn":101}

⚠️ text 작성 규칙(엄수): text에는 해당 SP가 받는 정확한 파라미터만 순서대로 나열합니다. 인증(@sk)과 jsondata는 엔진(run.ps1)이 자동 처리하므로 절대 나열하지 마세요. 파라미터를 과다 나열하면 SP 인자 개수를 초과해 has too many arguments specified 오류가 납니다.

명령(안전)SP 파라미터(=text에 나열)text 예시성공 응답
목록 조회statusGiipIssueList READYdata(이슈 배열)
상세 조회isnGiipIssueGet 7890data[0](이슈 1건)
원격 실행isnGiipIssueDispatch 7890data[0].RstVal = 200

🚫 GiipIssuePut을 Sk2로 상태변경에 쓰지 마세요 (데이터 파괴 위험). Sk2 GiipIssuePut은 내부 SP pApiGiipIssuePutbySK(@sk, @isn, @title, @content, @status, @csn)에 매핑되는 전체 덮어쓰기(full overwrite) 입니다(coalesce 없음). GiipIssuePut 7890 DONE로 부르면 두 번째 값 DONE이 @title로, 세 번째(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 불리언을 반환합니다.

💡 활용 사례

  • 슬랙 알림 봇: API를 주기적으로 호출하여 신규 Critical 이슈 발생 시 즉시 개발팀 채널에 메시지를 보냅니다.
  • 자동 복구 스크립트: 특정 유형의 이슈(예: 프로세스 다운) 탐지 시 API로 이슈를 확인하고, 원격 명령 API(api-system)를 호출하여 해당 서비스를 재시작합니다.

🛡️ Sk3(고성능 로깅) 활용

장애 대응 시스템이나 외부 티켓팅 도구와의 연동 시, 업데이트 무결성 보장과 상세한 호출 이력 추적을 위해 giipApiSk3 엔드포인트를 권장합니다.

  • 엔드포인트: https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 장점: 이슈 상태 업데이트(Done 처리 등) 실패 시 호출자의 상세 환경 정보(IP, UA)와 StackTrace를 즉시 tErrorLogs에 기록하여 장애 대응 프로세스의 신뢰성을 높여줍니다.
  • 활용 팁: jsondata 치환 기능을 사용하여 이슈 내의 특정 변수값이나 긴 에러 메시지를 파라미터 유실 없이 안전하게 전송할 수 있습니다.

문제 해결

증상원인해결
인증 실패(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 실행 오류 또는 잘못된 isnProc_MSG 확인 후 API 결과 코드 가이드 참조 (성공은 0이 아니라 200)
긴 에러 메시지·특수문자 전송 시 값 유실JSON 값 이스케이프 처리 누락giipApiSk3의 jsondata 치환 기능으로 안전하게 전송

버전: 1.3 최종 업데이트: 2026-07-09 소스 파일: giipv3/public/help/giip-issue-api.ko.md

v1.3 변경 이력 (2026-07-09, task 20260708183049): 실제 프로덕션 API(giipv3 프론트·giipApiSk2·SP 소스)와 대조하여 정합화. ① Sk2 쓰기 경로 위험 경고 추가: Sk2 GiipIssuePut은 내부 pApiGiipIssuePutbySK(@sk,@isn,@title,@content,@status,@csn) 전체 덮어쓰기 SP라 GiipIssuePut 7890 DONE이 제목·본문을 파괴함(응답은 가짜 RstVal:200). 실측 확인(577·578 오손 후 복구). 생성·상태변경·코멘트는 전용 REST 엔드포인트로, Sk2는 조회·액션 전용으로 안내. (과거 보고서의 "too many arguments 비호환" 진단은 부분적 관찰이었고, 실제로는 SP가 full-overwrite여서 위험한 것.) ② 성공 코드는 RstVal = 200(0 아님) — 응답 예시·문제 해결 표 정정. ③ 이슈 신규 등록 절차(POST /api/giipIssues, isn 생략 시 신규) 및 안전한 상태변경(PUT /api/giipIssues {isn,status}, ISNULL 보존) 추가.

관련 문서:

← PreviousDatabase Management APIsNext →Cost Analysis APIs