1. はじめに

V5 Java API クライアントを使用して最初の呼び出しを送信するまでの手順を説明します。

クイックスタート (60秒)

必要なもの3つ

項目	値	取得場所
サーバーアドレス	http://<server-ip>:80 (TLS は https://<server-ip>:443)	REST API エンドポイント。:7443 は管理コンソール専用なので、API には 80/443 を使用してください
アカウント ID	例: api	API 呼び出し用ユーザーアカウント
トークン	UUID 形式	コンソールの セキュリティ管理 → API 認証トークン(/token/index) でそのアカウント向けに発行 → セキュリティ設定 · セキュリティ管理

この3つの値があれば、以下の1ブロックで最初の呼び出しが行えます。

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", "<issued-token>", 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 サービス — 最初のマスターデータ作成