SIEMENS PLC Web API 学习记录

为顺应时代发展，西门子为 S7-200SMART/1200/1500 PLC 添加IT通讯所需要的 Web API。（由于S7-200 SMART 新固件必须配合新的硬件才能使用，手头没有），打赏可获取文中测试源代码，部署自己电脑或PLC中测试相关API。

序号	PLC类型	固件开始支持版本	当前API 版本
1	S7-200 SMART	V2.7	未知
2	S7-1200	V4.5	V1.46
3	S7-1500	V2.8	V2.00

Web Api 概述

Web Api 是基于PLC Web Server 实现的，Web Server 是西门子PLC很早就开始支持的特性，提供基础数据查看，诊断、故障更新、变量监测、文件浏览下载等功能，并提供一套 AWP 语法实现自定义网页数据读写监控；从新版本开始支持 Web Api 功能，所谓Web Api就是通讯定义的接口和方法，直接获取PLC运行数据，而不需要登陆网页。具体可以干嘛？官方文档如下：

CPU 提供基于 Web 的 API (Web API) 作为读取和写入 CPU 数据的界面。Web API 可用于：
- 使用最新的先进技术实现 Web 应用程序
- 通过脚本和编程语言与 CPU 的 Web 服务器通信
- 创建可同时连接到多个 CPU 的 Web 应用程序，例如，创建可显示多个 CPU 状态的仪表板

具体包括读写PLC数据，远程监控PLC运行状态等等；

S7-1200/1500 所实现的 Web API 是一个标准的 JSON-RPC 规范的 API 特性，遵循 JSON-RPC 2.0 规范。API 基于 HTTP URL POST方法，即发送 POST 请求到 https://[ip]/api/jsonrpc，CPU 根据权限及请求方法回应相关数据或错误指示。Web API 支持 JSON-RPC 2.0 中定义的批量操作。

JSON-RPC API格式

{"id": $(in_request),"jsonrpc": "2.0","method": $(method), // 方法名称"params": $(params) // 方法对应的参数，如果不需要，可忽略
}
// 处理成功返回
{"id": $id_in_request,"jsonrpc": "2.0","result":"$(data)"
}// 处理失败返回
{"id": $id_in_request,"jsonrpc": "2.0","error":{"code": $(error),"message": $(error_message)}
}

已经测试的支持的客户端包括 Chrome，Firefox，Edge，Safari 等主流浏览器，Python，GNU Wget，cURL等工具及库。

Web Api 测试

测试 S7-1500 为 CPU 1511-1 PN , 固件版本 2.9.4，最新 V3.0 并没有更新1511。S7-1200 为 CPU 1215C AC/DC/Rl，固件版本 V4.5(V4.6和V4.5相同)。测试工具包括Edge 100+版本，PostMan，JavaScript等

通过实际测试，发现S7-1200/1500 的 Web Api 因为 CPU 计算能力及API版本不同而差异较大，S7-1200 Web Api 响应速度与 S7-1500 相比明显慢，且支持的 API 有限，差异后面会列出；

启用 Web Api 功能

控制器启用 Web Api 的Web Server 方法参见参考资料所附的官方资料，此处不再展开。

值得注意的是，Web Api 的读写权限是与 Web Server 里面配置的权限相关，默认用户名为 EveryBody，默认用户的权限需要配置；管理员权限可以读写PLC数据，读取PLC启停状态，控制PLC启停状态，获取PLC时间，下载文件等等；Api.Version / Api.Browse / Api.Ping 等几个指令是不需要传递权限的，随意调用。

Api.Version/Api.Browse

// api Version
{"id": 5,"jsonrpc": "2.0","method": "Api.Version"
}
// ---响应----
{"jsonrpc": "2.0","id": 5,"result": 1.46
}// api browse
{"id": 6,"jsonrpc": "2.0","method": "Api.Browse"
}//响应
{"jsonrpc": "2.0","id": 6,"result": [{"name": "Api.Browse"},{"name": "Api.GetCertificateUrl"},{"name": "Api.GetPermissions"},{"name": "Api.Login"},{"name": "Api.Logout"},{"name": "Api.Ping"},{"name": "Api.Version"},{"name": "PlcProgram.Browse"},{"name": "PlcProgram.Read"},{"name": "PlcProgram.Write"}]
}

通过 Edge F12 开发者工具，可以清晰看到通讯过程；

Request Head 类型必须是：Content type:application/json

Api.Login/Logout

登陆PLC用的方法并不是传统 Basic Auth 等方法，而是直接在Request_Body传递Json结构体，改变

{"method": "Api.Login", // 方法名称"params": {"user":"UserName", "password":"SecurePassword""include_web_application_cookie":true // V2.9+版本支持cookie功能}// Api.Login 需要参数必要参数包括"user"，"password"
}
响应会在 "result" 返回
{"token": "eG9mcHdhaGR0dWVsdm5teGFxcGw=", // 后续用的请求更多用的为token
"web_application_cookie":"Cb5xdhgiokr0dWVsdm5teGCncFb="
}

获取token后，需要在后续 Request Head 中包括'X-Auth-Token': "eG9mcHdhaGR0dWVsdm5teGFxcGw=" 字段，会实现认证权限的包含。

Web Server 认证有效期为 120s，如果120s内没有任何通讯，CPU 会注销事件结束会话。延长会话的方法，即定时发送 Api.Ping 可确保会话保持活动状态。

$.post({url:"https://192.168.2.132/api/jsonrpc",
headers:{'X-Auth-Token':"Sy8pe3VNv86rTMldzFBsYzmw12Lg"
},
data:JSON.stringify({"jsonrpc":"2.0", method:"Api.Ping", "id":1}),
//Api.Ping 不需要任何参数
});

PLC Web Api 核心为浏览、读、写变量

