시스템 관리 API 레퍼런스

서버에 명령을 전달하거나 에이전트 상태를 제어하는 시스템 수준의 자동화 API를 안내합니다.

📋 개요

이 API 모듈은 GIIP 에이전트를 통해 개별 서버에 직접 명령을 내리거나, 서버의 메타데이터(태그 등)를 관리하기 위한 엔드포인트를 제공합니다.

🔐 인증 및 헤더

모든 요청은 공통 인증 헤더를 포함해야 합니다.

Header:
```
x-giip-ak: [Your Access Key]
```
Header:
```
x-giip-sk: [Your Secret Key]
```

🚀 주요 API 엔드포인트

1. 원격 명령 실행 (Run Remote Command)

URL:
```
POST /api/system/command/run
```
설명: 지정된 서버에서 특정 Shell 스크립트 또는 명령어를 실행합니다.
Request Body:

{
  "serverIsn": 456,
  "command": "ls -al /var/log",
  "timeout": 30
}

2. 에이전트 제어 (Agent Control)

URL:
```
POST /api/system/agent/control
```
설명: 서버에 설치된 GIIP 에이전트를 원격으로 재시작하거나 설정을 동기화합니다.
Request Body:

{
  "serverIsn": 456,
  "action": "restart"
}

3. 서버 태그 관리 (Manage Server Tags)

URL:
```
POST /api/system/server/tags
```
설명: 서버를 분류하기 위한 태그 목록을 업데이트합니다.
Request Body:

{
  "serverIsn": 456,
  "tags": ["Production", "Web", "Region-KR"]
}

🔍 응답 데이터 예시 (Command Run)

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "jobId": "JOB-10293",
    "output": "total 1024\ndrwxr-xr-x 2 root root ...",
    "exitCode": 0
  }
}

💡 활용 사례

자동 패치 관리: 취약점이 발견된 패키지에 대해 전체 서버에 일괄 업데이트 명령을 내립니다.
동적 자원 할당: 태그 관리 API를 사용하여 새롭게 생성된 VM의 용도를 자동으로 지정하고 정책을 적용합니다.

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

원격 명령 실행(

Run Remote Command

)이나 에이전트 제어와 같은 민감한 시스템 관리 작업 시, 조작의 무결성 보장과 상세한 실행 이력 추적을 위해

giipApiSk3

엔드포인트를 권장합니다.

엔드포인트:

https://giipfaw.azurewebsites.net/api/giipApiSk3

장점: 명령 실행 실패 시 호출자의 상세 환경 정보(IP, UA)와 StackTrace를 즉시 기록하여 비인가 요청이나 네트워크 장애 상황을 신속하고 명확하게 파악할 수 있도록 도와줍니다.
활용 팁:
```
jsondata
```
치환 기능을 사용하여 복잡한 Shell 명령어 문자열이나 특수문자가 포함된 태그 정보를 전송할 때 데이터 유실 없이 안전하게 관리할 수 있습니다.

🔧 문제 해결

증상	원인	해결
요청이 인증 오류로 거부됨	`x-giip-ak` / `x-giip-sk` 헤더가 누락되었거나 잘못된 키	유효한 Access Key와 Secret Key를 두 헤더에 모두 포함하여 재요청
원격 명령이 실행되지 않음	`serverIsn` 이 잘못되었거나 대상 서버의 에이전트가 오프라인	서버 식별자를 확인하고, 에이전트 제어 API( `action: restart` )로 에이전트를 재시작
응답의 `RstVal` 이 0이 아님	명령 실행 실패 또는 `timeout` 초과	`RstMsg` 와 `Data.exitCode` 를 확인하고, 필요 시 `timeout` 값을 상향 조정
특수문자가 포함된 태그 전송 시 데이터가 유실됨	`jsondata` 치환 기능 미사용	`giipApiSk3` 엔드포인트의 `jsondata` 필드로 전송하여 데이터 손실 방지

버전: 1.1 최종 업데이트: 2026-04-10 소스 파일:

giipv3/public/help/api-system.ko.md

관련 문서:

API 결과 코드 가이드 (RstVal)