Sk3 (고성능 로깅 및 무결성 검증) API 가이드

GIIP 플랫폼의 에이전트 전송 에러 감지 및 데이터 무결성 검증을 위한 High-fidelity 로깅 브릿지 API인 giipApiSk3의 사용 방법을 안내합니다.

📋 개요

giipApiSk3는 기존 giipApi에 강력한 로깅 및 데이터 파싱 기능을 더한 향상된 엔드포인트입니다. 에이전트의 요청 처리 중 발생하는 모든 예외와 경고를 자동으로 tErrorLogs 테이블에 상세히 기록하며, 복잡한 JSON 데이터를 SQL 파라미터로 자동 매핑하는 기능을 제공합니다.

⚠️ 엔드포인트 포지셔닝 (중요)

giipApiSk3은 디버깅·고신뢰 로깅 검증 전용 엔드포인트이며, Azure Function 레벨에서 익명(Anonymous) 인증을 사용합니다. 운영 에이전트의 표준 엔드포인트는 giipApiSk2입니다. 프로덕션 트래픽을 상시 Sk3로 전환하지 마세요. Sk3는 Sk2의 처리 로직에 상세 로깅을 더한 사본이므로, Sk2에서 정상인 요청이 Sk3에서만 실패한다면 이는 Sk3의 디버그 코드 문제입니다(이 경우 Sk2는 절대 수정하지 말고 Sk3만 점검).

📡 엔드포인트 정보

• URL: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 인증: Azure Function 레벨에서는 익명(Anonymous) 인증을 사용하지만, 실제 DB 작업 시에는 유효한 usertoken(AK) 또는 sk(Secret Key) 필드를 요청 본문에 포함해야 합니다.

🔐 주요 파라미터

필드명	타입	설명
text	String	실행하고자 하는 명령 문자열 (예: LSVRList, KVSPut)
jsondata	String	복잡한 파라미터를 담은 JSON 문자열
token / sk	String	인증을 위한 Access Key 또는 Secret Key
user_id	String	호출하는 사용자 ID
lssn	String	세션/서버 식별자 (필요 시)

🚀 주요 특장점

1. High-fidelity 로깅

모든 API 호출 시 클라이언트 IP, User-Agent, Referer 정보를 자동으로 수집하며, 에러 발생 시 StackTrace를 포함한 상세 로그를 tErrorLogs에 기록합니다.

2. jsondata 자동 치환

text 파라미터 내의 키워드를 jsondata에 포함된 값으로 자동 치환합니다.

• 예시:
  • text: LSvrPut 'jsondata', 44
  • jsondata: {"lsUsage": "Web_Server"}
  • 실제 실행 쿼리: exec pApiLSvrPutbySk '...', N'Web_Server', 44

3. KVSPut 자동 매핑

text에 KVSPut 명령이 포함된 경우, jsondata의 kType, kKey, kFactor, kValue 필드를 자동으로 추출하여 pApiKVSPutbySk 프로시저를 호출합니다.

💻 사용 예제

PowerShell 호출 예시

$apiUrl = "https://giipfaw.azurewebsites.net/api/giipApiSk3"
$body = @{
    text      = "KVSPut lssn, 1234, netstat"
    jsondata  = @{
        connections = @(
            @{ remote_ip = "10.0.0.10"; state = "ESTABLISHED" }
        )
    } | ConvertTo-Json -Compress
    usertoken = "YOUR_ACCESS_KEY"
}

$resp = Invoke-RestMethod -Uri $apiUrl -Method Post -ContentType "application/x-www-form-urlencoded" -Body $body
$resp.data

cURL 호출 예시

curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk3" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "text=ErrorLogList 50" \
     --data-urlencode "usertoken=YOUR_ACCESS_KEY"

🔍 응답 데이터 구조

성공 시 다음과 같은 JSON 구조를 반환합니다.

{
  "data": [
    { ... 결과 레코드 ... }
  ],
  "debug": {
    "_debug_spName": "ErrorLogList",
    "_debug_executedQuery": "exec pApiErrorLogListbySk '...', 50"
  }
}

문제 해결

증상	원인	해결
모든 요청에서 HTTP 500이 반환됨	Sk3 디버그 함수의 구문/컴파일 오류 (Sk2에서는 정상)	Sk2는 절대 수정하지 말고 giipApiSk3 함수 코드만 점검하여 구문 오류를 수정합니다.
RstVal 401 또는 인증 거부가 발생함	요청 본문에 usertoken(AK) 또는 sk 필드 누락	익명 인증과 별개로 유효한 usertoken/sk를 본문에 포함합니다.
jsondata의 값이 실행 쿼리에 반영되지 않음	text의 치환 키워드와 jsondata 필드명 불일치	text의 'jsondata' 위치와 jsondata 키(예: lsUsage)가 정확히 일치하는지 확인합니다.
KVSPut 호출이 무시되거나 값이 비어 저장됨	jsondata에 kType/kKey/kFactor/kValue 필드 누락	네 개 필드를 모두 포함하여 pApiKVSPutbySk 매핑이 완성되도록 합니다.

---

버전: 1.0
최종 업데이트: 2026-04-10
문서 위치: giipv3/public/help/api-sk3.ko.md

---

관련 문서:

• API 결과 코드 가이드 (RstVal)