跳到主要内容

17. 端点完整列表

这是 PlantPulse API 的 REST 端点与客户端方法的映射。基础路径为 /api/v5。

认证：调用 APIClient_V5.connect() 时会自动发行和管理 api_key，因此没有用户需要直接调用的认证端点。

17.1 System​

HTTP端点方法
GET/api/v5/pingclient.system().ping()

17.2 ID 发行​

方法路径说明
POST/api/v5/domain-ids预先获取域 ID（无客户端方法） — ID 规则

17.3 Site (6个)​

HTTP端点方法
POST/api/v5/siteclient.site().create(req)
PUT/api/v5/site/{id}client.site().update(id, req)
DELETE/api/v5/site/{id}client.site().delete(id)
GET/api/v5/site/{id}client.site().get(id)
GET/api/v5/siteclient.site().list()
GET/api/v5/site/{id}/existsclient.site().exists(id)

17.4 OPC (10个)​

HTTP端点方法
POST/api/v5/opcclient.opc().create(req)
PUT/api/v5/opc/{id}client.opc().update(id, req)
DELETE/api/v5/opc/{id}client.opc().delete(id)
GET/api/v5/opc/{id}client.opc().get(id)
GET/api/v5/opcclient.opc().list()
GET/api/v5/opc?site_id={id}client.opc().listBySite(siteId)
GET/api/v5/opc?opc_source_type={type}client.opc().listByType(sourceType)
GET/api/v5/opc/{id}/existsclient.opc().exists(id)
GET/api/v5/opc/countclient.opc().count()
GET/api/v5/opc/count?site_id={id}client.opc().countBySite(siteId)

17.5 Asset (6个)​

HTTP端点方法
POST/api/v5/assetclient.asset().create(req)
PUT/api/v5/asset/{id}client.asset().update(id, req)
DELETE/api/v5/asset/{id}client.asset().delete(id)
GET/api/v5/asset/{id}client.asset().get(id)
GET/api/v5/assetclient.asset().list()
GET/api/v5/asset/{id}/existsclient.asset().exists(id)

关系本体 (4个)​

这是与层级（父-子）不同的方向性关系。用于回答「如果该设备停止，影响范围到哪里」之类的问题。

HTTP端点功能
POST/api/v5/assets/{asset_id}/relations注册关系 — 正文 {site_id, to_entity_type, to_entity_id, relation_type, description?} → 201
GET/api/v5/assets/{asset_id}/relations?type=直接关系列表（入站 · 出站）
DELETE/api/v5/relations/{relation_id}删除关系 → 204
GET/api/v5/ontology/graph/{entity_id}?relation=&direction=DOWN&depth=2图遍历 (BFS)
关系含义方向
FEEDS工艺流程资产 → 资产
DEPENDS_ON公用设施依赖（电力 · 空气 · 冷却）资产 → 资产
PRODUCES生产产出资产 → 产品
  • direction 为 UP · DOWN · BOTH（默认 DOWN），depth 为 1~5（默认 2）。
  • 不存储指向自身的循环关系，相同组合的关系仅注册一次。
  • 注册和删除属于变更操作，适用 ADMIN/API 角色及审计记录。
  • AI 助手调用相同遍历功能的 MCP 端点为 trace_asset_relations。

QR 标签​

HTTP端点功能
GET/api/v5/asset/qr/{token}标签令牌对应的设备。若非令牌或为已重新发行的旧令牌，则返回 404

标签中包含的地址是 GET /api/v5/asset/{id} 响应中的 qr_payload。此调用不创建令牌，因此若尚无令牌或无 PP_UI_CONSOLE_URL，则返回 ""。无需登录的公开页面不属于 V5，而是 /qr/{token} — QR 标签与公开页面。

17.6 Tag (23个)​

CRUD + 列表​

