openplc runtime REST API 参考( 英--＞中)

openplc runtime REST API 参考( 英—>中)

概述

OpenPLC Runtime v4 提供了一个内部 REST API，通过 HTTPS 协议提供服务，供 OpenPLC Editor 桌面应用程序使用。该 API 并非设计为供最终用户直接交互，但可用于高级集成或诊断。

所有端点均可通过https://<主机>:8443/api/<端点>地址访问。

基础 URL

https://localhost:8443/api

认证

运行时使用基于 JWT 的认证：

1. 首次创建用户：POST /api/create-user（创建第一个用户无需认证）
2. 登录：POST /api/login返回 JWT 访问令牌
3. 认证请求：所有其他端点都需要Authorization: Bearer <令牌>请求头

注意：OpenPLC Editor 会自动处理认证。高级集成者必须手动实现认证流程。

通用响应格式

所有 API 响应均为 JSON 对象。成功响应通常包含一个status字段，而错误响应则包含描述性的错误消息。

认证端点

创建用户

创建新的用户账户。第一个用户可以在没有认证的情况下创建。后续创建用户需要 JWT 认证。

请求：

POST /api/create-user Content-Type: application/json { "username": "admin", "password": "your_password", "role": "admin" }

响应（成功）：

{"msg":"用户已创建","id":1}

响应（错误）：

{"msg":"用户名已存在"}

状态码：

• 201 Created- 用户创建成功
• 400 Bad Request- 缺少用户名或密码
• 401 Unauthorized- 用户已存在且未提供有效的 JWT
• 409 Conflict- 用户名已存在

登录

进行身份验证并获取 JWT 访问令牌。

请求：

POST /api/login Content-Type: application/json { "username": "admin", "password": "your_password" }

响应（成功）：

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

响应（错误）：

"用户名或密码错误"

状态码：

• 200 OK- 登录成功
• 401 Unauthorized- 凭据无效
• 500 Internal Server Error- 数据库错误

注意事项：

• 访问令牌应包含在所有后续请求的Authorization: Bearer <令牌>请求头中
• 令牌在配置的持续时间（默认：24 小时）后过期

PLC 控制端点

所有 PLC 控制端点都需要 JWT 认证。

启动 PLC

启动 PLC 程序执行。

请求：

GET /api/start-plc Authorization: Bearer <令牌>

响应：

{"status":"PLC 启动成功"}

可能的 Status 值：

• "PLC 启动成功"- PLC 已切换到 RUNNING 状态
• "PLC 已在运行"- PLC 已处于 RUNNING 状态
• "未加载 PLC 程序"- 没有可用的已编译程序
• "运行时无响应"- 运行时进程无响应

停止 PLC

停止 PLC 程序执行。

请求：

GET /api/stop-plc Authorization: Bearer <令牌>

响应：

{"status":"PLC 停止成功"}

可能的 Status 值：

• "PLC 停止成功"- PLC 已切换到 STOPPED 状态
• "PLC 已停止"- PLC 已处于 STOPPED 状态
• "运行时无响应"- 运行时进程无响应

获取 PLC 状态

查询当前的 PLC 状态。

请求：

GET /api/status Authorization: Bearer <令牌>

响应：

{"status":"RUNNING"}

可能的 Status 值：

• "EMPTY"- 未加载 PLC 程序
• "INIT"- 程序已加载，正在初始化
• "RUNNING"- 正在主动执行扫描周期
• "STOPPED"- 程序已加载但未执行
• "ERROR"- 可恢复的错误状态
• "运行时无响应"- 运行时进程无响应

运行时 Ping

检查运行时进程是否响应。

请求：

GET /api/ping Authorization: Bearer <令牌>

响应：

{"status":"pong"}

可能的 Status 值：

• "pong"- 运行时进程响应正常
• null- 运行时进程无响应

程序管理端点

上传 PLC 程序

上传一个包含由 OpenPLC Editor v4 生成的 PLC 程序源文件的 ZIP 文件。

请求：

POST /api/upload-file Authorization: Bearer <令牌> Content-Type: multipart/form-data file: <ZIP 文件>

成功响应：

{"UploadFileFail":"","CompilationStatus":"COMPILING"}

错误响应：

{"UploadFileFail":"错误消息","CompilationStatus":"FAILED"}

编译状态值：

• "IDLE"- 无构建进行中
• "UNZIPPING"- 正在解压 ZIP 文件
• "COMPILING"- 正在运行编译脚本
• "SUCCESS"- 构建成功完成
• "FAILED"- 构建失败

错误条件：

• 请求中没有文件
• 文件过大（>10 MB 每文件，>50 MB 总计）
• ZIP 验证失败（路径遍历、压缩率、不允许的扩展名）
• 另一个编译正在进行中
• 文件系统错误

注意事项：

• 编译在后台线程中异步运行
• 使用/api/compilation-status端点来监视进度
• PLC 在编译期间会自动停止
• OpenPLC Editor 在本地编译程序（JSON → XML → ST → C），并将源文件作为 ZIP 上传

获取编译状态

查询最近一次编译的状态。

请求：

GET /api/compilation-status Authorization: Bearer <令牌>

响应：

{"status":"SUCCESS","logs":["[INFO] 开始编译","[INFO] 正在编译 Config0.c...","[INFO] 正在编译 Res0.c...","[INFO] 正在编译 debug.c...","[INFO] 正在编译 glueVars.c...","[INFO] 正在编译 c_blocks_code.cpp...","[INFO] 正在编译共享库...","[INFO] 构建成功完成"],"exit_code":0