数据发布

1.功能简介

IOT平台能通过接入设备和多种类型的数据源并将之转化为标准的restful API、MQTT、RabbitMQ、KAFKA的数据接口。api发布作为数据管理功能的一部分，可以生成RESTFUL_API，查询设备属性、设备报警以及第三方数据库的接口，供第三方调用 。此外，还可支持生成MQTT、KAFKA订阅主题供第三方使用，或配置RabbitMQ队列中指定rooting key获取设备采集数据。

1.1 术语定义

设备数据源：设备数据主要指通过边缘连接服务进行协议或者设备连接之后所获取的数据。可以是通过连接PLC，OPC-UA或者MQTT等协议经过边缘连接服务所采集的数据。使用设备数据源之前需在边缘连接服务中配置连接和设备。

外部数据源：外部数据源主要包含连接外部数据库（支持查询mysql和influxDB数据），excel/csv文件或者数据表管理中的数据源对象。当前版本不支持将数据表管理中的数据表对象进行发布。

属性组：设备的属性可以通过属性组进行划分。可以通过【边缘连接服务】-【物模型管理】-【物模型】创建属性组再由设备继承物模型，也可以直接在【边缘连接服务】-【边缘设备管理】-【设备管理】中直接给设备创建属性组，在api发布中可以通过选择设备属性组进行发布。

属性：在HiperMATRIX中，属性即为资产（或者设备）的功能定义，属性分为三种类型：静态属性，动态属性，计算属性。静态属性指具有静态特征的数据表示，比如设备生产厂家和产品规格型号。动态属性主要指一些采集变量如温度，压力，或者设备变量等。计算属性指通过HiperMATRIX平台计算处理后得到的属性，这三种属性都可以通过api发布进行调用，但是静态属性的数据取决于创建时设置的默认值。

1.2 RESTFUL_API

目前存在两种类型的RESTFUL_API，EQUIPMENT（设备数据源）和THING（外部数据源）

EQUIPMENT（设备数据源）
查询边缘系统服务下属设备属性数据，支持用户同时查询多个设备，通过属性勾选选择其需要查询的数据。
默认查询返回当前设备最新数据，用户可以通过设置时间范围等查询定制化信息

THING（外部数据源）
查询边缘系统服务配置的外部数据源信息（可以在数据源管理中进行配置），可查询一个数据库下的数据。
默认查询返回当前数据源最新数据，用户可以通过设置时间范围等查询定制化信息；支持原生sql查询

1.3 MQTT

EQUIPMENT（设备数据源）
配置指定设备的MQTT订阅主题，转发点位采集数据，用户可以使用MQTT CLIENT订阅此类消息。

1.4 RabbitMQ

EQUIPMENT（设备数据源）
用户可自定义MQ队列中rooting key，查询指定设备属性采集到的数据

1.5 KAFKA

EQUIPMENT（设备数据源）
配置指定设备的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&lt;ApiInfoDTO>

2.3 创建数据API

点击导航栏【边缘连接服务】->【数据管理】->【数据API发布】，进入数据API发布界面，点击新增，选择RESTFUL_API，即可新增RESTFUL_API。

（1）RESTFUL_API-设备数据源创建方法

配置参数

参数名称 内容
API名称 数据API发布界面显示的API名称。唯一、必填
描述
数据服务类型 选择设备数据源，必填
启用token 勾选后开启token验证，调用API时无token会报401错误
选择设备 查询设备。必填，可多选。
属性列表 API返回的属性。可多选

数据格式

参数 描述 参数类型
equipmentId 设备ID String
groupId 属性组ID String
dataSourceId 数据源ID List<String>

（2）RESTFUL_API-外部数据源创建方法

配置参数

参数名称 内容
API名称 数据API发布界面显示的API名称。唯一、必填
描述
数据服务类型 选择外部数据源。必填
启用token 勾选后开启token验证，无token项会报401错误
数据源 目标数据源，可选择在【数据管理】-【数据源管理】中配置的数据源。必填，单选。
数据表 目标数据表，可以选择目标数据的数据表。
属性列表 数据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

（3）MQTT -设备数据源创建方法

配置参数

参数名称 内容
API名称 数据API发布界面显示的API名称。唯一、必填
描述
MQTT数据源 从数据源配置中选择MQTT数据源
类型 周期发布和值变化发布
Topic 发布的MQTT topic
推送频率(毫秒) 数据发布的间隔时间，周期发布时有效
数据服务类型 数据服务类型，默认设备数据源
选择设备 选择需要发布数据恶设备，必填，可多选
属性列表 发布数据的属性列表，可多选

数据格式

参数 描述 参数类型
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

（4）RabbitMQ-设备数据源创建方法

配置参数

参数名称 内容
API名称 数据API发布界面显示的API名称。唯一、必填
描述
数据服务类型 选择设备数据源，必填
数据源 选择Rabbitmq server，需提前在【边缘连接服务】-【数据管理】-【数据源管理】中设置
rooting key 用户需保证exchange下存在对应queue
推送频率 默认5000毫秒
选择设备 选择需查询的设备。必填，可多选
属性列表 返回的属性。可多选

（5）Kafka-设备数据源创建方法

配置参数

参数名称 内容
API名称 数据API发布界面显示的API名称。唯一、必填
描述
数据服务类型 选择设备数据源，必填
数据源 选择Kafka server，需提前在【边缘连接服务】-【数据管理】-【数据源管理】中设置
topic kafka topic
推送频率 默认5000毫秒
选择设备 选择需查询的设备。必填，可多选
属性列表 返回的属性。可多选

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订阅接口

（1）Topic语法

Topic：在MQTT API发布时，设置的Topic内容

（2）连接客户端

release
使用MQTTCLINET，订阅主题;一般需要输入用户、密码、以及任意CLIENTID

示例所用的客户端软件为MQTTX

（3）订阅

联通MQTTCLINET后，复数个订阅主题

订阅的缺省配置写法可以查阅相应相关资料

（4）报文内容
主题订阅目前返回设备的属性采集数据，格式内容如下

{
	"id": "6806393703729467392",
	"timestamp": "2021-11-24T17:08:19.122+08:00",
	"_type": "haidehanjichuang",
	"axle_magnification": 0.9800000190734863
}
2024-11-01
关注慧程公众号
© 2024 HiperM³ 产品帮助中心 版权所有 沪ICP备16004401号-1
1