시스템 관리 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)