1. 시작하기

V5 Java API 클라이언트를 사용해 첫 호출까지 보내는 단계를 안내합니다.

빠른 시작 (60초)

필요한 것 3가지

항목	값	어디서
서버 주소	http://<서버IP>:80 (TLS 는 https://<서버IP>:443)	REST API 엔드포인트. :7443 은 관리 콘솔 전용이니 API 에는 80/443 을 쓰세요
계정 ID	예: api	API 호출용 사용자 계정
토큰	UUID 형식	콘솔 보안 관리 → API 인증 토큰(/token/index) 에서 그 계정으로 발급 → 보안 설정 · 보안 관리

세 값만 있으면 아래 한 블록으로 첫 호출이 됩니다.

import java.util.List;
import plantpulse.api.v5.APIClient_V5;
import plantpulse.api.v5.dto.response.SiteResponseV5;

try (APIClient_V5 client = new APIClient_V5(
        "HTTP", "100.68.69.41", 80, "api", "<발급받은-토큰>", false)) {
    client.connect();                                       // 인증
    System.out.println(client.system().ping().isPing());    // → true
    for (SiteResponseV5 s : client.site().list())           // 사이트 목록
        System.out.println(s.getSite_id() + " — " + s.getSite_name());
}

이 블록이 true 와 사이트 목록을 출력하면 준비 완료입니다. 아래 1.1~1.7 에서 각 단계를 자세히 설명합니다.

1.1 의존성 추가

JAR 파일을 클래스패스에 추가하시면 됩니다.

# 빌드 (Gradle + Java 21)
cd plantpulse-api
./gradlew build

산출물은 target/ 에 생성됩니다.

파일	용도
target/plantpulse-api.jar	기존 프로젝트에 의존성과 함께 통합할 때

1.2 클라이언트 생성

APIClient_V5 생성자에 옵션을 직접 전달합니다.

import plantpulse.api.v5.APIClient_V5;

APIClient_V5 client = new APIClient_V5(
        "HTTPS",                                       // 프로토콜: "HTTP" 또는 "HTTPS"
        "100.68.69.41",                                // host
        443,                                           // port (REST API: 80=HTTP, 443=HTTPS)
        "api",                                         // user_id
        "19ba7a54-1132-49f2-967e-3c6f5cd989a0",        // token (api_key 발급용)
        false);                                        // debug

client.connect();          // 인증 + HTTP 클라이언트 초기화

// ... API 호출 ...

client.close();            // 종료

생성자 파라미터

파라미터	타입	설명
protocol	String	"HTTP" 또는 "HTTPS"
host	String	서버 호스트 또는 IP
port	int	서버 포트
user_id	String	인증 계정 ID
token	String	발급된 토큰 (UUID 형식)
debug	boolean	HTTP 요청·응답 디버그 로그

인증 흐름: connect() 호출 시 내부에서 user_id + token 으로 api_key를 발급받고, 이후 모든 호출에서 그 키를 자동으로 헤더에 포함시킵니다. 사용자가 직접 다룰 필요는 없습니다.

1.3 첫 API 호출 — ping & 사이트 목록

import java.util.List;
import plantpulse.api.v5.APIClient_V5;
import plantpulse.api.v5.dto.response.SiteResponseV5;
import plantpulse.api.v5.dto.response.SystemPingResponseV5;

public class FirstCall {
    public static void main(String[] args) throws Exception {

        try (APIClient_V5 client = new APIClient_V5(
                "HTTP", "100.68.69.41", 80, "api",
                "19ba7a54-1132-49f2-967e-3c6f5cd989a0", false)) {

            client.connect();

            // 1) 서버 헬스체크
            SystemPingResponseV5 ping = client.system().ping();
            System.out.println("Server alive: " + ping.isPing()
                + " (v" + ping.getVersion() + ")");

            // 2) 사이트 목록 (typed DTO 리스트)
            List<SiteResponseV5> sites = client.site().list();
            for (SiteResponseV5 s : sites) {
                System.out.println(s.getSite_id() + " — " + s.getSite_name());
            }
        }
    }
}

실행 결과:

Server alive: true (v5.0)
SITE_00001 — 대전 1공장
SITE_00002 — 천안 2공장

1.4 try-with-resources 패턴

APIClient_V5는 AutoCloseable을 구현합니다. try-with-resources 사용을 권장합니다.

try (APIClient_V5 client = new APIClient_V5(proto, host, port, user, token, false)) {
    client.connect();
    // ... API 호출 ...
}
// close() 자동 호출 — HTTP 커넥션 정리

1.5 서비스 13개 한눈에 보기

connect() 직후 아래 서비스 메서드로 모든 도메인에 접근할 수 있습니다 (lazy 초기화).

client.system()    // 헬스체크
client.site()      // 사이트(공장)
client.customer()  // 고객
client.employee()  // 직원
client.product()   // 제품
client.asset()     // 자산 계층 (Area → Line → Equipment)
client.opc()       // OPC 데이터 채널
client.tag()       // 태그(데이터 포인트)
client.alarm()     // 알람
client.order()     // 작업지시
client.calendar()  // 일정
client.path()      // 자산 경로
client.flow()      // Flow / Flow Node

1.6 V5 메서드 시그니처 표준 패턴

모든 도메인 서비스는 일관된 메서드 패턴을 따릅니다. 도메인 이름만 다를 뿐 사용법은 동일합니다.

패턴	반환 타입	실패 시 반환값	설명
create(req)	*ResponseV5	null	등록
update(id, req)	*ResponseV5	null	전체 수정
delete(id)	boolean	false	삭제
get(id)	*ResponseV5	null	단건 조회
list()	List<*ResponseV5>	빈 리스트	전체 목록
exists(id)	boolean	false	존재 여부
count()	long	0	카운트

⚠️ 예외가 throw 되지 않습니다. 통신 오류나 서버 ERROR 응답은 위 표의 안전 기본값으로 반환됩니다. 에러 원인은 로그 또는 BaseServiceV5.getErrorCode(env) 로 확인하세요. 상세 내용은 응답 형식 및 에러 처리 참고.

1.7 디버그 모드

생성자 마지막 인자를 true 로 주면 HTTP 요청·응답이 콘솔에 출력됩니다.

APIClient_V5 client = new APIClient_V5(
        "HTTP", "100.68.69.41", 80, "api", TOKEN, true);  // debug=true

출력 예:

[V5] GET https://server/api/v5/site headers={api_key=ab****cd}
[V5] response: 200 {"_status":"OK","data":[{"site_id":"SITE_00001",...}]}

다음 단계

• 도메인 ID 규칙 — 반드시 다음에 읽어주세요. ID 접두사 검증이 강제됩니다.
• 응답 형식 및 에러 처리 — 에러 코드 매핑과 안전한 처리 패턴
• Site 서비스 — 첫 마스터 데이터 생성