数据API发布

1.功能简介

IOT平台能通过接入设备和多种类型的数据源并将之转化为标准的restful API和MQTT的数据接口。api发布作为数据管理功能的一部分，可以生成RESTFUL_API，查询边缘系统服务下属设备以及第三方数据库的接口，供第三方调用。此外，还可支持生成MQTT订阅主题供第三方使用

1.1 术语定义

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

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

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

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

1.2 RESTFUL_API

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

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

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

1.3 MQTT

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

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

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-04-30

数据API发布

1.功能简介

1.1 术语定义

1.2 RESTFUL_API

1.3 MQTT

2 数据对象管理

2.1 数据api配置DTO：ApiInfoDTO

2.2 api管理主要接口：

2.3 创建数据API

3 HTTP查询接口（RESTFUL_API）

3.1 token认证标识

3.2 请求语法

3.3 请求参数

3.4 请求响应

3.5 请求示例

3.6 错误码

4.MQTT订阅

4.1 MQTT使用前提

4.2 MQTT订阅接口

本页目录