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`）中为该账号签发 → 安全设置 · 安全管理

只要具备这三个值，用下面一个代码块即可完成首次调用。

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`	计数

⚠️ 不会抛出异常。 通信错误或服务器 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 服务 —— 创建首条主数据

快速开始（60 秒）​

1.1 添加依赖​

1.2 创建客户端​

构造函数参数​

1.3 首次 API 调用 —— ping 与站点列表​

1.4 try-with-resources 模式​

1.5 13 个服务一览​

1.6 V5 方法签名标准模式​

1.7 调试模式​

后续步骤​