1.功能简介
IOT平台能通过接入设备和多种类型的外部数据源并将之转化为标准的restful API、MQTT、RabbitMQ、KAFKA的数据接口。数据发布作为数据管理功能的一部分，可以生成RESTFUL_API，查询设备属性、设备报警以及第三方数据库的接口，供第三方调用 。此外，还可支持生成MQTT、KAFKA订阅主题供第三方使用，或配置RabbitMQ队列中指定rooting key获取设备属性采集数据、外部数据库数据。
1.1 术语定义
设备数据源：设备数据主要指通过边缘连接服务进行协议或者设备连接之后所获取的数据。可以是通过连接PLC，OPC-UA或者MQTT等协议经过边缘连接服务所采集的数据。使用设备数据源之前需在配置管理中提前配置连接和设备。
外部数据源：外部数据源指的是连接外部数据库，目前支持查询mysql和influxDB数据。
报警数据源：用户可以自定义设备报警，报警数据支持对外发布。
属性组：设备的属性可以通过属性组进行划分。可以通过【配置管理】-【物模型配置】创建属性组再由设备继承物模型，也可以直接在【配置管理】-【设备配置】中直接给设备创建属性组，在数据发布中可以通过选择设备属性组进行发布。
属性：在HiperMATRIX中，属性即为资产（或者设备）的功能定义，属性分为三种类型：静态属性，动态属性，计算属性。静态属性指具有静态特征的数据表示，比如设备生产厂家和产品规格型号。动态属性主要指一些采集变量如温度，压力，或者设备变量等。计算属性指通过HiperMATRIX平台计算处理后得到的属性，这三种属性都可以通过数据发布进行调用，但是静态属性的数据取决于创建时设置的默认值。
1.2 RESTFUL_API
目前存在三种类型的RESTFUL_API，EQUIPMENT（设备数据源）、THING（外部数据源）、ALARM（报警数据源）
EQUIPMENT（设备数据源）
查询边缘系统服务下属设备属性数据，支持用户同时查询多个设备，通过属性勾选选择其需要查询的数据。
默认查询返回当前设备最新数据，用户可以通过设置时间范围等查询定制化信息
THING（外部数据源）
查询数据源配置的外部数据源信息，可查询一个数据库下的数据。目前支持查询mysql和influxDB
默认查询返回当前数据源最新数据，用户可以通过设置时间范围等查询定制化信息；支持原生sql查询
ALARM（报警数据源）
用户可配置查询指定设备、指定报警级别的设备报警数据，默认展示半小时以内的整点报警数据，用户可通过设置时间范围、报警状态等参数定向查询数据。
1.3 MQTT
（1）设备数据源：配置指定设备的MQTT订阅主题，转发点位采集数据，用户可以使用MQTT CLIENT订阅此类消息。
（2）外部数据源：查询数据源配置的外部数据库数据，支持查询mysql和influxDB
（3）报警数据源：对指定设备、指定级别的设备报警通过MQTT发布，利用订阅主题的方式获取报警数据
1.4 RabbitMQ
(1)设备数据源：用户可自定义MQ队列中rooting key，查询指定设备属性采集到的数据
(2)外部数据源：查询数据源配置的外部数据库数据，支持查询mysql和influxDB
(3)报警数据源：指定设备、指定报警级别的设备报警通过RabbitMQ发布，通过绑定rootingkey获取队列数据。
1.5 KAFKA
(1)设备数据源：配置指定设备的KAFKA订阅主题，转发属性采集到的数据
(2)外部数据源：查询数据源配置的外部数据库数据，支持查询mysql和influxDB
(3)报警数据源：指定设备、指定报警级别的设备报警通过KAFKA发布，通过订阅主题方式获取报警数据。
2 数据对象管理
2.1 数据api配置DTO：ApiInfoDTO
| 参数 | 描述 | 参数类型 |
|---|---|---|
| id | 主键id | int |
| name | API名称 | string |
| url | API路径 | string |
| apiEquipmentDTO | API设备信息定义 | List<ApiEquipmentDTO> |
| apiThingDTO | API数据源定义 | ApiThingDTO |
| mqttDTO | MQTT配置 | PublishMqttDTO |
| description | 发布API描述 | string |
| token | 是否启用Token验证 | bool |
| equipmentIds | 设备ID列表 | List<String> |
| tableName | 数据表名 | String |
| dataSourceId | 数据源ID | int |
| dataSourceType | THING/EQUIPMENT 数据源类型 | Enum |
| apiTypeEnum | MQTT/RESTFUL API API类型 | Enum |
补充：
API设备信息定义、API数据源API定义MQTT配置，将在后续内容中介绍
2.2 api管理主要接口：
- 新建api定义
- 请求方式： post
- 请求体： ApiInfoDTO
- 请求路径： http://{ip}:{port}/{gateway}/{application-name}/addApiInfo
- 返回结果： 新增主键id
- 编辑api定义
- 请求方式： put
- 请求体： ApiInfoDTO
- 请求路径： http://{ip}:{port}/{gateway}/{application-name}/updateApiInfo
- 返回结果： void
- 删除api定义
- 请求方式： get
- 请求路径： http://{ip}:{port}/{gateway}/{application-name}/deleteApiInfo/{id}
- 返回结果： void
- 查询全部api定义
- 请求方式： get
- 请求路径： http://{ip}:{port}/{gateway}/{application-name}/getList
- 返回结果： List<ApiInfoDTO>
2.3 创建数据发布
点击导航栏【配置管理】->【数据发布】，进入数据API发布界面，点击新增。
2.3.1 RESTFUL_API-设备数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 自定义消息接口 | API接口格式为{ip:端口}/api/data-query-service/publish/data/{用户自定义部分}，便于用户在第三方系统区分不同的接口 |
| 数据服务类型 | 选择设备数据源，必填 |
| 启用token | 勾选后开启token验证，调用API时无token会报401错误 |
| 选择设备 | 查询设备。必填，可多选。 |
| 属性列表 | API返回的属性。可多选 |
数据格式
| 参数 | 描述 | 参数类型 |
|---|---|---|
| equipmentId | 设备ID | String |
| groupId | 属性组ID | String |
| dataSourceId | 数据源ID | List<String> |
2.3.2 RESTFUL_API-外部数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 自定义消息接口 | API接口格式为{ip:端口}/api/data-query-service/publish/data/{用户自定义部分}，便于用户在第三方系统区分不同的接口 |
| 数据服务类型 | 选择外部数据源。必填 |
| 启用token | 勾选后开启token验证，无token项会报401错误 |
| 数据源 | 选择需要对外发布的数据库，仅支持发布mysql和influxDB类型的数据库，需提前在【配置管理】-【数据源配置】中设置。 |
| 数据表 | 目标数据表，可以选择目标数据的数据表。 |
| 属性列表 | 数据API查询的字段。可多选 |
| sql语句执行 | 目标数据源查询的一段原生sql语句。支持对同一数据源的跨表查询，不支持增删改表数据以及修改数据库 |
数据格式
| 参数 | 描述 | 参数类型 |
|---|---|---|
| dataSourceId | 数据源ID | List<String> |
| tableName | 数据表名 | String |
| columns | 数据表字段列表 | List<String> |
| url | 数据库url | String |
| dataSourceId | 数据源ID | int |
| type | 数据源类型 | String |
| database | 数据源名称 | String |
| timeCol | 时间字段 | String |
| usesql | 启用原生sql查询 | Boolean |
| sql | 原生sql查询 | String |
2.3.3 RESTFUL_API-报警数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 自定义消息接口 | API接口格式为{ip:端口}/api/data-query-service/publish/alarm/{用户自定义部分}，便于用户在第三方系统区分不同的接口 |
| 数据服务类型 | 选择报警数据源，必填 |
| 设备选择 | 指定查询哪些设备的报警数据。必填，可多选。 |
| 报警级别 | 指定查询设备报警的级别，必填 |
| 报警类型 | 指定查询设备报警的类型，必填 |
**注意：**默认展示半小时以内的整点报警数据，查询间隔最大为一天，查询报警时间不能超过数据最大存储时间。
允许添加以下参数：start-开始时间；end-结束时间；limit-限制条数；status-报警状态
2.3.4 MQTT -设备数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 数据服务类型 | 选择设备数据源，必填 |
| 数据源 | 选择mqtt server，需提前在【配置管理】-【数据源配置】中设置 |
| 类型 | 可以按周期发布或值变化发布 |
| topic | 输入mqtt topic |
| 推送频率 | 默认5000毫秒 |
| 选择设备 | 选择需查询的设备。必填，可多选 |
| 属性列表 | API返回的属性。可多选 |
数据格式
| 参数 | 描述 | 参数类型 |
|---|---|---|
| Name | API名称 | String |
| Description | API描述 | String |
| EquipmentId | 设备ID | String |
| FieldList | 属性列表 | List |
| RouteList | 路由列表 | List |
| GroupId Integer | 属性分组ID | Integer |
| CycleTimes | 定时采集 | Integer |
| Username | Mqtt连接名称 | String |
| Password | Mqtt连接密码 | String |
2.3.5 MQTT-外部数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 数据服务类型 | 选择外部数据源，必填 |
| MQTT配置-数据源 | 选择mqtt server，需提前在【配置管理】-【数据源配置】中设置 |
| topic | 输入mqtt topic |
| 推送频率 | 默认5000毫秒 |
| 数据源/数据表选择-数据源 | 选择需要对外发布的数据库，仅支持发布mysql和influxDB类型的数据库，需提前在【配置管理】-【数据源配置】中设置 |
| 数据源/数据表选择-数据表 | 选择已选中数据库下的数据表 |
| 属性列表 | API返回的属性。可多选 |
| sql语句执行 | 目标数据源查询的一段原生sql语句。支持对同一数据源的跨表查询，不支持增删改表数据以及修改数据库 |
2.3.6 MQTT-报警数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 数据服务类型 | 选择报警数据源，必填。 |
| 数据源 | 选择mqtt server，需提前在【配置管理】-【数据源配置】中设置 |
| Topic | 输入mqtt topic |
| 设备选择 | 指定查询哪些设备的报警数据。必填，可多选。 |
| 报警级别 | 指定查询设备报警的级别，必填 |
| 报警类型 | 指定查询设备报警的类型，必填 |
2.3.7 RabbitMQ-设备数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 数据服务类型 | 选择设备数据源，必填 |
| 数据源 | 选择Rabbitmq server，需提前在【配置管理】-【数据源配置】中设置 |
| rooting key | 用户需保证exchange下存在对应queue |
| 推送频率 | 默认5000毫秒 |
| 选择设备 | 选择需查询的设备。必填，可多选 |
| 属性列表 | 返回的属性。可多选 |
2.3.8 RabbitMQ-外部数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 数据服务类型 | 选择外部数据源，必填。 |
| RabbitMQ配置-数据源 | 选择Rabbitmq server，需提前在【配置管理】-【数据源配置】中设置 |
| rooting key | 用户需保证exchange下存在对应queue |
| 推送频率 | 默认5000毫秒 |
| 数据源/数据表选择-数据源 | 选择需要对外发布的数据库，仅支持发布mysql和influxDB类型的数据库，需提前在【配置管理】-【数据源配置】中设置 |
| 数据源/数据表选择-数据表 | 选择已选中数据库下的数据表 |
| 属性列表 | 返回的属性，可多选 |
| sql语句执行 | 目标数据源查询的一段原生sql语句。支持对同一数据源的跨表查询，不支持增删改表数据以及修改数据库 |
2.3.9 Kafka-设备数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 数据服务类型 | 选择设备数据源，必填 |
| 数据源 | 选择Kafka server，需提前在【配置管理】-【数据源配置】中设置 |
| topic | kafka topic |
| 推送频率 | 默认5000毫秒 |
| 选择设备 | 选择需查询的设备。必填，可多选 |
| 属性列表 | 返回的属性。可多选 |
2.3.10 Kafka-外部数据源创建方法
配置参数
| 参数名称 | 内容 |
|---|---|
| API名称 | 数据API发布界面显示的API名称。唯一、必填 |
| 描述 | |
| 数据服务类型 | 选择外部数据源，必填。 |
| Kafka配置-数据源 | 选择Kafka server，需提前在【配置管理】-【数据源配置】中设置 |
| topic | kafka topic |
| 推送频率 | 默认5000毫秒 |
| 数据源/数据表选择-数据源 | 选择需要对外发布的数据库，仅支持发布mysql和influxDB类型的数据库，需提前在【配置管理】-【数据源配置】中设置 |
| 数据源/数据表选择-数据表 | 选择已选中数据库下的数据表 |
| 属性列表 | 返回的属性，可多选 |
| sql语句执行 | 目标数据源查询的一段原生sql语句。支持对同一数据源的跨表查询，不支持增删改表数据以及修改数据库 |
3 HTTP查询接口（RESTFUL_API）
api定义完成后，用户可以通过http调用的api url来使用接口查询数据
目前支持post和get型请求，推荐使用post
查询设备数据源默认返回每个属性最后值；
当查询结果为空时，同样返回每个属性最后值；
3.1 token认证标识
使用HTTP查询接口时，如果接口开启token验证，则需要在请求Header中附加token。
用户可以通过登录接口获取token信息，启动token后使用HTTP接口实例如下：
token: ca61dc95-444b-420f-b8f2-fc8d07631be6 （此为示例token，请使用实际token）
3.2 请求语法
设备数据源URL:
POST(或GET) {http|https}://{host}:{port}/data-query-service/api/equipment/set/data/{timestamp}
外部数据源URL:
POST(或GET) {http|https}://{host}:{port}/data-query-service/api/thing/{dataSourceId}/{timestamp}
3.3 请求参数
API请求可以以RequestBody的形式添加下参数
| 字段 | 描述 | 备注 |
|---|---|---|
| limit | 主键id | int |
| offset | API名称 | string |
| isDesc | API路径 | string |
| start | 开始时间。 | string，ISO 8601格式: YYYY- MM-DDTHH:MM:SSZ |
| end | 结束时间。 | string，ISO 8601格式: YYYY- MM-DDTHH:MM:SSZ |
| keyValue | 匹配键值对 | Map，仅外部数据源非sql查询可用 |
start，end格式样例: "2022-01-07T06:36:49.248Z“
3.4 请求响应
Api请求结果
| 字段 | 描述 | 备注 |
|---|---|---|
| code | 请求状态码 | string |
| data | 数据结果 | json，内容为List<RecordResult>对象 |
| message | 错误信息 | string |
RecordResult
| 字段 | 描述 | 备注 |
|---|---|---|
| name | 设备名/数据库表名 | string |
| data | JSON型查询结果 | json |
3.5 请求示例
查询外部数据源，无参数
请求
URL:http://58.247.122.126:10007/data-query-service/api/thing/203/1640850760248
结果
{
{
"data": [
{
"name": "test2",
"data": [
{
"code": "1111",
"test": "2"
},
{
"code": "1123",
"test": "1"
}
]
}
],
"code": 200,
"message": null
}
}
查询外部数据源，有参数
请求
URL:http://58.247.122.126:10007/data-query-service/api/thing/203/1640850760248
请求参数
{
"keyValue":{
"test": "1"
}
}
结果
{
"data": [
{
"name": "test2",
"data": [
{
"code": "1123",
"test": "1"
}
]
}
],
"code": 200,
"message": null
}
查询外部数据源，使用sql
请求
URL:http://58.247.122.126:10007/data-query-service/api/thing/203/1640850760248
sql内容
select * from "test2" where test = 1
结果
{
"data": [
{
"name": null,
"data": [
{
"test": "1",
"code": "1123"
}
]
}
],
"code": 200,
"message": null
}
查询设备数据查询，无参数
请求
URL: POST http://58.247.122.126:10007/data-query-service/api/equipment/set/data/1641535057344
结果:
{
"data": [
{
"name": "haidehanjichuang",
"data": [
{
"time": "2022-01-10T02:33:18.780Z",
"calc": "4234.8",
"main_axle_speed": 6200.0,
"main_axle_magnification": 0.949999988079071,
"main_axle_load": 0.9599999785423279
}
]
}
],
"code": 200,
"message": null
}
查询设备数据查询，使用时间参数
请求
URL: POST http://58.247.122.126:10007/data-query-service/api/equipment/set/data/1641535057344
请求参数
{
"start":"2022-01-10T05:00:29.275Z",
"end":"2022-01-10T05:05:29.275Z",
"limit":10
}
结果:
{
"data": [
{
"name": "haidehanjichuang",
"data": [
{
"time": "2022-01-10T13:00:38.967+08:00",
"main_axle_magnification": 0.9300000071525574,
"main_axle_speed": 6400.0
},
{
"time": "2022-01-10T13:00:37.967+08:00",
"main_axle_magnification": 0.9300000071525574,
"main_axle_speed": 5100.0
},
{
"time": "2022-01-10T13:00:36.967+08:00",
"main_axle_magnification": 0.9700000286102295,
"main_axle_speed": 6700.0
},
{
"time": "2022-01-10T13:00:35.969+08:00",
"main_axle_magnification": 0.9300000071525574,
"main_axle_speed": 4500.0
},
{
"time": "2022-01-10T13:00:34.969+08:00",
"main_axle_magnification": 0.8299999833106995,
"main_axle_speed": 4000.0
},
{
"time": "2022-01-10T13:00:33.974+08:00",
"main_axle_magnification": 0.9800000190734863,
"main_axle_speed": 4200.0
},
{
"time": "2022-01-10T13:00:32.968+08:00",
"main_axle_magnification": 0.9800000190734863,
"main_axle_speed": 5500.0
},
{
"time": "2022-01-10T13:00:31.976+08:00",
"main_axle_magnification": 0.8899999856948853,
"main_axle_speed": 5000.0
},
{
"time": "2022-01-10T13:00:30.97+08:00",
"main_axle_magnification": 0.8299999833106995,
"main_axle_speed": 5600.0
},
{
"time": "2022-01-10T13:00:29.969+08:00",
"main_axle_magnification": 0.9399999976158142,
"main_axle_speed": 5100.0
}
]
}
],
"code": 200,
"message": null
}
当查询结果为空时，返回每个被查询属性的最后值；
3.6 错误码
当API调用出现错误时，请根据以下状态码进行排查。
| HTTP状态码 | 错误码 | 定义 |
|---|---|---|
| 200 | 无 | 接口调用成功 |
| 400 | BadRequest | 语义有误，当前请求语法被服务器理解，除非进行修改，否则客户端不应该重复提交该请求 |
| 401 | Unauthorized | 请求认证校验以过期，调用授权接口获取授权信息 |
| 403 | Forbidden | 服务器已经理解请求，但拒绝执行请求。需要进行权限校验，确认当前登录用户是否有权限 调口请求API |
| 404 | NotFound | 请求失败，未在服务器上发现请求所希望得到 的资源。需要确认请求参数是否正确。 |
| 405 | MethodNotAllowed | 请求中指定的请求方法不能被用于请求相应 的资源。例如，不支持使用DELETE语法。 |
| 500 | InternalServerError | 请求出错，优先根据错误信息提示和日志内容 排查问题。 |
| 503 | ServiceUnavailable | 由于临时的服务器维护或服务器过载，因此服务器当前无法处理请求。 |
| 10000 | SERVER_ERROR | 其他错误 |
4 MQTT订阅
4.1 MQTT使用前提
系统配置并启动可用的MQTT broker,与边缘系统保持互通
边缘系统默认配置的MQTT broker为RABBITMQ MQTT模组
4.2 MQTT订阅接口
4.2.1 Topic语法
Topic： data/{时间戳}/{设备ID}/{设备ID}...
4.2.2 连接客户端
使用MQTTCLINET，订阅主题;一般需要输入用户、密码、以及任意CLIENTID
示例所用的客户端软件为MQTTX
4.2.3 订阅
联通MQTTCLINET后，复数个订阅主题
订阅的缺省配置写法可以查阅相应相关资料
4.2.4 报文内容
主题订阅目前返回设备的属性采集数据，格式内容如下
{
"id": "6806393703729467392",
"timestamp": "2021-11-24T17:08:19.122+08:00",
"_type": "haidehanjichuang",
"axle_magnification": 0.9800000190734863
}
