HTTP REST API

Name: Darra Software PLC
Author: Darra

Darra PLC 内置 HTTP REST API 服务, 提供 25+ 个端点, 支持 CORS 跨域访问, 适用于移动端监控和第三方系统集成。

服务配置

参数	默认值	说明
端口	8080	HTTP 监听端口
CORS	允许所有来源	可配置白名单
认证	Bearer Token	可选启用
最大并发	100	最大同时连接数

API 端点总览

#	方法	端点	说明
1	GET	`/api/system/info`	系统信息
2	GET	`/api/system/status`	运行状态
3	GET	`/api/plc/status`	PLC 状态 (运行/停止/错误)
4	POST	`/api/plc/start`	启动 PLC 程序
5	POST	`/api/plc/stop`	停止 PLC 程序
6	GET	`/api/variables`	获取变量列表
7	GET	`/api/variables/{name}`	读取单个变量
8	PUT	`/api/variables/{name}`	写入单个变量
9	POST	`/api/variables/batch`	批量读取变量
10	GET	`/api/io/state`	IO 状态概览
11	GET	`/api/io/{module}`	指定模块 IO 状态
12	GET	`/api/robot/status`	机器人状态
13	GET	`/api/robot/joints`	关节角度
14	GET	`/api/alarms`	报警列表
15	POST	`/api/alarms/acknowledge`	确认报警
16	GET	`/api/trend/{variable}`	趋势数据查询
17	GET	`/api/diagnostics`	诊断信息

请求/响应示例

获取系统信息

GET /api/system/info HTTP/1.1
Host: 192.168.1.100:8080

{
  "success": true,
  "data": {
    "productName": "Darra Software PLC",
    "version": "2.1.0",
    "serialNumber": "DPLC-2026-001",
    "uptime": 86400,
    "cpuUsage": 12.5,
    "memoryUsage": 45.8
  }
}

读取 PLC 变量

GET /api/variables/MD100 HTTP/1.1
Host: 192.168.1.100:8080
Authorization: Bearer eyJhbGciOi...

{
  "success": true,
  "data": {
    "name": "MD100",
    "value": 85.3,
    "type": "REAL",
    "quality": "Good",
    "timestamp": "2026-04-07T10:30:00.000Z"
  }
}

写入 PLC 变量

PUT /api/variables/MW500 HTTP/1.1
Host: 192.168.1.100:8080
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...

{
  "value": 1500
}

{
  "success": true,
  "message": "变量 MW500 写入成功"
}

批量读取变量

POST /api/variables/batch HTTP/1.1
Content-Type: application/json

{
  "variables": ["MD100", "MD104", "MW200", "MX0.0"]
}

{
  "success": true,
  "data": [
    { "name": "MD100", "value": 85.3, "type": "REAL", "quality": "Good" },
    { "name": "MD104", "value": 2.41, "type": "REAL", "quality": "Good" },
    { "name": "MW200", "value": 1500, "type": "INT", "quality": "Good" },
    { "name": "MX0.0", "value": true, "type": "BOOL", "quality": "Good" }
  ]
}

获取报警列表

GET /api/alarms?active=true&severity=high HTTP/1.1

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "message": "伺服驱动器过载",
      "severity": "High",
      "source": "Axis1",
      "timestamp": "2026-04-07T10:25:00.000Z",
      "acknowledged": false
    }
  ],
  "total": 1
}

查询趋势数据

GET /api/trend/MD100?from=2026-04-07T00:00:00Z&to=2026-04-07T12:00:00Z&interval=60 HTTP/1.1

{
  "success": true,
  "data": {
    "variable": "MD100",
    "points": [
      { "t": "2026-04-07T00:00:00Z", "v": 82.1 },
      { "t": "2026-04-07T00:01:00Z", "v": 82.4 },
      { "t": "2026-04-07T00:02:00Z", "v": 83.0 }
    ]
  }
}

CORS 配置

{
  "httpApi": {
    "port": 8080,
    "cors": {
      "allowedOrigins": ["*"],
      "allowedMethods": ["GET", "POST", "PUT", "DELETE"],
      "allowedHeaders": ["Content-Type", "Authorization"],
      "maxAge": 3600
    }
  }
}

Web HMI 集成

HTTP REST API 非常适合构建 Web 端 HMI。结合前端框架 (Vue/React) 可快速实现跨平台监控界面。轮询间隔建议不低于 500ms。

安全建议

生产环境建议:

启用 Bearer Token 认证
限制 CORS 允许来源为具体域名
对写入操作进行权限验证
使用 HTTPS (反向代理)

PLC 作为 HTTP 客户端

除了作为 Server, PLC 程序也可以用 FB 主动调用外部 HTTP 服务 (MES / ERP / Webhook):

VAR
    Http : HTTP_REQUEST;
END_VAR

Http(
    Method := 'POST',
    Url := 'https://mes.example.com/api/production',
    ContentType := 'application/json',
    Body := '{"station":"01","qty":12580,"ts":"2026-04-17T10:00:00Z"}',
    Auth := 'Bearer ' + ApiToken,
    Timeout := T#10s,
    Execute := TRUE
);

IF Http.Done THEN
    // Http.StatusCode = 200
    // Http.ResponseBody = '{"id":12345,"ok":true}'
ELSIF Http.Error THEN
    // Http.ErrorMessage
END_IF

