跳到主要内容

API 使用手册

本文是 PlantPulse Java API 客户端库(plantpulse-api)的完整使用手册。通过 13 个领域服务,可访问站点、资产、标签、报警、工单等平台的全部主数据/运营数据。

库的特点​

  • 标准 REST — 按语义使用 GET/POST/PUT/PATCH/DELETE 方法
  • 类型化 DTO — 所有请求与响应自动映射为 *RequestV5 / *ResponseV5 类(无需手动解析 JSONObject)
  • 按选项卡 PATCH — 支持 Tag 的报警、元数据、计算、聚合等 10 种局部修改
  • 13 个领域服务 — system、site、customer、employee、product、asset、opc、tag、alarm、order、calendar、path、flow
  • 安全的默认值 — 失败时返回 null 或空列表(不抛出异常)

本手册面向谁? 这是一份面向使用 Java 与 PlantPulse 平台对接的外部系统(MES、ERP、自建看板等)开发者的完整参考文档。

快速浏览​

领域说明
初次使用请按 1. 快速开始 → 2. 领域 ID 规则 → 3. 响应格式与错误处理 的顺序阅读。
需要特定领域可从下方目录直接跳转到相应服务(如 Tag、Order)。
直接调用 REST端点完整列表中整理了 URL 与方法的映射关系。
需要工作流示例请查看综合示例集中的端到端场景。

核心概念​

  • 入口点: new APIClient_V5(proto, host, port, user, token, debug) → connect()
  • 13 个服务: client.system()、client.site()、client.customer()、client.employee()、client.product()、client.asset()、client.opc()、client.tag()、client.alarm()、client.order()、client.calendar()、client.path()、client.flow()
  • 返回类型化 DTO: 所有方法均返回类型类(SiteResponseV5、TagResponseV5 等)而非 JSONObject
  • 失败时的安全默认值: create/update/get → null、list → 空列表、delete/exists → false、count → 0
  • 错误响应提取: BaseServiceV5.getErrorCode(env)、getErrorMessage(env)、getHttpStatus(env) 静态方法
  • 领域 ID 校验: 强制 SITE_、ASSET_、OPC_/API_、TAG_ 前缀(服务端校验器)
  • 基础路径: 所有调用均为 /api/v5 下的端点

手册目录​

入门与基本规则​

  1. 快速开始 — 创建客户端与连接
  2. 领域 ID 规则 ⭐ 请务必先阅读
  3. 响应格式与错误处理

基础设施 · 模型领域​

  1. System 服务 — 健康检查
  2. Site 服务 — 站点(工厂)主数据
  3. OPC 服务 — 数据采集通道
  4. Asset 服务 — 资产层级(Area·Line·Equipment)
  5. Tag 服务 — 标签定义 + 10 种 PATCH
  6. Path 服务 — 资产路径查询

运营领域​

  1. Alarm 服务 — 报警事件查询
  2. Calendar 服务 — 日程(巡检、停机等)
  3. Order 服务 — 工单 + 生命周期

主数据​

  1. Customer 服务 — 客户
  2. Employee 服务 — 员工
  3. Product 服务 — 产品

自动化​

  1. Flow 服务 — Flow / Flow Node 查询

附录​

  1. 端点完整列表 — URL 映射
  2. 综合示例集 — 端到端工作流

咨询:webmaster@kopens.com