OPCDA-Proxy的Web API代理接口

# Web API接口

## API接口列表

|接口url|需要参数|说明|
|----|----|----|
|/login|是|登录接口|
|/version|否|查询版本号|
|/items|否|获取系统中的所有标签|
|/tags|否|读取所有许可标签的当前值|
|/tag|是|读取单个或者多个指定标签的当前值|
|/update|是|更新单个或者多个标签的值|
|/authorize|否|获取授权信息|
|/modbusmap|否|获取Modbus地址表|

## 通用返回结果的结构

- 通用返回结果

```json
{
    "ok": true,
    "msg": "",
    "data": ""
}
```

- 返回参数

|参数名|类型|说明|
|----|----|----|
|ok|bool|返回结果是否正确|
|msg|string|ok==true时:显示一些必要信息; ok==false时:返回错误信息|
|data|any|ok==true时:显示返回的数据; ok==false时:显示额外的数据|

# Web API接口详解
## 登录
- 描述
  用户登录系统，获得访问其他API接口的授权。未授权的访问会被拒绝。
- 请求URL

`http://localhost:8765/login`

- 请求方式

POST

- 请求参数

|参数名|必选|类型|说明|
|----|----|----|----|
|user|是|string|用户名|
|password|是|string|用户密码|
|exphours|否|int|登录信息的有效小时数|

- 返回示例

```json
{
    "ok": true,
    "msg": "2024-01-25 12:08:27",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJwcm94eXVzZXIiLCJleHAiOjE3MDYxNTU3MDcsImp0aSI6IjE3MDYxNTIxMDc4ODAiLCJpYXQiOjE3MDYxNTIxMDcsImlzcyI6Ik1pY09QQ1Byb3h5IiwibmJmIjoxNzA2MTUyMTA3LCJzdWIiOiIxOTIuMTY4LjMuNDAifQ.GKrQM19FnzrFCPI14TB9mwmrdy08S2Oj79C24Wn_HNg"
}
```

- 返回参数

|参数名|类型|说明|
|----|----|----|
|ok|bool|返回结果是否正确|
|msg|string|ok==true时:登录信息有效时间; ok==false时:返回错误信息|
|data|string|ok==true时:用户登录JWT令牌; ok==false时:无|

- 应用程序获取到JWT令牌(Token)后的使用方法