支持的 FB

FB	用途
HTTP_REQUEST	通用 HTTP 请求
HTTP_GET	GET 简化版
HTTP_POST	POST 简化版
HTTP_DOWNLOAD	下载大文件到本地
HTTP_UPLOAD	上传本地文件 (multipart)
HTTP_WEBHOOK	Webhook 触发, 异步无需等响应

认证机制

机制	Header	说明
无	-	公开 API
Basic	`Authorization: Basic base64(user:pass)`	简单, 需 HTTPS
Bearer	`Authorization: Bearer <token>`	OAuth / JWT
API Key	`X-Api-Key: <key>`	固定密钥
HMAC	自定义 Header 含签名	最高安全

Bearer Token 支持自动刷新:

{
  "auth": {
    "type": "oauth2",
    "tokenUrl": "https://auth.example.com/token",
    "clientId": "plc_001",
    "clientSecret": "***",
    "refreshBefore": 300
  }
}

Token 过期前 300 秒自动刷新。

WebSocket 支持

除了 REST, 还支持 WebSocket 双向通讯:

// PLC Service 打开 WebSocket 服务
server.StartWebSocket(path: "/ws", port: 8080);

// 客户端连接后, PLC 推送变量变化
await ws.SendAsync(new {
    type = "update",
    variable = "MD100",
    value = 85.3,
    timestamp = DateTime.UtcNow
});

适合前端实时仪表盘, 替代高频轮询。

SSE (Server-Sent Events)

简化版 WebSocket, 只服务器推, 基于 HTTP 长连接:

GET /api/variables/subscribe?names=MD100,MD104 HTTP/1.1
Accept: text/event-stream

data: {"MD100": 85.3, "MD104": 2.41}

data: {"MD100": 85.5, "MD104": 2.42}

event: alarm
data: {"id":1001,"msg":"Overheat"}

浏览器 EventSource API 原生支持, 比 WebSocket 简单, 但只能服务器发客户端。

Rate Limiting

为防止误用拖垮 PLC, API 可限速:

策略	配置
每 IP 限速	100 请求/分钟
每 Token 限速	1000 请求/分钟
全局限速	10000 请求/分钟
写操作限速	100 写/分钟 (独立计)

超限返回 429 Too Many Requests, 响应头 Retry-After: 30。

API 版本管理

主要两种方式:

URL 版本 (推荐)

/api/v1/variables/MD100    ← 稳定版 v1
/api/v2/variables/MD100    ← 新特性 v2

GET /api/variables/MD100
Accept: application/vnd.darra.v2+json

默认走 v1, 旧客户端无感升级。

响应格式统一约定

所有成功响应:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-04-17T10:00:00.000Z"
}

所有失败响应:

{
  "success": false,
  "error": {
    "code": "VARIABLE_NOT_FOUND",
    "message": "变量 MD99999 不存在",
    "details": { "variable": "MD99999" }
  },
  "timestamp": "2026-04-17T10:00:00.000Z"
}

HTTP 状态码语义化:

200 OK — 成功
201 Created — 资源创建
400 Bad Request — 参数错
401 Unauthorized — 未认证
403 Forbidden — 认证通过但无权限
404 Not Found — 资源不存在
409 Conflict — 状态冲突 (如写入只读变量)
422 Unprocessable — 语义错误
429 Too Many Requests — 限速
500 Internal Server Error — 服务器错
503 Service Unavailable — 服务停止

OpenAPI 规范

服务启动后暴露自描述接口:

GET /openapi.json        — OpenAPI 3.0 JSON
GET /api-docs             — Swagger UI (浏览器查看)

方便前端自动生成 SDK, 或用 Postman 一键导入。

Webhook 触发

PLC 事件驱动外部系统:

项目树 → 通讯 → Webhook → 新建

配置:

触发源: 变量变化 / 报警 / 定时
目标 URL: POST 到哪里
请求模板: JSON 模板, 支持 {{variable.MD100}} 占位
重试策略: 指数退避 5 次
队列: 断线暂存

典型用途:

报警通知钉钉/企微
生产完成写 MES
异常事件推送到监控平台

反向代理建议

生产环境前面建议加反代 (Nginx / Caddy):

location /api/ {
    proxy_pass http://localhost:8080/api/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Real-IP $remote_addr;
    
    # TLS 终结 + 压缩
    gzip on;
    gzip_types application/json;
}

好处: TLS 证书管理、压缩、限速、缓存、ACL 集中。

排错

症状	处理
404	路径拼写, 确认版本
401	Token 过期
403	角色权限不足
429	降低调用频率
CORS 错	后端 `Access-Control-Allow-Origin` 未设
跨域预检 OPTIONS 返 405	需要允许 OPTIONS 方法
Webhook 不触发	检查触发条件 + 目标 URL 可达

服务配置​

API 端点总览​

请求/响应示例​

获取系统信息​

读取 PLC 变量​

写入 PLC 变量​

批量读取变量​

获取报警列表​

查询趋势数据​

CORS 配置​

PLC 作为 HTTP 客户端​

支持的 FB​

认证机制​

WebSocket 支持​

SSE (Server-Sent Events)​

Rate Limiting​

API 版本管理​

URL 版本 (推荐)​

Header 版本​

响应格式统一约定​

OpenAPI 规范​

Webhook 触发​

反向代理建议​

排错​