KB Management API User Guide

본 문서는 지식 베이스(KB) 시스템을 외부 스크립트(giipAgentWin 등)에서 관리하기 위한 API 사용법을 안내합니다.

🔌 지식 베이스 관리 페이지로 이동 →

1. 개요

KB API(giipKb)를 호출하여 특정 서버(lssn) 또는 데이터베이스(mdb_id)에 대한 장애 대응 노하우, 설정 정보 등을 저장하고 조회할 수 있습니다.

2. 기본 정보

Endpoint: https://giipfaw.azurewebsites.net/api/giipKb
Authentication: x-api-key 헤더를 통해 세션 토큰(AK/SK)을 전달해야 합니다.

3. 기능 안내 (Endpoints)

3.1 KB 등록 (POST)

새로운 지식 문서를 등록합니다.

Payload (JSON):

{
  "csn": 100,
  "refType": "LSSN", 
  "lssn": 1234,
  "title": "서버 커널 튜닝 가이드",
  "content": "# 가이드\n커널 파라미터 수정 방법...",
  "tags": "kernel,tuning,linux"
}

refType: LSSN(서버), MDB(DB), GENERAL 중 선택

3.2 KB 수정 (PUT)

기존 지식 문서를 수정합니다.

Payload (JSON):

{
  "kbSn": 42,
  "title": "수정된 제목",
  "content": "업데이트된 내용...",
  "tags": "linux,updated"
}

3.3 KB 조회 (GET)

필터 조건에 맞는 KB 목록 또는 상세 정보를 조회합니다.

Query Parameters:

kbSn: 특정 문서 조회 시 사용
lssn: 특정 서버 관련 지식 조회
mdb_id: 특정 DB 관련 지식 조회
searchKeyword: 검색어

3.4 KB 삭제 (DELETE)

지식 문서를 삭제합니다.

Query Parameters:

kbSn: 삭제할 문서 번호

4. SK 기반 API 사용법 (giipAgent 권장)

giipAgent와 같이 상주형 프로그램 또는 자동화 스크립트에서는 세션 만료가 없는 Secret Key(SK)를 사용하는 것이 권장됩니다. SK 기반 호출은 통합 API 엔드포인트(giipApiSk3)를 통해 수행됩니다.

Endpoint: https://giipfaw.azurewebsites.net/api/giipApiSk3
Method: POST (form-urlencoded)

4.1 주요 파라미터

sk: 발급받은 Secret Key
text: 실행할 명령어 (KbCreate, KbUpdate, KbDelete, KbGet, KbList 중 하나)
jsondata: API에 전달할 상세 데이터 (JSON 문자열)

4.2 호출 예제 (PowerShell)

$sk = "YOUR_SECRET_KEY"
$url = "https://giipfaw.azurewebsites.net/api/giipApiSk3"

# KB 등록 예제
$body = @{
    sk = $sk
    text = "KbCreate jsondata"
    jsondata = (@{
        csn = 100
        refType = "LSSN"
        lssn = 1234
        title = "Agent 자동 등록 지식"
        content = "에이전트에서 자동으로 분석된 내용입니다."
        tags = "agent,auto"
    } | ConvertTo-Json -Compress)
}

$response = Invoke-RestMethod -Uri $url -Method Post -Body $body
Write-Host "KB Registered. kbSn: $($response.data[0].kbSn)"

5. `giipAgentWin` 자동화 예제 (AK 기반)

giipAgentWin 스크립트에서 완료된 작업 로그를 AK로 자동 등록하는 예제입니다 (로그인 세션이 유효한 경우).

$ak = "YOUR_SESSION_AK"
$url = "https://giipfaw.azurewebsites.net/api/giipKb"

$body = @{
    title = "자동화 분석 결과 - $(Get-Date -Format 'yyyyMMdd')"
    content = "# 분석 결과`n환경 점검이 완료되었습니다."
    refType = "LSSN"
    lssn = 1201
    csn = 0
    tags = "auto,diag"
} | ConvertTo-Json -Compress

$headers = @{
    "x-api-key" = $ak
    "Content-Type" = "application/json"
}

$response = Invoke-RestMethod -Uri $url -Method Post -Headers $headers -Body $body
Write-Host "KB Registered. kbSn: $($response.kbSn)"

[!TIP] giipv3 프론트엔드의 서버/DB 상세 페이지에서 이 API로 등록된 내용을 즉시 확인할 수 있습니다.

문제 해결

증상	원인	해결
401 Unauthorized 응답	`x-api-key` 헤더에 유효한 AK/SK 토큰이 없거나 세션이 만료됨	헤더에 유효한 토큰을 넣거나, 세션 만료가 없는 SK 기반 `giipApiSk3` 호출로 전환
SK 호출 시 명령이 실행되지 않음	`text` 필드가 `KbCreate jsondata` 형식이 아님	`text`에 명령어(`KbCreate`/`KbUpdate`/`KbDelete`/`KbGet`/`KbList`)와 `jsondata` 키워드를 정확히 기재
등록·수정 시 데이터가 누락됨	`refType` 값이 `LSSN`/`MDB`/`GENERAL` 이외이거나 `kbSn` 누락	허용된 `refType` 세 값 중 하나만 사용하고, PUT/DELETE에는 유효한 `kbSn` 지정
`jsondata` 파싱 오류	`content` 내 개행·따옴표가 이스케이프되지 않음	`ConvertTo-Json -Compress` 등으로 JSON 문자열로 직렬화한 뒤 전송

← PreviousMonitoring Data API Next →Network & Security Policy API