有三种方式可以使用获取到的JWT令牌：[Cookie](#cookie)、[Header](#header)和[请求参数](#parameter)。

1. Cookie方式

获取到JWT后，在浏览器中写入一个名为`Authorization`的Cookie，Cookie的值为`Bearer <JWT>`(不含`< >`),以便为浏览器记录登录状态。浏览器访问同域名下的页面时会自动带着Cookie。应用程序接收到Cookie后，读取其中的`Authorization`值,并获取JWT令牌。此种方式最方便，**但不支持跨域**。
![Cookie方式使用JWT Token的示例](/media/202405/2024-05-27_163101_9491390.934568898284632.png)

2. Header方式
 获取到JWT令牌后，在客户端浏览器的请求头(Header)中添加名为`Authorization`,值为`Bearer <JWT>`(不含`< >`)的参数，客户端访问应用程序时应一直在请求中带着该参数。应用程序接收到客户端的请求后，读取其Header中的`Authorization`值，并获取JWT令牌。**推荐使用此种方式，支持跨域访问**。
 ![Header方式使用JWT Token的示例](/media/202405/2024-05-27_163122_5129860.9636589825272993.png)

3. 请求参数方式
 获取到JWT后，在客户端的每个需要验证权限的请求中，添加一个`Authorization=<JWT>`(不含`< >`)的参数，应用程序接收到客户端的请求后，读取其请求参数中的`Authorization`值，并获取JWT令牌。**此种方式支持跨域**。
 ![请求参数方式使用JWT Token的示例](/media/202405/2024-05-27_163201_1131310.8176543102218842.png)

## 获取系统中的所有标签

- 描述

- 以层级结构列出OPCDA-Proxy所连接的OPC Server中的所有可访问的标签。
  - 如果配置文件中设定了`opc.tags`,则只有该配置参数列出的标签才可在OPCDA-Proxy中被访问。

- 请求URL

`http://localhost:8765/items`

- 请求方式

GET

- 请求参数

|参数名|必选|类型|说明|
|----|----|----|----|
|server|否|string|OPC服务器的字符串。如果配置参数或者启动参数中没有设定OPC server,且没有在其他API接口中输入过有效的OPC server, 则此参数必须|
|node|否|string|OPC服务器的计算机节点,默认为`localhost`|

>在任意一个需要server的API接口中输入过有效的server后，系统会记录第一个有效的OPC server.

- 返回示例

```json
{
    "ok": true,
    "msg": "",
    "data": {
        "Name": "root",
        "Branches": [
            {
                "Name": "options",
                "Branches": [],
                "Leaves": [
                    {
                        "Name": "sawfreq",
                        "Tag": "options.sawfreq"
                    },
                    {
                        "Name": "sinfreq",
                        "Tag": "options.sinfreq"
                    },
                    {
                        "Name": "trianglefreq",
                        "Tag": "options.trianglefreq"
                    },
                    {
                        "Name": "sqaurefreq",
                        "Tag": "options.sqaurefreq"
                    }
                ]
            }
        ]
    }
}
```

- 返回参数

|参数名|类型|说明|
|----|----|----|
|Name|string|节点名称|
|Branches|array|当前节点下的分支节点。有分支节点的时候就不会有叶子节点|
|Leaves|array|当前节点下的叶子节点,叶子节点有`Name`和`Tag`两个属性. 叶子节点的`Tag`是最终的标签名。某个节点有叶子节点的时候就不会有分支节点|

## 读取所有许可标签的当前值

- 描述

- 读取所有许可标签的当前值。
  - 如果配置文件中设定了`opc.tags`,则只读取该参数中设定的标签的当前值。否则读取全部标签。

- 请求URL

`http://localhost:8765/tags`

- 请求方式

GET

- 请求参数

|参数名|必选|类型|说明|
|----|----|----|----|
|server|否|string|OPC服务器的字符串。如果配置参数或者启动参数中没有设定OPC server,且没有在其他API接口中输入过有效的OPC server, 则此参数必须|
|node|否|string|OPC服务器的计算机节点,默认为`localhost`|

>在任意一个需要server的API接口中输入过有效的server后，系统会记录第一个有效的OPC server.

- 返回示例

```json
{
    "ok": true,
    "msg": "",
    "data": {
        "enum.number": {
            "Value": 4,
            "Quality": 192,
            "Timestamp": "2024-01-25T12:13:14Z"
        },
        "numeric.sin.double": {
            "Value": -10.31744676636319,
            "Quality": 192,
            "Timestamp": "2024-01-25T12:13:14Z"
        },
        "options.sinfreq": {
            "Value": 0.05,
            "Quality": 192,
            "Timestamp": "2024-01-25T12:13:14Z"
        },
        "time.current": {
            "Value": "2024-01-25T04:13:15Z",
            "Quality": 192,
            "Timestamp": "2024-01-25T12:13:14Z"
        }
    }
}
```

- 返回参数

|参数名|类型|说明|
|----|----|----|
|Value|any|标签的当前值|
|Quality|int|数据质量码, { 0:"Bad", 64:"Uncertain", 192:"Good", 216:"GoodButForced", 其他:"Uncertain" }|
|Timestamp|time|标签数值的时间戳|

## 读取指定标签的当前值

- 描述

- 读取指定标签的当前值
  - 如果配置文件中设定了`opc.tags`,指定的标签只能是设置的参数中的标签之一。

- 请求URL

`http://localhost:8765/tag`

- 请求方式

GET

- 请求参数

|参数名|必选|类型|说明|
|----|----|----|----|
|tagname|是|string|待读取的标签名称,可以是多个标签,多个标签之间用逗号`,`隔开|
|server|否|string|OPC服务器的字符串。如果配置参数或者启动参数中没有设定OPC server,且没有在其他API接口中输入过有效的OPC server, 则此参数必须|
|node|否|string|OPC服务器的计算机节点,默认为`localhost`|

>在任意一个需要server的API接口中输入过有效的server后，系统会记录第一个有效的OPC server.

- 返回示例

```json

//访问URL: http://localhost:8765/tag?tagname=numeric.sin.double

{
    "ok": true,
    "msg": "numeric.sin.double",
    "data": {
      "numeric.sin.double":{
          "Value": -70.71067811886206,
          "Quality": 192,
          "Timestamp": "2024-01-25T12:43:32Z"
        }
      }
}
```

- 返回参数

|参数名|类型|说明|
|----|----|----|
|msg|string|ok==true时,显示当前所读取的标签|
|Value|any|标签的当前值|
|Quality|int|数据质量码, { 0:"Bad", 64:"Uncertain", 192:"Good", 216:"GoodButForced", 其他:"Uncertain" }|
|Timestamp|time|标签数值的时间戳|

## 更新标签值

- 描述

- 通过API接口创建一个新的标签
  - 需要配置参数中的`config.allow_add`设置为`true`

- 请求URL

`http://localhost:8765/update`

- 请求方式

POST、PUT

- 请求参数

|参数名|必选|类型|说明|
|----|----|----|----|
|变量标签1|否|string|待更新的变量标签1名称|
|变量标签2|否|string|待更新的变量标签2名称|

>可以同时更新多个标签

- 返回示例

```json

//访问URL: http://localhost:8765/update?options.sinfreq=2.123&enum.number=3.214
{
    "ok": true,
    "msg": "",
    "data": [
        "options.sinfreq",
        "enum.number"
    ]
}
```

- 返回参数

`data`中的数据标签是更新成功的标签

## 获取授权信息

- 描述

- 获取OPCDA-Proxy的授权状态和授权信息

- 请求URL

`http://localhost:8765/authorize`

- 请求方式
GET

- 请求参数
  无

- 返回示例

```json

//访问URL: http://localhost:8765/authorize

{
    "ok": true,
    "msg": "",
    "data": {
        "MachineCode": "DtpAXFv2R93wrN+3JTQWgS4rYovXfePBIHASFOY9TTjVAkIo5aahhOo+as5xyEz+yk3JeBS7YbqJTjjKk03p9w==",
        "AuthorCode": "Ywbsl+7K7s7AJCcbJbRXVSdst11iM5NonalM730X62nljMU2j+cYNxcars5TDSKsIiQBs/gdL9KMlGq4ODtxRcyEljmpsEekb8Qc4xpXcPSAAmmTa99ic5goQ7mywsY/UvC9M636fjMKjxs0E2PGPZUuO7rMrOFC65ATynJYakrdAYBXeY1UMm3UjnfZmh7s3aLd0ant71F+snN02A3CGg==",
        "UserName": "wjp",
        "Organization": "BDGCA",
        "Tags": 1024,
        "CreateAt": "2024-06-17T12:45:06"
    }
}
```

- 返回参数

|参数名|类型|说明|
|----|----|----|
|MachineCode|string|机器码|
|AuthorCode|string|授权码|
|Organization|string|被授权的组织机构名称或者代码|
|UserName|string|被授权的用户名称|
|Tags|int|被授权使用的标签数(仅限制Modbus-TCP代理的标签数)|
|CreateAt|string|授权信息创建时间|

## 获取Modbus地址表

- 描述

- 获取OPCDA-Proxy的Modbus地址表

- 请求URL

`http://localhost:8765/modbusmap`

- 请求方式
GET

- 请求参数
  无

- 返回示例

```json

//访问URL: http://localhost:8765/modbusmap

{
    "ok": true,
    "msg": "",
    "data": [
        {
            "Id": 0,
            "Item": "enum.number",
            "ValType": "int32",
            "Offset": 0,
            "Size": 2
        },
        {
            "Id": 1,
            "Item": "options.sinfreq",
            "ValType": "float64",
            "Offset": 2,
            "Size": 4
        },
        {
            "Id": 2,
            "Item": "numeric.sin.double",
            "ValType": "float64",
            "Offset": 6,
            "Size": 4
        }
    ]
}
```

- 返回参数
|参数名|类型|说明|
|----|----|----|
|Id|int|自增ID|
|Item|string|OPC变量标签|
|ValType|string|数据类型|
|Offset|int|起始地址,以位寄存器（16位）为单位|
|Size|int|数据长度,以位寄存器（16位）为单位|