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)