PlcProgram.Browse

通过 PlcProgram.Browse 方法，可以读取变量列表。要调用 PlcProgram.Browse 方法，需要“read_value”认证。PlcProgram.Browse 方法用到两个参数，有两种用法。

// method 1，返回所有子变量
{“mode”:"children","var":"VarName" // 如果 var 变量为空，则返回所有PLC可访问的变量表
}
// method 2 返回变量信息，包括变量地址、DB块、PLC内部数据类型等信息
{“mode”:"var","var":"VarName" // 如果 var 变量为空，则返回所有PLC可访问的变量表
}

PlcProgram.Read

使用 PlcProgram.Read 方法从 CPU 读取单个变量值，要调用 PlcProgram.Read 方法，需要“read_value”认证。PlcProgram.Read 方法用到两个参数mode,var，有两种用法。

// method 1，读取变量实际值
{“mode”:"simple", // 默认值，可不写"var":"VarName"
}
// method 2 读取变量原始值，原始值即为 由字节构成的数据底层数组
{“mode”:"raw","var":"VarName"
}
// 如
以下示例显示在“raw”表示中读取“dword”类型变量的结果。
[ 1, 47, 233, 0 ]

PlcProgram.Write

PlcProgram.Write 和Read 相似，只是参数中多一个value参数

// method 1，读取变量实际值
{“mode”:"simple", // 默认值，可不写"value": "VarValue","var":"VarName"
}
// method 2 读取变量原始值，原始值即为 由字节构成的数据底层数组
{“mode”:"raw","var":"VarName" ,"value": ["VarValue1", "VarValue2", "VarValue3"],
}
// 如
以下示例显示在“raw”表示中读取“dword”类型变量的结果。
[ 1, 47, 233, 0 ]

此处需要注意的是，变量名称的写法，传递给CPU的JSON中变量名称需要和博通调用名称一致，即该加引号需要加引号，如果徒手写json，则可能需要用到转义字符，类似于 "var": "\"MyDB\".MyVariable"。写入或返回的数值类型需要与CPU内部类型对应，支持绝大部分基础数据类型，对于结构体和UDT，建议使用批量调用模式获取，无法通过变量名一次性获取。

布尔 JSON 值必须为：true 或 false
整数注意数值范围
JSON 浮点数必须使用 parseFloat 格式化为浮点数
日期、时间等数值写入也必须满足TIA对数据格式的要求

Plc.ReadOperatingMode/Plc.ReadOperatingMode

使用 Plc.ReadOperatingMode 方法可以读取 CPU 的操作模式。要调用 Plc.ReadOperatingMode 方法，需要“read_diagnostics”认证。通过 Plc.RequestChangeOperatingMode 方法，为 CPU 请求新的操作模式。但这只是对工作模式的请求，必须在 CPU 上给出操作模式更改的条件，例如，通过模式选择器的相应位置。可使用 Plc.ReadOperatingMode 方法检查 CPU 上的工作模式更改是否成功。要调用 Plc.RequestChangeOperatingMode 方法，需要“change_operating_mode”认证。

ReadOperatingMode 方法无需参数，直接发送即可。

{"id": x,"jsonrpc": "2.0","method": "Plc.ReadOperatingMode"
}
// 结果返回
在result 中返回，STOP，STARTUP，RUN，HOLD，unknown等几种模式

写入请求

{"id": ,"jsonrpc": "2.0","method": "Plc.RequestChangeOperatingMode","params": {"mode": "stop" // run,stop}
}

批量方法，就是将上述请求Body合并；

[
{"jsonrpc":"2.0", "id":1, method:"PlcProgram.Read"},
{"jsonrpc":"2.0", "id":2, method:"PlcProgram.Read",
params:{"var":"\"MyDB\".InvalidField"}},
{"jsonrpc":"2.0", "id":3, method:"PlcProgram.Read",
params:{"var":"MyDB.MyDate"} },
{"jsonrpc":"2.0", "id":4, method:"PlcProgram.Write",
params:{"var":"\"BoilerControl\".TempSetPoint", value:9001} }
]

Web Api 列表

S7-1200 Api V1.46 提供功能如下：

Api.Browse
Api.GetCertificateUrl
Api.GetPermissions
Api.Login
Api.Logout
Api.Ping
Api.Version
PlcProgram.Browse
PlcProgram.Read
PlcProgram.Write

S7-1500 Api V2.00 提供Api 在上述基础上，还包括
— v2.9 固件新增 ----

用户可以加载的 Web 应用
Api.BrowseTickets
Api.CloseTicket
Plc.ReadOperatingMode
Plc.RequestChangeOperatingMode
票证机制
WebApp.Browse
WebApp.BrowseResources
WebApp.Create
WebApp.CreateResource
WebApp.Delete
WebApp.DeleteResource
WebApp.DownloadResource
WebApp.Rename
WebApp.RenameResource
WebApp.SetDefaultPage
WebApp.SetNotAuthorizedPage
WebApp.SetNotFoundPage
WebApp.SetResourceETag
WebApp.SetResourceMediaType
WebApp.SetResourceModificationTime
WebApp.SetResourceVisibility
WebApp.SetState
— V3.0 固件新增----
DataLogs.DownloadAndClear
Files.Browse
Files.Create
Files.CreateDirectory
Files.Delete
Files.DeleteDirectory
Files.Download
Files.Rename
Plc.CreateBackup
Plc.ReadSystemTime
Plc.ReadTimeSettings
Plc.RestoreBackup

参考资料

S7-200 Smart Web API 开发手册
SIMATIC S7-1500、SIMATIC 驱动控制器、ET 200SP、ET 200pro Web 服务器
WebserverApi Client Library for .NET
smart web api初体验西门子论坛大神贡献的Go版本