HTTP端点方法
POST/api/v5/tagclient.tag().create(req)
PUT/api/v5/tag/{id}client.tag().update(id, req)
DELETE/api/v5/tag/{id}client.tag().delete(id)
GET/api/v5/tag/{id}client.tag().get(id)
GET/api/v5/tag/{id}/existsclient.tag().exists(id)
GET/api/v5/tagclient.tag().list()
GET/api/v5/tag?site_id={id}client.tag().listBySite(siteId)
GET/api/v5/tag?opc_id={id}client.tag().listByOpc(opcId)
GET/api/v5/tag?asset_id={id}client.tag().listByAsset(assetId)
GET/api/v5/tag/countclient.tag().count()
GET/api/v5/tag/count?site_id={id}client.tag().countBySite(siteId)
GET/api/v5/tag/count?opc_id={id}client.tag().countByOpc(opcId)
GET/api/v5/tag/count?asset_id={id}client.tag().countByAsset(assetId)

PATCH (10个 — 按页签部分修改)​

HTTP端点方法
PATCH/api/v5/tag/{id}/basicpatchBasic(id, req)
PATCH/api/v5/tag/{id}/alarmpatchAlarm(id, req)
PATCH/api/v5/tag/{id}/metadatapatchMetadata(id, req)
PATCH/api/v5/tag/{id}/calculationpatchCalculation(id, req)
PATCH/api/v5/tag/{id}/samplingpatchSampling(id, req)
PATCH/api/v5/tag/{id}/aggregationpatchAggregation(id, req)
PATCH/api/v5/tag/{id}/aipatchAi(id, req)
PATCH/api/v5/tag/{id}/publishpatchPublish(id, req)
PATCH/api/v5/tag/{id}/attributepatchAttribute(id, req)
PATCH/api/v5/tag/{id}/linkpatchLink(id, req)

17.7 Alarm (3个)​

HTTP端点方法
GET/api/v5/alarm/{seq}client.alarm().get(seq)
GET/api/v5/alarm?limit={n}client.alarm().list(limit)
GET/api/v5/alarm/performance?scope_type=&scope_id=报警系统性能（无客户端方法）

/alarm/performance — scope_type 为 SITE · AREA · LINE，scope_id 为 Site ID 或 Asset ID，两者均为必填。期间可通过 days（1~31，默认 7）或 from + to（两者同时提供，最高 31 天）指定，且 from/to 优先级高于 days。仅统计报警发生数，在隐藏或抑制期间开启的报警单独出现在 suppression 中。范围或期间错误时返回 400。相同数值由 MCP get_alarm_performance 返回。

17.8 Order (11个)​

HTTP端点方法
POST/api/v5/orderclient.order().create(req)
PUT/api/v5/order/{id}client.order().update(id, req)
DELETE/api/v5/order/{id}client.order().delete(id)
GET/api/v5/order/{id}client.order().get(id)
GET/api/v5/orderclient.order().list()
GET/api/v5/order/{id}/existsclient.order().exists(id)
POST/api/v5/order/{id}/startclient.order().start(id)
POST/api/v5/order/{id}/endclient.order().end(id)
POST/api/v5/order/{id}/pauseclient.order().pause(id)
POST/api/v5/order/{id}/resumeclient.order().resume(id)
POST/api/v5/order/{id}/abortclient.order().abort(id)

17.8.1 维护工单​

用于设备维护的调用、修理、预防性维护工作（ISA-95 维护工作单）。该对象与生产工作单（/order）不同，无客户端方法，通过 REST 访问。

HTTP端点功能
GET/api/v5/maintenance-orders列表。过滤：scope+scope_id(asset · line · area · site) · status_code · open · maintenance_kind_code · assignee_employee_id · failure_mode_code · maintainable_item_code · from/to · period_of · overdue · external_system · external_id。分页：page · limit (默认 50, 最大 500) · sort · order
GET/api/v5/asset/{asset_id}/maintenance-orders单个设备的列表
POST/api/v5/asset/{asset_id}/maintenance-orders添加维护调用
GET/api/v5/maintenance-orders/{maintenance_order_id}单条记录
PATCH/api/v5/maintenance-orders/{maintenance_order_id}修改内容
POST/api/v5/maintenance-orders/{maintenance_order_id}/transition状态迁移（接收 · 开始 · 完成 · 取消）。正文 status_code · version，取消则需 cancel_reason_code
GET/api/v5/maintenance-orders/{maintenance_order_id}/revisions判定历史
GET/api/v5/maintenance-orders/summary范围和期间内的维护摘要
GET/api/v5/maintenance-orders/options可选的种类 · 状态 · 代码
GET/api/v5/maintenance-orders/board范围内的维护仪表板
GET/api/v5/maintenance-orders/changes用于 CMMS 同步的变更 Feed (Cursor)
GET · PUT/api/v5/maintenance-orders/by-external/{system}/{external_id}通过外部 (CMMS) 编号查找 · 幂等写入
GET · PUT/api/v5/maintenance-orders/by-external?system=&external_id=同上。编号中包含 / 时使用
POST · GET/api/v5/maintenance-orders/{maintenance_order_id}/attachments上传照片 · 列表
GET/api/v5/maintenance-orders/{maintenance_order_id}/attachments/{maintenance_attachment_seq}/content照片详情

