使用WinCC的REST API访问PLC数据
1 REST介绍
1.1 什么是REST
REST 是REpresentational State Transfer的缩写，通过 REST 通信，能够使用常规的 HTTP 方法和 JSON ，访问运行系统数据和组态数据，还可以将运行系统数据以变量值的形式发送到云端。
外部应用程序可以通过 REST 接口读取和写入 WinCC 组态数据和变量值。访问变量时不支持 原始数据变量 和 文本参考 两种数据类型。
1.2 REST订货号
| Title | Order number DVD |
Order number download |
Order number DVD |
Order number download |
| 8.0 | 8.0 | 8.1 | 8.1 | |
| WinCC/ConnectivityPack 需要RT授权 | 6AV6371-1DR08-0AX0 | 6AV6371-1HR08-0AX0 | 6AV6371-1DR08-0AX0 | 6AV6371-1HR08-0AX0 |
| WinCC/ConnectivityStation 不需要RT授权 | 6AV6371-1DR18-0AX0 | 6AV6371-1HR18-0AX0 | 6AV6371-1DR18-0AX0 | 6AV6371-1HR18-0AX0 |
| WinCC/Cloud Connect | 6AV6362-5AA08-0BB0 | 6AV6362-5AA08-0AH0 | 6AV6362-5AA08-0BB0 | 6AV6362-5AA08-0AH0 |
| WinCC/Rest Connect | 6AV6362-6AA08-0BB0 | 6AV6362-6AA08-0AH0 | 6AV6362-6AA08-0BB0 | 6AV6362-6AA08-0AH0 |
1.2.1 WinCC Connectivity Pack
该许可证将涵盖所有与连接相关的功能:
OPC 服务器、OPC UA服务器、WinCC OLE-DB、REST, CloudConnector, Tag Collaboration with Unified
1.2.2 Rest Connect
该许可证仅包含REST功能(REST-API、REST Connector)，其费用约为Connectivity Pack 许可证费用的一半
REST 接口提供了访问 RT 数据的接口：
读取过程标签、写入过程标签、警报、记录
1.2.3 REST-API
该功能指WinCC作为服务端，允许其他应用程序和系统向WinCC发送 REST请求，以读取变量管理的组态数据，或读/写变量运行值+归档变量(组态/值)
1.2.4 REST Connector
该功能指WinCC作为客户端，主动从WinCC向其他应用程序和系统发送REST请求
通过变量或报警触发 REST方法的发送
内置的json组态编辑器可以帮助创建包含运行数据和报警消息内容的请求包
2 通过REST访问WinCC实时数据(V7.5开始支持)
2.1 启用REST
在WinCC的计算机上点击右键，打开属性界面
- 点击“启动”选项卡
- 勾选“REST服务”
- 点击“REST 设置”
- 勾选通过REST发送变量值
- 修改主机名称（如果通过IP访问，可以将这里修改为IP地址）
- 点击”端口证书“选择证书
创建端口证书
生成自签名证书（管理员身份运行 PowerShell）
|
1 |
New-SelfSignedCertificate -DnsName "localhost", "127.0.0.1" -CertStoreLocation "cert:\LocalMachine\My" -KeyUsage DigitalSignature, KeyEncipherment -Type SSLServerAuthentication -NotAfter (Get-Date).AddYears(1) |
绑定证书到端口（替换 <Thumbprint> 为实际值）
|
1 |
netsh http add sslcert ipport=0.0.0.0:34568 certhash=<Thumbprint> appid="{00000000-0000-0000-0000-000000000000}" certstorename=MY |
选择新增的证书
2.2 设置用户权限
进入“用户管理器”
- 选取“用户管理器”
- 点击“权限等级”选项卡
- 创建两个权限，分别对应读取和写入
- 点击“Administrator”或者新创建一个用户，该用户为REST-API外部访问用户
- 设置用户密码
- 勾选访问权限
2.3 设置变量权限
- 进入“变量管理”窗口，选择需要读写的变量
- 修改REST API的权限
2.4 测试API
2.4.1 HTTP 方法
| 方法 | 说明 |
|---|---|
| GET | 从服务器读取资源。
用于从 WinCC 项目中读取运行系统值和组态数据。 |
| POST | 从服务器读取资源。
寻址 Body 中的资源。 用于发送多个值。 |
| PUT | 写访问
通过 URL 寻址资源。 用于将单个 WinCC |
2.4.2 读取所有变量的运行系统值
调用
- GET / POST
URL
- https://<Host>:<Port>/WinCCRestService/tagManagement/Values
Body:
|
1 2 3 4 5 |
{ "variableNames" : [ "Tag name 1", "Tag name 2", "Tag name 3", "Tag name 4" ] } |
2.4.3 将值写入到多个变量
调用
- PUT
URL
- https://<Host>:<Port>/WinCCRestService/TagManagement/Values
Body：
|
1 2 3 4 5 6 7 8 9 10 11 |
[ {"variableName":"Tag name 1","value":true}, {"variableName":"Tag name 2","value":6}, {"variableName":"Tag name 3","value":8}, {"variableName":"Tag name 4","value":10} ] |
2.4.4 其他方法
PUT：支持的请求
GET / POST：支持的请求
- 读取一个变量的运行系统值
- 读取所有变量的运行系统值
- 读取一个连接的组态数据
- 读取所有连接的组态数据
- 读取一个变量的组态数据
- 读取所有变量的组态数据
- 读取一个变量组的组态数据
- 读取所有变量组的组态数据
- 读取一个结构类型的组态数据
- 读取所有结构类型的组态数据
- 读取一个结构类型的实例
- 读取多个结构类型的实例
2.5 报错处理
2.5.1 错误代码
| 响应代码 | 说明 | 注释 |
|---|---|---|
| 200 | OK | WinCC API 已成功处理请求。 |
| 400 | Bad Request | 请求无效 |
| 401 | Unauthorized | 无访问权限 |
| 402 | Payment Required | 未找到有效的 WinCC 许可证 |
| 404 | Not Found | 未找到资源
URL 与 WinCC API 的资源类型不匹配。 请更正 URL 的格式。 |
| 416 | RangeNotSatisfiable | 请求无效
URL 结构不正确。无法满足请求的范围。 原因包括，在调用“GET”时缺少所寻址资源的名称。 |
| 423 | Locked | 资源被锁定。
原因包括，当前正在读取寻址的数据。 等待一段时间后再次发送请求。 |
| 500 | InternalError | 内部错误
服务器报告意外错误。 |
| 501 | NotImplemented | 请求无效
服务器不支持请求的功能。 |
2.5.2 报错 401
Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
在测试环境下可以在postman的Setting中关闭SSL证书验证功能
在认证页面，选择Basic Auth，输入用户名和密码
2.5.3 返回数据报错Forbidden
需要给变量设置权限参照2.3。
2.5.4 返回值报错"errorcode":-1073446906
变量未连接到PLC，无法写入数据报错。
2.5.5 404 Not Found
The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
检查PUT/GET是否选择正确，检查链接是否正确。
2.6 实现REST Connector功能
设置IT连接器
- 点击“IT连接器”选项卡
- 在“REST服务器“上点击右键
- 选择”新REST服务器“，这里的服务器是指推送给对方的地址，按对方实际地址进行修改。
- 在新建的服务器上右键
- 选择“新端点”
- 选择“端点”
- 在变量触发器中，选择变量名称，右边的“…”
- 在弹出的“变量选择”对话框中选择变量
- “确定”关闭对话框
- 切换到“占位符”标签页
- 根据需要填写占位符
- 并关联变量
- 切换到“JSON主体”标签页
- 根据需要填写名称
- 选择数据类型
- 选择”占位符“
- 点击服务器
- 查看发送数据发生了变化
3 通过REST访问WinCC归档组态和数据(V8.0开始支持)
3.1 访问归档组态
如果归档配置如下
可通过以下API获取到组态状态
调用
- GET / POST
URL
- https://<Host>:<Port>/WinCCRestService/TagLogging/Archive/<ArchiveName>/Variables
3.2 读取归档数据
3.2.1 设置归档变量权限
- 点击要访问的归档
- 选择过程变量
- 设置“REST-API”的读授权
3.2.2 读取数据
调用
- GET / POST
URL
- https://<Host>:<Port>/WinCCRestService/TagLogging/Archive/<ArchiveName>/Value/<ValueName>
在不加任何过滤条件的情况下，默认返回最近的1000条历史数据。
3.2.3 过滤条件
3.3 报错处理
3.3.1 “errorcode":16
{"archive":"Archive1","variableName":"DB_1_ST2","unit":"","errorcode":16,"values":[],"namespace":""}
检查计算机“属性”中，“启动”选项卡，“变量记录运行系统”是否已勾选。
3.3.2 “errorcode":8
{"archive":"Archive1","variableName":"DB_1_ST2","unit":"","errorcode":8,"values":[],"namespace":""}
指定的时间范围内没有数据，注意时间是UTC的，中国时间范围是+8，查询的时候要-8。
4 附录
4.1 基本URL和端点
4.1.1 变量管理方法
基本 URL
https://<Host>:<Port>/WinCCRestService/tagManagement/
端点
Connection/<ConnectionName>
读取一个连接的组态数据
Connections
读取所有连接的组态数据
Group/<GroupName>
读取一个变量组的组态数据
Groups
读取所有变量组的组态数据
StructureType/<StructureName>
读取一个结构类型的组态数据
StructureTypes
读取所有结构类型的组态数据
StructureTag/<StructureTypeName>
读取一个结构类型的实例
StructureTags
读取多个结构类型的实例
Value/<TagName>
读取一个变量的运行系统值
将值写入到一个变量
Values
读取所有变量的运行系统值
将值写入到多个变量
tag/<TagName>
读取一个变量的组态数据
tags
读取所有变量的组态数据
4.1.2 归档系统方法
基本 URL
https://<Host>:<Port>/WinCCRestService/tagLogging/
端点
Archives
读取所有过程值归档的组态数据
Archive/<ArchiveName>
读取单个过程值归档的组态数据
Archive/<ArchiveName>/Variable/<TagName>
读取单个过程值归档变量的组态数据
Archive/<ArchiveName>/Variables
读取过程值归档所有变量的组态数据
Archive/<ArchiveName>/Value/<TagName>
读取过程值归档变量的运行系统值
Archive/<ArchiveName>/Values
读取单个过程值归档的多个变量的运行系统值
从不同过程值归档中读取多个变量的运行系统值
Timer/<TimerName>
读取归档系统单个时间的组态数据
Timers
读取归档系统所有时间的组态数据
Tag/<TagName>
读取归档系统变量的组态数据
Tags
读取所有归档系统变量的组态数据
4.1.3 消息系统的方法
基本 URL
https://<Host>:<Port>/WinCCRestService/alarmLogging/
端点
Message/<MessageNumber>
读取一条消息的组态数据
Messages
读取所有消息的组态数据
MessageClass/<MessageClassName>
读取一个消息类别的组态数据
MessageClasses
读取所有消息类别的组态数据
MessageType/<MessageTypeName>
读取一个消息类型的组态数据
MessageTypes
读取所有消息类型的组态数据
MessageBlock/<MessageBlockName>
读取一个消息块的组态数据
MessageBlocks
读取所有消息块的组态数据
MessageGroup/<MessageGroupName>
读取一个消息组的组态数据
MessageGroups
读取所有消息组的组态数据
LimitValue/<Tagname>
读取一个变量的限值的组态数据
LimitValues
读取所有变量的限值的组态数据
RestFilter/<Filtername>
读取一个 REST 过滤器的组态数据
RestFilters
读取所有 REST 过滤器的组态数据
MessageList/<Filtername>
读取一个消息列表的运行系统消息
ShortTermArchive/ <Filtername>
从一个短期归档中读取运行系统消息
LongTermArchive/<Filtername>
从一个长期归档中读取运行系统消息
HitList/<Filtername>
从一个统计列表中读取运行系统消息
Hidelist/<Filtername>
从一个要隐藏的消息列表中读取运行系统消息
HiddenMessageList/<Filtername>
从一个已隐藏消息列表中读取运行系统消息
4.2 方法过滤器
4.2.1 过滤器的使用
插入过滤器
过滤器将作为 URL 的一部分进行传送：
- <URL>?<过滤条件>
示例：
- https://<URL>/WinCCRestService/tagManagement/variables?canWrite
过滤器字符串不区分大小写。
链接
可同时使用多个不同过滤器。
对于逻辑运算，使用操作数“&”，例如：
- <URL>?<过滤条件_1>&<过滤条件_2>&<过滤条件_3>
连接的过滤器越多，对搜索结果的限制就越多。不允许使用 OR 逻辑运算。
每个过滤器参数只能在一个请求中使用一次。
无效过滤器组合的示例：
- variables?variableName=mot*&variableName=!motor
4.2.2 过滤条件
| 参数 | 对象 | 描述 |
|---|---|---|
| canRead | 变量 | 返回已登录用户具有读取访问权限的变量的名称。 |
| canWrite | 变量 | 返回已登录用户具有写入访问权限的变量的名称。 |
| variableName | 变量 | 返回包含所搜索字符串的所有变量的名称。
可使用占位符“?”和“*”。 |
| connection | 变量：连接数据 | 提供在创建变量、结构变量或变量组时所用连接的相关信息。 |
| structureType | 结构变量 | 返回结构类型的所有结构类型元素的名称。 |
| structureVariable | 结构变量 | 返回结构类型的所有结构变量元素的名称。 |
| group | 变量组 | 返回变量组中所有变量的名称。 |
| channel | 通信通道 | 返回通道下所有连接的名称。 |
| archiveName | 过程值归档 | 返回包含所搜索字符串的所有过程值归档。
可使用占位符“?”和“*”。 |
| begin | 过程值归档 | 返回过程值归档中变量值的时间范围的起始时间。
日期格式：YYYY-MM-DD hh:mm:ss:ms 示例：2015-12-31 16:30:00:000 |
| end | 过程值归档 | 返回过程值归档中变量值的时间范围的结束时间。
日期格式：YYYY-MM-DD hh:mm:ss:ms 示例：2015-12-31 16:30:00:000 |
| range | 过程值归档 | 返回过程值归档中变量值的时间范围，单位为秒。
如果使用时未关联到“begin”或“end”参数，则会将过程值归档的最后几秒设为时间范围。 |
| maxValues | 过程值归档 | 返回的最大变量值数。
除非另有规定，否则最多返回 1000 个变量值。 |
| Name | 消息系统 | 返回包含所查找的名称的消息类别、消息类型、消息块、消息组和限制的所有条目。
可使用占位符“?”和“*”。 |
| MessageClass | 消息系统 | 返回具有所搜索消息类别的所有消息。 |
| MessageType | 消息系统 | 返回具有搜索消息类型的所有消息。 |
| MessageGroup | 消息系统 | 返回包含所搜索消息组的所有消息/组。 |
| MessageTag | 消息系统 | 返回带有所搜索消息变量的所有消息。 |
| StatusTag | 消息系统 | 返回所有具有所搜索的状态变量的消息/组。 |
| AcknowledgmentTag | 消息系统 | 返回所有带有所搜索的确认变量的消息/组。 |
| GroupLockTag | 消息系统 | 返回所有带有所搜索的锁定变量的消息组。 |
| GroupHideTag | 消息系统 | 返回所有带有所搜索的隐藏变量的消息组。 |
| maxValues | 消息系统 | 短期存档、长期存档和命中列表返回的最大消息数。
最多 |
| changed_After | 组态数据 | 返回在指定日期后更改的组态数据。不适用于消息系统的方法。
日期格式：YYYY-MM-DD hh:mm:ss:ms 示例：2015-12-31 16:30:00:000 |
| itemLimit | 组态数据 | 限制返回元素的数量。
这可提高大型 WinCC 项目的性能。 |
| continuationPoint | 组态数据 | 继续执行通过“itemLimit”限制的请求。
如果找到的元素数量大于通过“itemLimit”设置的值，则将在达到最大值时停止输出。可通过再次请求继续输出，直至返回所有已找到的元素。 |
| *
? |
通配符 | 只能在过滤变量名称 (variableName) 时使用通配符。
|
| ! | 操作数：取反 (NOT) | 对于每个请求只能使用一个 NOT 过滤器。 |
| & | 操作数：逻辑运算 (AND) | 可为每个请求使用多个 AND 逻辑运算。 |
