패널 API로 외부에서 서버를 조작하기

이 페이지에서 할 수 있는 것

게임 패널의 API(클라이언트 API)를 사용하면 다음과 같은 작업을 외부 프로그램이나 스크립트에서 자동화하실 수 있습니다.

• 접속 중인 플레이어 목록 조회
• 전체 공지 전송
• 플레이어 킥·차단
• 수동 저장
• 서버 시작·정지·재시작
• 가동 상태(CPU·메모리·디스크·통신량) 조회

API는 게임 종류와 관계없이 이용하실 수 있습니다. 게임별 명령어는 각 게임의 문서를 참조해 주세요.

API 키 발급

1. 게임 패널에 로그인하신 뒤, 화면 우측 상단의 계정 메뉴에서 「API Credentials(API 자격 증명)」을 엽니다.
2. 용도를 알 수 있는 설명을 입력하고 생성합니다.
3. 표시된 키를 따로 보관합니다.

API 키는 계정당 최대 25개까지 만드실 수 있습니다. 용도별로 나누어 만들고, 필요 없어진 키는 삭제해 주세요.

기본 사용법

기본 URL은 다음과 같습니다.

https://gsv.bestnetllc.co.jp/api/client

요청에는 다음 헤더를 함께 보냅니다.

Authorization: Bearer <API 키>
Accept: application/json
Content-Type: application/json   ← POST의 경우

서버 식별자는 패널에서 서버를 열었을 때의 URL https://gsv.bestnetllc.co.jp/server/xxxxxxxx의 마지막 8자입니다.

주요 엔드포인트

명령을 전송하는 예:

curl -X POST "https://gsv.bestnetllc.co.jp/api/client/servers/xxxxxxxx/command" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"command":"Info"}'

명령 실행 결과 받기

실행 결과를 읽으시려면 콘솔(WebSocket)에 접속합니다.

1. GET /api/client/servers/{id}/websocket을 호출하면 접속 URL(socket)과 token이 반환됩니다.
2. 해당 socket에 WebSocket으로 접속합니다.
3. 접속 후 먼저 {"event":"auth","args":["<token>"]}을 전송합니다. {"event":"auth success"}가 오면 인증 완료입니다.
4. 이후 {"event":"console output","args":["..."]} 형태로 콘솔 출력이 전달됩니다.
5. 같은 연결에서 {"event":"send command","args":["..."]}를 보내실 수도 있습니다.

접속 대상은 패널 도메인이 아니라 서버가 가동 중인 노드의 호스트명(포트 8443)입니다. 정상적인 동작입니다.

제한 및 주의사항

• 요청 제한은 1분당 256회입니다. 계정 단위이므로 발신 IP를 변경해도 완화되지 않습니다.
• 서버가 정지된 상태에서 명령을 보내면 오류가 반환됩니다(Server must be online in order to send commands.).
• command가 비어 있으면 입력 오류(422)가 됩니다.
• 보내신 명령은 패널의 활동 로그에 기록됩니다.
• 서브 사용자가 이용하시는 경우 「콘솔 조작」 권한이 필요합니다.

보안에 대하여

• API 키는 비밀번호와 동일하게 취급해 주세요. GitHub·Discord·스크린샷 등에 포함하지 마십시오.
• 「Allowed IPs(허용 IP)」를 설정해 주세요.
• 용도별로 키를 나누고, 필요 없어지면 삭제해 주세요. 만일 유출되더라도 삭제하면 즉시 무효가 됩니다.
• 권한이 없는 서버에는 접근하실 수 없습니다.