核心内容摘要
密挑影视91精彩推荐：深夜灵魂的避风港，解锁前所未有的视听盛宴
REST API 参考概述OpenPLC Runtime v4 提供了一个内部 REST API通过 HTTPS 协议提供服务供 OpenPLC Editor 桌面应用程序使用。
该 API 并非设计为供最终用户直接交互但可用于高级集成或诊断。
所有端点均可通过https://主机:8443/api/端点地址访问。
基础 URLhttps://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:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ
..}响应错误用户名或密码错误状态码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] 正在编译 Config
c...,[INFO] 正在编译 Res
c...,[INFO] 正在编译 debug.c...,[INFO] 正在编译 glueVars.c...,[INFO] 正在编译 c_blocks_code.cpp...,[INFO] 正在编译共享库...,[INFO] 构建成功完成],exit_code:0}响应字段status- 当前构建状态IDLE, UNZIPPING, COMPILING, SUCCESS, FAILEDlogs- 来自构建过程的日志消息数组exit_code- 编译脚本的退出代码0 成功非零 错误null 进行中
注意事项OpenPLC Editor 轮询此端点以监视编译进度日志在编译期间累积错误消息以[ERROR]为前缀退出代码在编译完成前为null获取运行时日志从 PLC 运行时进程检索日志。
请求GET /api/runtime-logs GET /api/runtime-logs?id最小_ID GET /api/runtime-logs?level日志等级 Authorization: Bearer 令牌查询参数id(可选) - 要检索的最小日志 ID用于分页level(可选) - 按日志等级过滤DEBUG, INFO, WARNING, ERROR响应{runtime-logs:[{id:1,timestamp:
T12:00:
0
000Z,level:INFO,message:PLC 启动成功},{id:2,timestamp:
T12:00:
0
000Z,level:DEBUG,message:扫描计数: 100}]}日志等级DEBUG- 详细的诊断信息INFO- 一般信息性消息WARNING- 警告消息ERROR- 错误消息错误处理HTTP 状态码200 OK- 请求成功201 Created- 资源创建成功400 Bad Request- 请求参数无效401 Unauthorized- 需要认证或令牌无效409 Conflict- 资源冲突例如用户名已存在500 Internal Server Error- 服务器错误错误响应格式{error:错误消息描述}或对于某些端点{msg:错误消息描述}使用示例完整的认证流程cURL 示例# 步骤 1创建第一个用户curl-k -X POST https://localhost:8443/api/create-user\-HContent-Type: application/json\-d{username:admin,password:admin123,role:admin}# 步骤 2登录并获取 JWT 令牌TOKEN$(curl-k -X POST https://localhost:8443/api/login\-HContent-Type: application/json\-d{username:admin,password:admin123}\|jq -r.access_token)echo令牌:$TOKEN# 步骤 3使用令牌进行认证请求# 获取 PLC 状态curl-k https://localhost:8443/api/status\-HAuthorization: Bearer$TOKEN# 启动 PLCcurl-k https://localhost:8443/api/start-plc\-HAuthorization: Bearer$TOKEN# 停止 PLCcurl-k https://localhost:8443/api/stop-plc\-HAuthorization: Bearer$TOKEN# 上传程序curl-k -X POST https://localhost:8443/api/upload-file\-HAuthorization: Bearer$TOKEN\-Ffileprogram.zip# 获取编译状态curl-k https://localhost:8443/api/compilation-status\-HAuthorization: Bearer$TOKEN# 获取运行时日志curl-k https://localhost:8443/api/runtime-logs\-HAuthorization: Bearer$TOKEN# Ping 运行时curl-k https://localhost:8443/api/ping\-HAuthorization: Bearer$TOKEN注意-k标志用于绕过自签名证书的验证。
Python 示例importrequestsimporturllib3importtime# 禁用自签名证书的 SSL 警告urllib
disable_warnings(urllib
exceptions.InsecureRequestWarning)base_urlhttps://localhost:8443/api# 步骤 1创建第一个用户无需认证responserequests.post(f{base_url}/create-user,json{username:admin,password:admin123,role:admin},verifyFalse)print(f用户创建:{response.json()})# 步骤 2登录获取 JWT 令牌responserequests.post(f{base_url}/login,json{username:admin,password:admin123},verifyFalse)tokenresponse.json()[access_token]print(f接收到的令牌:{token[:50]}...)# 步骤 3使用令牌进行认证请求headers{Authorization:fBearer{token}}# 获取 PLC 状态responserequests.get(f{base_url}/status,headersheaders,verifyFalse)print(fPLC 状态:{response.json()})# 启动 PLCresponserequests.get(f{base_url}/start-plc,headersheaders,verifyFalse)print(f启动 PLC:{response.json()})# 上传程序withopen(program.zip,rb)asf:files{file:f}responserequests.post(f{base_url}/upload-file,filesfiles,headersheaders,verifyFalse)print(f上传:{response.json()})# 监视编译whileTrue:responserequests.get(f{base_url}/compilation-status,headersheaders,verifyFalse)statusresponse.json()print(f编译状态:{status[status]})ifstatus[status]in[SUCCESS,FAILED]:print(编译日志:)forloginstatus[logs]:print(f{log})breaktime.sleep(
JavaScript/Node.js 示例consthttpsrequire(https);constfetchrequire(node-fetch);constFormDatarequire(form-data);constfsrequire(fs);// 禁用自签名证书的 SSL 验证constagentnewhttps.Agent({rejectUnauthorized:false});constbaseUrlhttps://localhost:8443/api;asyncfunctionmain(){// 步骤 1创建第一个用户letresponseawaitfetch(${baseUrl}/create-user,{method:POST,headers:{Content-Type:application/json},body:JSON.stringify({username:admin,password:admin123,role:admin}),agent});console.log(用户创建:,awaitresponse.json());// 步骤 2登录获取 JWT 令牌responseawaitfetch(${baseUrl}/login,{method:POST,headers:{Content-Type:application/json},body:JSON.stringify({username:admin,password:admin123}),agent});const{access_token}awaitresponse.json();console.log(接收到的令牌:,access_token.substring(0,
...);// 步骤 3使用令牌进行认证请求constheaders{Authorization:Bearer${access_token}};// 获取 PLC 状态responseawaitfetch(${baseUrl}/status,{headers,agent});console.log(PLC 状态:,awaitresponse.json());// 启动 PLCresponseawaitfetch(${baseUrl}/start-plc,{headers,agent});console.log(启动 PLC:,awaitresponse.json());// 上传程序constformDatanewFormData();formData.append(file,fs.createReadStream(program.zip));responseawaitfetch(${baseUrl}/upload-file,{method:POST,headers:{...headers},body:formData,agent});console.log(上传:,awaitresponse.json());// 监视编译while(true){responseawaitfetch(${baseUrl}/compilation-status,{headers,agent});conststatusawaitresponse.json();console.log(编译状态:,status.status);if(status.statusSUCCESS||status.statusFAILED){console.log(编译日志:);status.logs.forEach(logconsole.log( log));break;}awaitnewPromise(resolvesetTimeout(resolve,
);}}main();速率限制目前没有强制执行速率限制。
但是请注意一次只能运行一个编译频繁的启动/停止命令可能会导致状态转换问题日志查询在大容量日志时可能占用大量资源安全
注意事项仅限 HTTPS所有通信必须使用 HTTPS端口 8443JWT 认证除首次创建用户和登录外所有端点都需要 JWT 认证自签名证书默认安装使用自签名证书OpenPLC Editor 会自动处理文件上传验证ZIP 文件在解压前会经过全面的安全检查大小限制文件大小受到限制以防止资源耗尽10 MB 每文件50 MB 总计路径验证所有文件路径都经过验证以防止遍历攻击密码安全密码使用 PBKDF2-SHA256600,000 次迭代、盐值和胡椒值进行哈希处理WebSocket 调试接口对于实时调试和变量检查OpenPLC Editor 使用位于https://主机:8443/api/debug的 WebSocket 接口。
详情请参阅 调试协议。
相关文档编辑器集成 - OpenPLC Editor 如何使用此 API架构 - 系统概述调试协议 - WebSocket 调试接口编译流程 - 构建过程详情安全 - 安全特性故障排除 -