news 2026/2/25 10:01:31

openPLC REST API 参考(英译中）

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
openPLC REST API 参考(英译中）

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}

响应字段：

  • status- 当前构建状态（IDLE, UNZIPPING, COMPILING, SUCCESS, FAILED）
  • logs- 来自构建过程的日志消息数组
  • 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":"2024-01-01T12:00:00.000Z","level":"INFO","message":"PLC 启动成功"},{"id":2,"timestamp":"2024-01-01T12:00:05.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\-H"Content-Type: application/json"\-d'{"username":"admin","password":"admin123","role":"admin"}'# 步骤 2：登录并获取 JWT 令牌TOKEN=$(curl-k -X POST https://localhost:8443/api/login\-H"Content-Type: application/json"\-d'{"username":"admin","password":"admin123"}'\|jq -r'.access_token')echo"令牌:$TOKEN"# 步骤 3：使用令牌进行认证请求# 获取 PLC 状态curl-k https://localhost:8443/api/status\-H"Authorization: Bearer$TOKEN"# 启动 PLCcurl-k https://localhost:8443/api/start-plc\-H"Authorization: Bearer$TOKEN"# 停止 PLCcurl-k https://localhost:8443/api/stop-plc\-H"Authorization: Bearer$TOKEN"# 上传程序curl-k -X POST https://localhost:8443/api/upload-file\-H"Authorization: Bearer$TOKEN"\-F"file=@program.zip"# 获取编译状态curl-k https://localhost:8443/api/compilation-status\-H"Authorization: Bearer$TOKEN"# 获取运行时日志curl-k https://localhost:8443/api/runtime-logs\-H"Authorization: Bearer$TOKEN"# Ping 运行时curl-k https://localhost:8443/api/ping\-H"Authorization: Bearer$TOKEN"

注意：-k标志用于绕过自签名证书的验证。

Python 示例：

importrequestsimporturllib3importtime# 禁用自签名证书的 SSL 警告urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)base_url="https://localhost:8443/api"# 步骤 1：创建第一个用户（无需认证）response=requests.post(f"{base_url}/create-user",json={"username":"admin","password":"admin123","role":"admin"},verify=False)print(f"用户创建:{response.json()}")# 步骤 2：登录获取 JWT 令牌response=requests.post(f"{base_url}/login",json={"username":"admin","password":"admin123"},verify=False)token=response.json()["access_token"]print(f"接收到的令牌:{token[:50]}...")# 步骤 3：使用令牌进行认证请求headers={"Authorization":f"Bearer{token}"}# 获取 PLC 状态response=requests.get(f"{base_url}/status",headers=headers,verify=False)print(f"PLC 状态:{response.json()}")# 启动 PLCresponse=requests.get(f"{base_url}/start-plc",headers=headers,verify=False)print(f"启动 PLC:{response.json()}")# 上传程序withopen("program.zip","rb")asf:files={"file":f}response=requests.post(f"{base_url}/upload-file",files=files,headers=headers,verify=False)print(f"上传:{response.json()}")# 监视编译whileTrue:response=requests.get(f"{base_url}/compilation-status",headers=headers,verify=False)status=response.json()print(f"编译状态:{status['status']}")ifstatus["status"]in["SUCCESS","FAILED"]:print("编译日志:")forloginstatus["logs"]:print(f"{log}")breaktime.sleep(1)

JavaScript/Node.js 示例：

consthttps=require('https');constfetch=require('node-fetch');constFormData=require('form-data');constfs=require('fs');// 禁用自签名证书的 SSL 验证constagent=newhttps.Agent({rejectUnauthorized:false});constbaseUrl="https://localhost:8443/api";asyncfunctionmain(){// 步骤 1：创建第一个用户letresponse=awaitfetch(`${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 令牌response=awaitfetch(`${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,50)+'...');// 步骤 3：使用令牌进行认证请求constheaders={'Authorization':`Bearer${access_token}`};// 获取 PLC 状态response=awaitfetch(`${baseUrl}/status`,{headers,agent});console.log('PLC 状态:',awaitresponse.json());// 启动 PLCresponse=awaitfetch(`${baseUrl}/start-plc`,{headers,agent});console.log('启动 PLC:',awaitresponse.json());// 上传程序constformData=newFormData();formData.append('file',fs.createReadStream('program.zip'));response=awaitfetch(`${baseUrl}/upload-file`,{method:'POST',headers:{...headers},body:formData,agent});console.log('上传:',awaitresponse.json());// 监视编译while(true){response=awaitfetch(`${baseUrl}/compilation-status`,{headers,agent});conststatus=awaitresponse.json();console.log('编译状态:',status.status);if(status.status==='SUCCESS'||status.status==='FAILED'){console.log('编译日志:');status.logs.forEach(log=>console.log(' '+log));break;}awaitnewPromise(resolve=>setTimeout(resolve,1000));}}main();

速率限制

目前没有强制执行速率限制。但是，请注意：

  • 一次只能运行一个编译
  • 频繁的启动/停止命令可能会导致状态转换问题
  • 日志查询在大容量日志时可能占用大量资源

安全注意事项

  1. 仅限 HTTPS：所有通信必须使用 HTTPS（端口 8443）
  2. JWT 认证：除首次创建用户和登录外，所有端点都需要 JWT 认证
  3. 自签名证书：默认安装使用自签名证书（OpenPLC Editor 会自动处理）
  4. 文件上传验证：ZIP 文件在解压前会经过全面的安全检查
  5. 大小限制：文件大小受到限制以防止资源耗尽（10 MB 每文件，50 MB 总计）
  6. 路径验证：所有文件路径都经过验证以防止遍历攻击
  7. 密码安全：密码使用 PBKDF2-SHA256（600,000 次迭代）、盐值和胡椒值进行哈希处理

WebSocket 调试接口

对于实时调试和变量检查，OpenPLC Editor 使用位于https://<主机>:8443/api/debug的 WebSocket 接口。详情请参阅 调试协议。

相关文档

  • 编辑器集成 - OpenPLC Editor 如何使用此 API
  • 架构 - 系统概述
  • 调试协议 - WebSocket 调试接口
  • 编译流程 - 构建过程详情
  • 安全 - 安全特性
  • 故障排除 - 常见问题
版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/2/22 18:25:47

AI写论文新选择！这4款AI论文生成神器，解决写论文的燃眉之急！

还在为论文写作烦恼吗&#xff1f;面对大量的文献资料、繁杂的格式要求和频繁的修改&#xff0c;很多学术人士都感觉效率低下&#xff0c;倍感压力&#xff01;别担心&#xff0c;本文将推荐4款实测过的AI论文写作工具&#xff0c;帮助你从文献检索、论文大纲到语言润色&#x…

作者头像 李华
网站建设 2026/2/22 22:14:39

AI写论文必备！这4款AI论文写作工具，让你写职称论文不再愁！

四款实用AI论文写作工具推荐 在撰写期刊论文、毕业论文或职称论文的过程中&#xff0c;不少人可能感到无比烦恼。面对海量的参考文献&#xff0c;仿佛是在大海里捞针&#xff0c;文献的查找让人头疼不已。各种复杂的格式要求也让人倍感压力&#xff0c;反复修改的过程更是消耗…

作者头像 李华
网站建设 2026/2/25 4:07:10

计算机毕设java的校园一卡通管理系统的设计与实现 基于Java技术的高校一卡通管理系统开发与应用 Java环境下校园一卡通综合管理平台的设计与构建

计算机毕设java的校园一卡通管理系统的设计与实现8x2vv9 &#xff08;配套有源码 程序 mysql数据库 论文&#xff09; 本套源码可以在文本联xi,先看具体系统功能演示视频领取&#xff0c;可分享源码参考。随着信息技术的飞速发展&#xff0c;校园管理逐渐向智能化、便捷化方向迈…

作者头像 李华
网站建设 2026/2/22 18:13:25

AI写论文利器登场！4款AI论文生成软件，让你的学术创作快人一步！

在撰写期刊论文、毕业论文或职称论文的过程中&#xff0c;学术人员常常面临不少挑战。手动编写论文时&#xff0c;海量的文献资料仿佛像大海中的针&#xff0c;寻找相关的信息极为困难&#xff1b;格式要求的复杂程度也让人感到无从下手&#xff0c;令许多人忙得不可开交。而在…

作者头像 李华
网站建设 2026/2/24 8:37:41

Apollo 占据网格感知模型：从训练到部署的完整指南

Apollo 占据网格感知模型：从训练到部署的完整指南 引言：什么是占据网格？ 第一部分：为什么需要这份指南？（背景与初衷） 第二部分：核心概念与准备工作 2.1 关键术语 2.2 准备工作：驱动确认 第三部分：训练阶段详解 步骤 1: 获取训练环境与数据 步骤 2: 创建并运行容器 步…

作者头像 李华
网站建设 2026/2/7 18:57:16

在OpenHarmony上用React Native：自定义useHighlight关键词高亮

React Native for OpenHarmony 实战&#xff1a;自定义useHighlight关键词高亮 摘要 本文深入探讨在OpenHarmony 6.0.0平台上使用React Native 0.72.5实现自定义useHighlight关键词高亮功能的完整解决方案。文章从Hook设计原理出发&#xff0c;详细分析在OpenHarmony 6.0.0 (…

作者头像 李华