维护工单字段​

字段名称在响应正文、请求正文和列表查询中保持一致。

字段类型含义
maintenance_order_id字符串MAINTENANCE_ORDER_000001。旧行为数字字符串 ("12")
maintenance_kind_code字符串维护种类 (CORRECTIVE …)
status_code字符串状态 (REQUESTED · ACCEPTED · IN_PROGRESS · COMPLETED · CANCELLED)
cancel_reason_code字符串取消原因
failure_record_seq数字关联的故障记录
maintenance_plan_id · maintenance_plan_name字符串预防性维护计划。MAINTENANCE_PLAN_000001 或旧数字字符串
failure_mode_code · failure_mechanism_code · failure_cause_code · maintainable_item_code字符串ISO 14224 代码。显示名称用 _name 代替 _code
cause_code字符串原因字典代码（与报警共用字典）
checklist_results[].maintenance_attachment_seq数字巡检项照片

CMMS Webhook​

在配置键 PP_MAINTENANCE_WEBHOOK_URL 中填入地址，每当维护工单状态变更时，将通过 JSON 进行一次 POST 发送（调用 · 接收 · 开始 · 完成 · 取消）。仅修改内容时不发送，留空则关闭。失败时将开启诊断 diagnostic.maintenance.webhook_failed，并在下次成功时关闭，且不会重新发送。

键值
text安装语言的单行句子
eventmaintenance.requested · maintenance.accepted · maintenance.in_progress · maintenance.completed · maintenance.cancelled
maintenance_order_id维护工单 ID (字符串)
asset_id · asset_name设备
maintenance_kind_code · status_code种类 · 状态
description · failure_mode_code说明 · 故障模式
requested_by · accepted_by · assignee_employee_id人员
cancel_reason_code取消原因
external_system · external_id · owner外部编号与所有者
anomaly_found · checklist_results巡检异常与否及其回答 (item_id · checked · value · maintenance_attachment_seq · out_of_range)
maintenance_plan_id · plan_due_at预防性维护计划
at · version状态变更时刻 (epoch ms) · 判定

未知值的键也会以 null 形式完整包含在内。

17.9 Calendar (6个)​

HTTP端点方法
POST/api/v5/calendarclient.calendar().create(req)
PUT/api/v5/calendar/{id}client.calendar().update(id, req)
DELETE/api/v5/calendar/{id}client.calendar().delete(id)
GET/api/v5/calendar/{id}client.calendar().get(id)
GET/api/v5/calendarclient.calendar().list()
GET/api/v5/calendar/search?from={iso}&to={iso}client.calendar().search(from, to)

17.10 Customer (8个)​

HTTP端点方法
POST/api/v5/customerclient.customer().create(req)
PUT/api/v5/customer/{id}client.customer().update(id, req)
DELETE/api/v5/customer/{id}client.customer().delete(id)
GET/api/v5/customer/{id}client.customer().get(id)
GET/api/v5/customerclient.customer().list()
GET/api/v5/customer?site_id={id}client.customer().listBySite(siteId)
GET/api/v5/customer/{id}/existsclient.customer().exists(id)
GET/api/v5/customer/countclient.customer().count()

17.11 Employee (7个)​

HTTP端点方法
POST/api/v5/employeeclient.employee().create(req)
PUT/api/v5/employee/{id}client.employee().update(id, req)
DELETE/api/v5/employee/{id}client.employee().delete(id)
GET/api/v5/employee/{id}client.employee().get(id)
GET/api/v5/employeeclient.employee().list()
GET/api/v5/employee/{id}/existsclient.employee().exists(id)
GET/api/v5/employee/countclient.employee().count()

