)
openplc runtime REST API 参考( 英—>中)
概述
OpenPLC Runtime v4 提供了一个内部 REST API，通过 HTTPS 协议提供服务，供 OpenPLC Editor 桌面应用程序使用。该 API 并非设计为供最终用户直接交互，但可用于高级集成或诊断。
所有端点均可通过https://<主机>:8443/api/<端点>地址访问。
基础 URL
https://localhost:8443/api认证
运行时使用基于 JWT 的认证：
- 首次创建用户：
POST /api/create-user（创建第一个用户无需认证） - 登录：
POST /api/login返回 JWT 访问令牌 - 认证请求：所有其他端点都需要
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- 用户已存在且未提供有效的 JWT409 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
