news 2026/6/10 21:34:56

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/6/10 13:23:51

新手入门ClaudeBox：国内合规使用Claude，避坑指南+快速上手

&#x1f4cc; 前言 对于刚接触Claude系列工具的国内新手开发者来说&#xff0c;最头疼的不是工具本身的使用&#xff0c;而是“怎么合规接入”“环境怎么配”“遇到问题怎么解”。网上很多教程要么命令复杂&#xff0c;要么适配海外场景&#xff0c;国内开发者跟着操作很容易踩…

作者头像 李华
网站建设 2026/6/10 13:20:00

HoRain云--RESTful API 概念

&#x1f3ac; HoRain云小助手&#xff1a;个人主页 &#x1f525; 个人专栏: 《Linux 系列教程》《c语言教程》 ⛺️生活的理想&#xff0c;就是为了理想的生活! ⛳️ 推荐 前些天发现了一个超棒的服务器购买网站&#xff0c;性价比超高&#xff0c;大内存超划算&#xff01;…

作者头像 李华
网站建设 2026/6/10 13:24:52

与学习相关的技巧(正则化)

正则化 机器学习的问题中&#xff0c;过拟合是一个很常见的问题。过拟合指的是只能拟 合训练数据&#xff0c;但不能很好地拟合不包含在训练数据中的其他数据的状态。机 器学习的目标是提高泛化能力&#xff0c;即便是没有包含在训练数据里的未观测数据&#xff0c; 也希望模型…

作者头像 李华
网站建设 2026/6/10 13:26:23

AI写论文的秘密武器！4款AI论文生成工具，解决论文写作困扰！

在2025年的学术写作智能化浪潮中&#xff0c;越来越多的人开始依靠AI写论文工具。许多现有的工具在撰写硕士、博士论文等长篇学术作品时&#xff0c;往往面临着理论深度不足或逻辑结构松散的问题。普通的AI论文写作工具很难满足专业论文写作的需求。 尽管AI写论文的技术日益进…

作者头像 李华
网站建设 2026/6/10 13:20:04

AI写论文神器来袭！4款AI论文写作工具，让毕业论文不再难写！

学术论文写作难题的破解之道——AI论文写作工具推荐 在撰写期刊论文、毕业论文学位或者职称论文的过程中&#xff0c;许多学术人士常常面临各种挑战。手动撰写论文时&#xff0c;面对纷繁复杂的文献资料&#xff0c;寻找相关信息仿佛大海捞针&#xff1b;而严格的格式规范又让…

作者头像 李华
网站建设 2026/6/10 14:51:59

uniapp+nodejs小程序校园求职招聘系统

文章目录系统概述技术架构核心功能创新点应用场景系统设计与实现的思路主要技术与实现手段源码lw获取/同行可拿货,招校园代理 &#xff1a;文章底部获取博主联系方式&#xff01;系统概述 基于Uniapp和Node.js的校园求职招聘系统旨在为高校学生与企业提供便捷的求职招聘平台。…

作者头像 李华