3분 읽기

서버 관리 API 가이드 (v1.5)

GIIP 플랫폼의 핵심 자산인 논리 머신(LSVR)을 조회하기 위한 API 가이드입니다.

🔌 서버 목록 기능 페이지로 이동 →

📋 개요

서버 관리 API를 통해 인프라 내의 서버 자산 정보를 조회할 수 있습니다.

🔐 인증 및 보안 (실제 구현 기준, 2026-08-20 giip #1277 실측)

아래 API들은 giipv3 어드민 UI가 아니라 giipApiSk2 범용 SP 래퍼를 통해 호출합니다(SP를 직접 호출하는 sk 기반 방식). 이 래퍼는 HTTP 헤더가 아니라 POST 본문의 필드로만 인증합니다.

엔드포인트: POST https://giipfaw.azurewebsites.net/api/giipApiSk2
Content-Type: application/x-www-form-urlencoded
필드:
- text: [명령어] [파라미터 이름...]
- token: [Your_SK] — SK는 반드시 이 필드로 전달(text나 jsondata에 SK를 넣지 마세요)
- jsondata: 파라미터 값(선택, 명령별로 형식이 다름 — 아래 LsvrDetail 참고)
⚠️ giipfaw/giipApiSk2/run.ps1을 직접 확인한 결과(2026-08-20), 이 엔드포인트는 HTTP 헤더를 전혀 파싱하지 않습니다. x-giip-ak/x-giip-sk/x-api-key 등 어떤 헤더를 보내도 무시되며, Azure Function 자체도 authLevel: anonymous라 함수 키(?code=)도 필요 없습니다. 인증은 오직 위 token 필드 값으로만 이뤄집니다.

📡 API 상세

서버 상세 정보 단건 조회 (LsvrDetail) — 실측 검증 완료 (giip #1277)

명령: text=LsvrDetail
설명: LSSN(내부 서버 일련번호) 1건의 상세 정보를 반환합니다. 내부적으로 pApiLSVRDetailbySk(@sk, @lssn bigint, @jsondata=NULL) → pLSvrDescOptbyAT를 호출합니다.

요청 예시:

POST https://giipfaw.azurewebsites.net/api/giipApiSk2
Content-Type: application/x-www-form-urlencoded

text=LsvrDetail&token={SK}&jsondata=71289

(71289는 조회할 서버의 LSSN)

응답 예시 (lssn=71289):

{ "data": [ { "LSsn": 71289, "LSHostname": "shinsema0104", "CSn": 70418, "CGCode": "smtodr-group", "lsRegdt": "2026-...", "LSLastHeartbeat": null } ] }

🚨 jsondata는 반드시 raw 숫자 문자열만 (객체로 감싸면 실패):
- ✅ 성공: jsondata=71289
- ❌ 실패: jsondata={"lssn":71289}, {"id":71289}, {"isn":71289} 등 — 어떤 키로 감싸도 모두 Error converting data type nvarchar to bigint 오류가 납니다.
- 원인: text 값이 LsvrDetail 한 단어뿐이라(뒤에 파라미터 이름이 없음) run.ps1은 이 호출을 "파라미터 이름 없는 단일 명령" 경로로 처리합니다. 이 경로에서는 jsondata 값의 개별 키를 골라내는 대신, jsondata 문자열 전체를 그대로 이스케이프해 SP의 두 번째 인자(@lssn bigint)에 문자열 리터럴로 붙입니다(giipApiSk2 자동 jsondata 전달 로직, run.ps1 내부 주석 ISN 161). 그 리터럴이 71289처럼 숫자만이면 SQL Server가 nvarchar→bigint 암묵 변환에 성공하지만, {"lssn":71289}처럼 중괄호가 섞이면 변환할 수 없어 오류가 납니다.
- text=LsvrDetail lssn처럼 파라미터 이름을 명시하고 jsondata={"lssn":71289}로 보내는 방식이 이론상 더 안전할 수 있으나(값 이름 매칭 경로를 타므로) 실측 검증되지 않았습니다 — 확실히 동작하는 것은 위 raw-number 방식뿐입니다.

🚫 동작하지 않는 명령 (giip #1281)

아래 명령은 giipApiSk2 디스패처에 대응 SP가 존재하지 않아 동작하지 않습니다. UI를 이용해주세요.

명령	원인	대안
`LSVRList <CSN>`	`pApiLSVRListbySk` SP가 giipdb에 존재하지 않음	서버 목록 페이지를 이용해 주세요
`LSvrPut '<lsUsage>', <CSN>`	SK 기반 `pApiLSvrPutbySk` SP가 존재하지 않음 (AK 기반 `pApiLSvrPutbyAK`만 존재, giipApiSk2에서 호출 불가)	서버 목록 페이지를 이용해 주세요

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

상세 정보 조회 등 인프라 자산 관리의 핵심 작업 시, 작업의 정합성 확보와 상세한 감사 로그(Audit Log)를 위해 giipApiSk3 엔드포인트를 권장합니다.

엔드포인트: https://giipfaw.azurewebsites.net/api/giipApiSk3
장점: 상세 환경 정보(IP, UA)와 StackTrace를 즉시 기록하여 에이전트 연동 문제나 설정 오류를 신속하게 분석할 수 있습니다.

문제 해결

증상	원인	해결
`LsvrDetail` 조회 시 `Error converting data type nvarchar to bigint` 오류	`jsondata`를 `{"lssn":71289}`처럼 객체로 감쌈 — `text=LsvrDetail`에는 파라미터 이름이 없어 `jsondata` 전체가 문자열 그대로 `@lssn bigint` 인자에 대입됨	`jsondata`에 LSSN raw 숫자만 전달(예: `jsondata=71289`), 객체로 감싸지 말 것
`LsvrDetail` 조회 시 인증이 거부됨	POST 본문 `token` 필드 누락/오타 또는 비활성화(재발급/회전)된 SK 사용. `x-giip-ak`/`x-giip-sk`/`x-api-key` 등 헤더는 이 엔드포인트에서 전혀 사용되지 않으므로 헤더를 아무리 채워도 소용없습니다.	POST 본문의 `token` 필드에 유효한(현재 발급된) SK를 담았는지 확인합니다.
`LsvrDetail` 조회 결과가 없음	존재하지 않는 LSSN 사용	유효한 LSSN으로 다시 조회합니다.

버전: 1.5 최종 업데이트: 2026-08-20 소스 파일: giipv3/public/help/api-server.ko.md

v1.5 변경 이력 (2026-08-20, giip #1281): giipApiSk2 디스패처에 대응 SP가 존재하지 않는 LSVRList/LSvrPut 명령을 API 상세에서 제거하고, "동작하지 않는 명령" 표로 대안(UI)을 명시. LsvrDetail만 유일하게 동작하는 명령으로 남김. v1.4 변경 이력 (2026-08-20, giip #1277): 외부 사용자(smartorder-works, csn 70418) 실측 제보로 문서-구현 불일치를 발견해 정정.

관련 문서:

API 결과 코드 가이드 (RstVal)