17.12 Product (7个)​

HTTP端点方法
POST/api/v5/productclient.product().create(req)
PUT/api/v5/product/{id}client.product().update(id, req)
DELETE/api/v5/product/{id}client.product().delete(id)
GET/api/v5/product/{id}client.product().get(id)
GET/api/v5/productclient.product().list()
GET/api/v5/product/{id}/existsclient.product().exists(id)
GET/api/v5/product/countclient.product().count()

17.13 Path (2个)​

HTTP端点方法
GET/api/v5/path/asset/{id}client.path().getByAsset(assetId)
GET/api/v5/path/tag/{id}client.path().getByTag(tagId)

17.14 Flow (3个)​

HTTP端点方法
GET/api/v5/flow/{id}client.flow().get(flowId)
GET/api/v5/flowclient.flow().list()
GET/api/v5/flow/{id}/nodeclient.flow().listNodes(flowId)

17.15 统计​

以下数值仅计算具有 plantpulse-api 客户端方法的路径。

域端点数量
System1
Site6
OPC10
Asset6
Tag23 (CRUD 5 + 列表 7 + 计数 4 + PATCH 10)
Alarm2
Order11 (CRUD 6 + 生命周期 5)
Calendar6
Customer8
Employee7
Product7
Path2
Flow3
总计92 (+认证 1)

17.16 HTTP 方法分布​

HTTP数量用途
GET56查询 (单条/列表/存在与否/计数)
POST16注册 + Order 生命周期
PUT10全量修改
PATCH10Tag 按页签部分修改
DELETE10删除

17.17 读取列表至末尾 — 游标 (Cursor)​

GET /api/v5/site · /product · /customer · /employee 使用游标进行连续读取。页大小 limit 默认为 100，上限 1000（超过则截断为 1000），首次调用时不包含 cursor。

curl -H "X-API-Key: $TOKEN" "$BASE/api/v5/site?limit=500"
curl -H "X-API-Key: $TOKEN" "$BASE/api/v5/site?limit=500&cursor=<next_cursor>"
{
  "data": [ ],
  "meta": {
    "status": "OK",
    "pagination": { "limit": 500, "total": 1234 },
    "cursor": { "next_cursor": "…", "has_more": true, "limit": 500 }
  },
  "errors": null
}
  • data 为本页的行数组。
  • meta.pagination.total 为该过滤条件的总记录数。
  • 在 meta.cursor.has_more 变为 false 之前，将 next_cursor 原样传递至下次调用的 cursor。
  • 游标与特定的列表和过滤条件绑定。若将其用于其他列表或更改了 site_id 的调用，将返回 422 E1002。
  • 客户 · 产品 · 员工按 ID 排序，Site 按名称 · ID 排序。读取期间即使行发生修改，也不会被遗漏。

Java 客户端的 list() 由于不传递 cursor，因此仅返回第一页。如需读取全部，请使用 REST 接口。

17.18 仅在变更时接收 — /tag/export 的 ETag​

GET /api/v5/tag/export 可一次性导出 Site · 连接 · 整个工厂的所有标签。通过 site_id · opc_id 过滤，若指定 include=config 则每行包含配置（无需为每个标签单独请求配置）。响应格式为 data = {tags: [...], count: N}。

保存响应中的 ETag，并在下次读取时将其作为 If-None-Match 返回。

curl -i -H "X-API-Key: $TOKEN" "$BASE/api/v5/tag/export?site_id=SITE_000001&include=config"
# ETag: "<SHA-256>"

curl -i -H "X-API-Key: $TOKEN" -H 'If-None-Match: "<SHA-256>"' \
  "$BASE/api/v5/tag/export?site_id=SITE_000001&include=config"
# 304 Not Modified — 본문 없음
  • ETag 为导出内容的 data SHA-256 值。只要可见内容发生变更（如标签或配置更改、标签添加/删除、连接迁移至其他 Site），无论由谁变更，该值均会变化。未变更时，即使重启或在不同节点读取，值也保持一致。
  • 同样支持代理附加的弱形式 W/"…" 和 *。
  • 304 仅节省传输和解析开销，并不节省读取开销。 服务器仍需读取所有行以计算数值。请勿以高于数据需要周期的频率调用。

KOPENS All rights reserved.