970 lines
35 KiB
Markdown
970 lines
35 KiB
Markdown
# 设备管家云平台Open API调用接口文档
|
||
|
||
**修订历史**
|
||
|
||
| 版本 | 时间 | 修改人/参与人 | 备注 |
|
||
| ---- | --------- | ------------- | ---- |
|
||
| V1.0 | 2022-9-22 | 沈斌洪/张荣文 | |
|
||
|
||
基于设备管家云平台，为接入租户提供设备的接入和管理功能。
|
||
|
||
依托于设备管家云家平台，对第三方提供Iot开放服务。
|
||
|
||
|
||
|
||
## API文档摘要
|
||
|
||
### 设备云管家平台
|
||
|
||
设备云管家平台支持包括用户管理、设备管理等，您可以根据本文档提供的API来使用平台应用侧的服务。
|
||
|
||
### 服务
|
||
|
||
服务为当前设备云管家平台可对外提供的功能的应用类型。
|
||
|
||
### 租户
|
||
|
||
租户指每一个使用本平台的独立个体。平台在不同的租户之间进行数据隔离，每个独立的租户只能在各自的租户下进行设备接入，产品/设备/项目管理等。在接入Iot平台前，请先申请建立租户账号。
|
||
|
||
### 应用
|
||
|
||
应用归属于租户，不同租户可拥有不同的应用，同一种应用租户只可拥有一个。应用下的设备以及用户归属于设备管家以及用户中心管理，租户在拥有应用后可在用户中心申请应用超管进行应用管理。
|
||
|
||
### 租户与应用关系图示
|
||
|
||
|
||
|
||
每个租户都可通过服务创建一个应用，应用下的如业务相同设备可通用。
|
||
|
||
## API调用说明
|
||
|
||
### 支持协议
|
||
|
||
HTTP
|
||
|
||
客户端需要将服务端要求的一些必要参数以url的形式进行拼接，然后通过不可逆的加密算法生成加密的签名字符串，然后客户端以HTTP的形式向服务端发送HTTP请求，传输过程中以JSON格式进行传输。
|
||
|
||
### 构造请求
|
||
|
||
一个完整的请求由指定协议下指定终端路径和资源描述符以及参数构成。
|
||
|
||
#### HTTP请求URL
|
||
|
||
平台请求的URL原则上使用符合类Restful风格的资源描述符。
|
||
|
||
URI构成如下：
|
||
|
||
**{Protocol} :// {Endpoint} / {api-resource-path} **
|
||
|
||
- **Protocol**：表示请求的传输协议，当前仅支持HTTP协议。
|
||
|
||
- **Endpoint**：指定承载REST服务端点的服务器域名或IP
|
||
- **api-resource-path**：api服务资源路径，由平台固定前缀/api/v1/加资源定义组成 ，其中v1是版本号。例如查询产品列表时的资源路径：/api/v1/products
|
||
|
||
|
||
|
||
#### HTTP请求方法
|
||
|
||
统一使用post请求，调用者不用管接口语义，对于具有幂等性的操作，接口本身会做幂等性处理。
|
||
|
||
|
||
|
||
#### HTTP请求参数
|
||
|
||
请求参数通常包括**公共参数**和**私有参数**，其中公共参数为所有接口都有的参数，公共参数统一放请求头，私有参数（或称接口业务请求参数）则可参考具体的API,参数传递以**json**格式传输。
|
||
|
||
1. 公共参数 （所有接口都有的参数，**公共参数统一放请求头**)
|
||
2. 私有参数 （或称接口业务请求参数，每个接口自己的私有参数，一般根据各自接口的业务定义，可参考具体的API，**私有参数统一放于请求体中**）
|
||
|
||
|
||
|
||
##### 公共参数
|
||
|
||
平台规定的公共参数统一放置在HTTP请求头中，公共参数有以下：
|
||
|
||
- **Content-type：**消息体的类型(格式)，传application/json
|
||
- **Sign-Info： ** 消息的签名信息，用于网关鉴权。平台使用HTTP和对称加密签名的方式进行请求的合法性验证。
|
||
|
||
|
||
|
||
###### Sign-Info 内容
|
||
|
||
| 公共请求参数 | 数据类型 | 是否必填 | 说明 |
|
||
| ------------ | -------- | -------- | ---------------------------------------------------------- |
|
||
| appid | string | 是 | 访问appid(由平台提供) |
|
||
| signtype | string | 是 | 签名解析方式（目前支持sha256，后续可能支持其他种签名算法） |
|
||
| timestamp | string | 是 | 客户端生成的时间戳，单位到毫秒 |
|
||
| sign | string | 是 | 签名 |
|
||
|
||
如下示例
|
||
|
||
```json
|
||
{
|
||
"signtype":"sha256",
|
||
"sign":"E30098E052D17BD15E9FA5E71EC9CD8396D4DE44FA6F41EAE8388CF6029A1340",
|
||
"appid":"2014072300007148",
|
||
"timestamp":"1651040462800"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
##### 业务参数
|
||
|
||
|
||
|
||
业务请求参数放BODY里，为 json格式, 假设业务参数定义有以下：
|
||
|
||
| 请求参数（私有参数） | **字段名** | **类型** | **必填** | **默认值** | **说明** |
|
||
| -------------------- | ---------- | -------- | :------: | ---------- | -------- |
|
||
| device_id | string | | M | | 设备ID |
|
||
| product_id | string | | M | | 产品ID |
|
||
|
||
则body里的格式为
|
||
|
||
```
|
||
{“device_id”，“xxxx”,"product_id":"xxxdfdf"}
|
||
```
|
||
|
||
|
||
|
||
每个接口的业务参数定义不同，则请求消息体内容也不同；同时需要注意的是，并不是每个接口都需要有请求消息体（或者说消息体为空），消息体具体内容需要根据具体接口而定。
|
||
|
||
例如[查询产品](https://www.baidu.com)接口，其请求的部分消息格式如下所示。
|
||
|
||
```shell
|
||
POST /api/v1/products HTTPS
|
||
Headers:
|
||
Accept: application/json, text/plain, */*
|
||
Accept-Encoding: gzip, deflate
|
||
Accept-Language: zh-CN,zh;q=0.9
|
||
Host: 192.168.11.139:8099
|
||
Connection: keep-alive
|
||
Content-Length: 141
|
||
Content-Type: application/json;charset=UTF-8
|
||
Sign-Info: {"signtype":"sha256","sign":"E30098E052D17BD15E9FA5E71EC9CD8396D4DE44FA6F41EAE8388CF6029A1340","appid":"2014072300007148","timestamp":"1651040462800"}
|
||
|
||
Body:
|
||
{"productId":"1460423311245922305"}
|
||
...
|
||
```
|
||
|
||
|
||
|
||
### 认证鉴权(签名算法)
|
||
|
||
#### sha256 签名原理
|
||
|
||
假设业务请求参数有 a,b则 业务请求参数内容为{"a","xx","b":"xxx"}
|
||
|
||
1. 将业务请求json参数里的请求参数 <font color="red">***先排除掉null值的参数***</font>，按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，将排序后的参数与其对应值,组装到biz_content的值里，例如biz_content={"a":"1","b":"2"},
|
||
|
||
2. 将公共参数（除了sign参数）以及第一步计算完的biz_content参数,按照键值的第一个字符的 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，将排序后的参数与其对应值，组合成 **参数=参数值** 的格式，并且把这些参数用 `&` 字符连接起来，此时生成的字符串为待签名字符串1
|
||
|
||
3. 将请求的uri 拼上"?"，然后再拼接上 第二步生成的 待签名串1,在末尾拼接上secretKey的值,得到待签名字符串2
|
||
|
||
4. 将待签名字符串2进行sha256运算得到最终的sign值.
|
||
|
||
#### 模拟一次签名计算过程：
|
||
|
||
|
||
|
||
```
|
||
|
||
假设
|
||
secretKey为"sdfdfdfdfdfdf"
|
||
请求的接口为 "/api/v1/xxxx"
|
||
头部公共参数有 appid = "2014072300007148";timestamp =1651040462800;signtype = "sha256"；sign 未得到
|
||
业务接口请求参数有 a = 1,b = "2",ab = "123",bc=343434，c=null 则业务请求body内容可能为：{"ab":"123","bc":"343434","a":1,"b":"2","c":null}
|
||
第一步： 对业务请求参数排序，作为biz_content参数的内容值 {"a":1,"ab":"123","b":"2","bc":"343434"}
|
||
注意：其中c排除掉了
|
||
第二步： 把biz_content加入到公共参数里排序，并用&连接，最后拼接上，得到
|
||
appid=2014072300007148&biz_content={"a":1,"ab":"123","b":"2","bc":"343434"}&signtype=sha256×tamp=1651040462800sdfdfdfdfdfdf
|
||
|
||
第三步：按步骤得到待签名字符串为
|
||
/api/v1/xxxx?appid=2014072300007148&biz_content={"a":1,"ab":"123","b":"2","bc":"343434"}&signtype=sha256×tamp=1651040462800sdfdfdfdfdfdf
|
||
|
||
第四步：按步骤操作得到签名为73B0DBA52E12F16C9E2890A0150D82E54644FB379930B1A9964448C5660FF682
|
||
|
||
最终请求头部的 Sign_Info 为 {"appid":"2014072300007148","sign":"73B0DBA52E12F16C9E2890A0150D82E54644FB379930B1A9964448C5660FF682","signtype":"sha256","timestamp":1651040462800}
|
||
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
### 响应说明
|
||
|
||
|
||
|
||
#### 状态码
|
||
|
||
凡是接口有接收到请求的http响应状态码都是200, 至于网络异常等其他原因请自行查阅http状态码，对于一次正常调用，调用方只需要关注状态码为200的响应即可。 至于响应业务是否查询或操作成功等，请查阅响应体中的code.
|
||
|
||
#### 响应消息头
|
||
|
||
对应请求消息头，响应同样也有消息头，如“Content-type”等。Content-type默认为application/json。
|
||
|
||
#### 响应消息体
|
||
|
||
响应消息体将以json格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
| --------- | ---------- | ------------------------------------------------------------ |
|
||
| code | string | 000000 代表查询或处理成功，除此以外都代表失败，具体参见错误码列表 |
|
||
| msg | string | 响应说明 |
|
||
| data | json结构体 | 具体参见每个接口的响应结构定义 |
|
||
| requestId | string | 请求id，调用方可根据requestid在平台回溯请求记录 |
|
||
|
||
例如
|
||
|
||
```
|
||
{
|
||
"code":"000000",
|
||
"msg":"成功",
|
||
"data":{
|
||
"projectId": 1462688159170568194,
|
||
"name": "66666666666666666666666",
|
||
"dataOrder": null
|
||
},
|
||
"requestId":"b0fef3cb-2b6e-4bf7-9743-68e3d61a7e7e"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
当接口调用发生业务异常时，如请求参数缺失/错误时，将返回对应的错误码，部分错误码还将附加对应的错误原因说明。错误响应的Body体格式如下所示。
|
||
|
||
```
|
||
{
|
||
"msg":"鉴权失败",
|
||
"code":"000004",
|
||
"data":"",
|
||
"requestId":"629d04eb-ac33-4a8c-b975-61db6b6ee502"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
#### 响应码列表
|
||
|
||
| 平台业务类别 | 错误码 | 响应码消息 | 响应码描述 |
|
||
| ------------ | ------ | ------------------------------------------------ | ------------------------------------------------------------ |
|
||
| 系统 | 000000 | 请求成功 | 请求成功 |
|
||
| 权限 | 100001 | 登录失败，用户名或密码错误。 | 密码错误 |
|
||
| 权限 | 100002 | 用户不存在。 | 用户名错误 |
|
||
| 权限 | 100003 | 原密码错误。 | 修改密码 |
|
||
| 权限 | 100004 | 鉴权失败。 | 请排查请求中的鉴权参数是否携带正确。 |
|
||
| 权限 | 100005 | 签名鉴权失败。 | 鉴权不通过，未在头部携带签名信息 |
|
||
| 权限 | 100006 | 该用户没有权限。 | 请求资源与用户信息不匹配，例如租户信息与访问资源不匹配 |
|
||
| 权限 | 100007 | 用户状态异常。 | 用户冻结，无效用户等 |
|
||
| 权限 | 100008 | 缺少必要参数。 | 参数少传，漏传等 |
|
||
| 权限 | 100009 | 参数值为空 | 必传的参数值为空 |
|
||
| 权限 | 100010 | 缺少timestamp参数 | 缺少timestamp参数 |
|
||
| 权限 | 100011 | 缺少appid参数 | 缺少appid参数 |
|
||
| 权限 | 100012 | 缺少sign参数 | 缺少sign参数 |
|
||
| 权限 | 100013 | 缺少signtype参数 | 缺少signtype参数 |
|
||
| 权限 | 100014 | 重放攻击 | 重放攻击 |
|
||
| 权限 | 100015 | 时间超时 | 请求超时 |
|
||
| 系统 | 000001 | 系统内部错误。 | bug或网络原因导致的非预期错误 |
|
||
| 系统 | 000002 | 系统正在维护，请稍后重试。 | 子服务连接超时 |
|
||
| 系统 | 000003 | 非预期的错误，可能是网络原因导致的，请稍后再试。 | 任何远程调用或访问数据库/缓存/消息队列的非预期错误 |
|
||
| 系统 | 000004 | 请求参数不合法。 | 表单校验导致的异常 |
|
||
| 系统 | 000429 | 请求过于频繁!!请稍后重试!! | 对于请求过于频繁的租户会进行限流处理 |
|
||
| 通用 | 210001 | 请求参数错误。 | 请求的参数进行校验时发生错误，例如开始时间晚于结束时间等逻辑性错误。 |
|
||
| 通用 | 220001 | 数据库中的数据不正常。 | 数据库的数据错误，例如错误的关联关系导致非空关联为空 |
|
||
| 通用 | 299999 | 操作失败，请稍候再试 | 通用失败码 |
|
||
|
||
|
||
|
||
# 应用侧API列表总览
|
||
|
||
|
||
|
||
| 模块 | 名称 | URI | 说明 | 实现 |
|
||
| ------------ | ---------------------- | ----------------------------------------- | ---------------------------------------- | ---- |
|
||
| **用户中心** | 获取应用列表 | POST：`/api/v1/userCenter/appList` | 根据租户 ID查询应用列表 | ✔ |
|
||
| **设备管家** | 获取设备信息分页 | POST: `/api/v1/deviceManage/deviceInfo` | 查询租户、应用下的设备信息 | ✔ |
|
||
| | 获取设备元数据信息列表 | POST：`/api/v1/deviceManage/deviceModel` | 根据设备ID、查询设备的要素元数据信息列表 | ✔ |
|
||
| **数据中台** | 获取设备最新数据 | POST: `/api/v1/dataCenter/deviceUpToData` | 根据设备ID查询设备的要素最新数据 | ✔ |
|
||
| | 获取设备历史数据 | POST：`/api/v1/dataCenter/device/details` | 根据ID查询设备详情 | ✔ |
|
||
| | 获取设备状态 | POST: `/api/v1/dataCenter/deviceStatus` | 根据设备ID获取设备属性的最新值 | ✔ |
|
||
|
||
# 应用侧API详情
|
||
|
||
# 设备管家云第三方服务-用户中心
|
||
|
||
## 获取应用列表
|
||
|
||
/api/v1/userCenter/appList
|
||
|
||
根据租户 ID查询应用列表
|
||
|
||
### 请求参数
|
||
|
||
| 名称 | 位置 | 类型 | 必选 | 说明 |
|
||
| --------- | ------ | ------ | ---- | ---- |
|
||
| Sign_Info | header | string | true | none |
|
||
|
||
body参数请求示例：
|
||
|
||
```
|
||
{
|
||
}
|
||
```
|
||
|
||
|
||
|
||
> 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "000000",
|
||
"msg": "成功",
|
||
"data": [
|
||
{
|
||
"id": "281905070042251264",
|
||
"tenantId": "0",
|
||
"serverCode": "iot-user-center",
|
||
"applicationName": "用户中心",
|
||
"applicationValidity": "2025-06-25",
|
||
"applicationStatus": 1
|
||
},
|
||
{
|
||
"id": "287296677323210752",
|
||
"tenantId": "0",
|
||
"serverCode": "reservoir-monitoring-platform",
|
||
"applicationName": "水库",
|
||
"applicationValidity": "2025-08-06",
|
||
"applicationStatus": 1
|
||
},
|
||
{
|
||
"id": "288827602469126144",
|
||
"tenantId": "0",
|
||
"serverCode": "device-manage",
|
||
"applicationName": "四信设备管家",
|
||
"applicationValidity": "2026-07-15",
|
||
"applicationStatus": 1
|
||
}
|
||
],
|
||
"requestId": "d7e9700e-e23f-4c87-b8f9-6f5578f65b8a"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
### 返回数据结构
|
||
|
||
| 名称 | 类型 | 说明 |
|
||
| --------------------- | ------ | -------------------- |
|
||
| » id | long | 应用id |
|
||
| » tenantId | long | 租户id |
|
||
| » serverCode | string | 服务编码 |
|
||
| » applicationName | string | 应用名 |
|
||
| » applicationValidity | string | 应用有效日期 |
|
||
| » applicationStatus | int | 应用状态 1启用 0停用 |
|
||
|
||
# 设备管家云第三方服务-设备管家
|
||
|
||
## 获取设备信息分页
|
||
|
||
/api/v1/deviceManage/deviceInfo
|
||
|
||
根据分组ID查询分组详情，包括基本信息及其子分组信息
|
||
|
||
### 请求参数
|
||
|
||
| 名称 | 位置 | 类型 | 必选 | 说明 |
|
||
| ------------- | ------ | ------ | ---- | -------- |
|
||
| applicationId | body | long | true | 应用id |
|
||
| pageNum | body | int | true | 当前页 |
|
||
| pageSize | body | int | true | 每页大小 |
|
||
| Sign_Info | header | string | true | none |
|
||
|
||
body参数请求示例：
|
||
|
||
```
|
||
{
|
||
"tenantId":"0",
|
||
"applicationId":288827602469126144,
|
||
"pageNum":1,
|
||
"pageSize":10
|
||
}
|
||
```
|
||
|
||
|
||
|
||
> 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "000000",
|
||
"msg": "成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"deviceId": 1572495474971721732,
|
||
"accessId": "2733417620",
|
||
"deviceSn": "aaaa213",
|
||
"deviceName": "aaaaa11111",
|
||
"productId": 1546827935855644565,
|
||
"productName": "产品名称1",
|
||
"productCode": "产品型号1",
|
||
"productType": "RTU",
|
||
"devTemplateId": 1560452823795662850,
|
||
"deviceTemplateName": "1123",
|
||
"protocolId": 1546826432547205121,
|
||
"protocolName": "水文演示协议",
|
||
"protocolVersion": "1.0.2",
|
||
"tenantId": 0,
|
||
"tenantName": "四信物联网",
|
||
"applicationIds": "288827602469126144",
|
||
"applicationNames": "四信设备管家",
|
||
"createTime": "2022-09-21 15:58:31",
|
||
"remark": "",
|
||
},
|
||
{
|
||
"deviceId": 1567426163248783362,
|
||
"accessId": "2020120412",
|
||
"deviceSn": "2020120412",
|
||
"deviceName": "GNSS-2020120412",
|
||
"productId": 1567424956237144066,
|
||
"productName": "GNSS",
|
||
"productCode": "GNSS",
|
||
"productType": "RTU",
|
||
"devTemplateId": 1567425926018949122,
|
||
"deviceTemplateName": "GNSS",
|
||
"protocolId": 1554016358570147842,
|
||
"protocolName": "gnss协议",
|
||
"protocolVersion": "1.0.0",
|
||
"tenantId": 0,
|
||
"tenantName": "四信物联网",
|
||
"applicationIds": "288827602469126144",
|
||
"applicationNames": "四信设备管家",
|
||
"createTime": "2022-09-07 16:14:53",
|
||
"remark": ""
|
||
},
|
||
{
|
||
"deviceId": 1567352553125502978,
|
||
"accessId": "5332035228",
|
||
"deviceSn": "0907001",
|
||
"deviceName": "0907001设备",
|
||
"productId": 1557978718232174594,
|
||
"productName": "0812产品",
|
||
"productCode": "0812001",
|
||
"productType": "DTU",
|
||
"devTemplateId": 1557979401714982914,
|
||
"deviceTemplateName": "0812模板",
|
||
"protocolId": 1556949634725105665,
|
||
"protocolName": "测试水文协议新脚本",
|
||
"protocolVersion": "1.0.0",
|
||
"tenantId": 0,
|
||
"tenantName": "四信物联网",
|
||
"applicationIds": "288827602469126144",
|
||
"applicationNames": "四信设备管家",
|
||
"createTime": "2022-09-07 11:22:23"
|
||
}
|
||
],
|
||
"count": 10,
|
||
"pageSize": 3,
|
||
"curPage": 1
|
||
},
|
||
"requestId": "5e8e8a34-ca28-4fab-a0cc-3c12182103ab"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
### 返回数据结构
|
||
|
||
| 名称 | 类型 | 说明 |
|
||
| -------------------- | ------ | ------------ |
|
||
| » deviceId | long | 设备id |
|
||
| » accessId | string | accessId |
|
||
| » deviceSn | string | 设备sn号 |
|
||
| » deviceName | string | 设备名 |
|
||
| » productId | long | 产品id |
|
||
| » productName | string | 产品名 |
|
||
| » productCode | string | 产品编码 |
|
||
| » productType | string | 产品类型 |
|
||
| » devTemplateId | long | 设备模板 |
|
||
| » deviceTemplateName | string | 设备模板名 |
|
||
| » protocolId | long | 协议id |
|
||
| » protocolName | string | 协议名 |
|
||
| » protocolVersion | string | 协议版本 |
|
||
| » tenantId | long | 租户id |
|
||
| » tenantName | string | 租户名 |
|
||
| » applicationIds | string | 设备归属应用 |
|
||
| » createTime | string | 创建时间 |
|
||
| » remark | string | 描述 |
|
||
|
||
## 获取设备物模型列表
|
||
|
||
/api/v1/deviceManage/deviceModel
|
||
|
||
根据设备ID、查询设备的要素元数据信息列表
|
||
|
||
### 请求参数
|
||
|
||
| 名称 | 位置 | 类型 | 必选 | 说明 |
|
||
| ------------- | ------ | ---------- | ---- | ---------- |
|
||
| deviceIdList | body | List<Long> | true | 设备id集合 |
|
||
| applicationId | body | long | true | 应用id |
|
||
| Sign_Info | header | string | true | none |
|
||
|
||
body参数请求示例：
|
||
|
||
```
|
||
{
|
||
"deviceIdList": [
|
||
1547038348406239234,
|
||
1567426163248783362,
|
||
1563092155278852099,
|
||
1564134138410176513,
|
||
1567352553125502978
|
||
],
|
||
"tenantId": "0",
|
||
"applicationId": "288827602469126144"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
> 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "000000",
|
||
"msg": "成功",
|
||
"data": [
|
||
{
|
||
"deviceId": 1563092155278852099,
|
||
"deviceSn": "112",
|
||
"deviceName": "112233",
|
||
"factors": [
|
||
{
|
||
"factorId": 1561642831273615361,
|
||
"identifier": "ac",
|
||
"identifierCn": "断面面积",
|
||
"unit": "m²",
|
||
"dataType": "number",
|
||
"accuracy": 2,
|
||
"createTime": "2022-08-22 17:14:00"
|
||
},
|
||
{
|
||
"factorId": 1561642831273615362,
|
||
"identifier": "ai",
|
||
"identifierCn": "瞬时气温",
|
||
"unit": "℃",
|
||
"dataType": "number",
|
||
"accuracy": 1,
|
||
"createTime": "2022-08-22 17:14:00"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"deviceId": 1567352553125502978,
|
||
"deviceSn": "0907001",
|
||
"deviceName": "0907001设备",
|
||
"factors": [
|
||
{
|
||
"factorId": 1564455265940111371,
|
||
"identifier": "ac",
|
||
"identifierCn": "断面面积",
|
||
"unit": "m²",
|
||
"dataType": "number",
|
||
"accuracy": 2,
|
||
"createTime": "2022-08-30 11:29:36"
|
||
},
|
||
{
|
||
"factorId": 1564455265940111372,
|
||
"identifier": "ai",
|
||
"identifierCn": "瞬时气温",
|
||
"unit": "℃",
|
||
"dataType": "number",
|
||
"accuracy": 1,
|
||
"createTime": "2022-08-30 11:29:36"
|
||
},
|
||
{
|
||
"factorId": 1564455265940111373,
|
||
"identifier": "c",
|
||
"identifierCn": "瞬时水温",
|
||
"unit": "℃",
|
||
"dataType": "number",
|
||
"accuracy": 1,
|
||
"createTime": "2022-08-30 11:29:36"
|
||
},
|
||
{
|
||
"factorId": 1564455265982054421,
|
||
"identifier": "ns",
|
||
"identifierCn": "开机台数",
|
||
"unit": "台",
|
||
"dataType": "number",
|
||
"accuracy": 0,
|
||
"createTime": "2022-08-30 11:29:36"
|
||
},
|
||
{
|
||
"factorId": 1564455265982054422,
|
||
"identifier": "p1",
|
||
"identifierCn": "1小时时段降水量",
|
||
"unit": "mm",
|
||
"dataType": "number",
|
||
"accuracy": 1,
|
||
"createTime": "2022-08-30 11:29:36"
|
||
},
|
||
{
|
||
"factorId": 1564455265982054423,
|
||
"identifier": "p2",
|
||
"identifierCn": "2小时时段降水量",
|
||
"unit": "mm",
|
||
"dataType": "number",
|
||
"accuracy": 1,
|
||
"createTime": "2022-08-30 11:29:36"
|
||
}
|
||
],
|
||
"requestId": "876f2a34-9cfe-4021-a867-ebeee5296876"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
### 返回数据结构
|
||
|
||
| 名称 | 类型 | 必选 | 约束 | 说明 |
|
||
| --------------- | -------- | ---- | ---- | ------------ |
|
||
| » deviceId | long | true | none | 设备id |
|
||
| » deviceSn | String | true | none | 设备sn号 |
|
||
| » deviceName | string | true | none | 设备名 |
|
||
| » factors | [object] | true | none | 要素集合 |
|
||
| »» factorId | string | true | none | 要素id |
|
||
| »» identifier | string | true | none | 要素标识 |
|
||
| »» identifierCn | string | true | none | 要素名称 |
|
||
| »» unit | null | true | none | 要素计量单位 |
|
||
| »» dataType | string | true | none | 要素数据类型 |
|
||
| »» accuracy | Integer | true | none | 要素精度 |
|
||
| »» createTime | | | | 创建时间 |
|
||
|
||
# 设备管家云第三方服务-数据中台
|
||
|
||
## 获取设备最新数据
|
||
|
||
/api/v1/dataCenter/deviceUpToData
|
||
|
||
产品信息的列表分页查询
|
||
|
||
### 请求参数
|
||
|
||
| 名称 | 位置 | 类型 | 必选 | 说明 |
|
||
| --------------- | ------ | ------------ | ----- | ---------------------------------------------- |
|
||
| applicationId | body | long | true | 应用id |
|
||
| deviceIdList | body | List<Long> | true | 设备集合id |
|
||
| selectFieldList | body | List<String> | false | 查询所需设备的数据所对应的字段，为空则查询所有 |
|
||
| templateId | body | long | true | 模板id |
|
||
| Sign_Info | header | string | true | none |
|
||
|
||
body参数请求示例：
|
||
|
||
```
|
||
{
|
||
"deviceIdList": [
|
||
1560516975124287489
|
||
],
|
||
"templateId": "1560475203354497026",
|
||
"tenantId": "0",
|
||
"applicationId": "288827602469126144"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
> 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "000000",
|
||
"msg": "成功",
|
||
"data": [
|
||
{
|
||
"tt": "2022-08-19 10:45",
|
||
"fl": 29.0,
|
||
"m50": 28.9,
|
||
"m30": 28.9,
|
||
"deviceId": "1560516975124287489",
|
||
"m10": 28.9,
|
||
"uc": "29",
|
||
"mst": 28.9,
|
||
"qa": 28.92,
|
||
"ue": "29",
|
||
"us": 28.9,
|
||
"ed": 28.9,
|
||
"st": "8120970688",
|
||
"gtp": 28.9,
|
||
"c": 28.9,
|
||
"ej": 28.9,
|
||
"m60": 28.9,
|
||
"ai": 28.9,
|
||
"m40": 28.9,
|
||
"m20": 28.9,
|
||
"va": 28.92,
|
||
"q": 28.92,
|
||
"tbname": "template_1560475203354497026_1560516975124287489",
|
||
"vj": 28.92,
|
||
"pn05": 0.0,
|
||
"ph": 28.92,
|
||
"pj": 0.0,
|
||
"z": null,
|
||
"vt": 12.16,
|
||
"ts": "2022-08-19 18:45:02"
|
||
}
|
||
],
|
||
"requestId": "fc09a4b7-f094-47c4-bcd7-78a7fb0af07a"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
### 返回数据结构
|
||
|
||
| 名称 | 类型 | 说明 |
|
||
| ------ | ------------- | ------------ |
|
||
| » ts | Timestamp | 设备上报时间 |
|
||
| » 其他 | string/double | 设备上报数据 |
|
||
|
||
## 获取设备历史数据分页
|
||
|
||
/api/v1/dataCenter/deviceData
|
||
|
||
根据设备ID、时间段查询设备的要素历史数据信息分页
|
||
|
||
### 请求参数
|
||
|
||
| 名称 | 位置 | 类型 | 必选 | 说明 |
|
||
| --------------- | ------ | ---------------- | ----- | ---------------------------------------------- |
|
||
| applicationId | body | long | true | 应用id |
|
||
| pageSize | body | int | true | 分页每页大小 |
|
||
| pageNum | body | int | true | 分页当前页 |
|
||
| deviceId | body | String | true | 设备id |
|
||
| templateId | body | long | true | 模板id |
|
||
| selectFieldList | body | List<String> | false | 查询所需设备的数据所对应的字段，为空则查询所有 |
|
||
| startTs | body | long(13位时间戳) | false | 开始时间 |
|
||
| endTs | body | long(13位时间戳) | false | 结束时间 |
|
||
| Sign_Info | header | string | true | none |
|
||
|
||
body参数请求示例：
|
||
|
||
```
|
||
{
|
||
"templateId": "1560475203354497026",
|
||
"deviceId": 1560516975124287489,
|
||
"pageSize": 20,
|
||
"pageNum":1,
|
||
"tenantId": "0",
|
||
"applicationId": "288827602469126144"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
> 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "000000",
|
||
"msg": "成功",
|
||
"data": {
|
||
"pageNum": 1,
|
||
"pageSize": 20,
|
||
"size": 0,
|
||
"total": 408,
|
||
"list": [
|
||
{
|
||
"tt": "2022-08-19 10:45",
|
||
"fl": 29.0,
|
||
"m50": 28.9,
|
||
"m30": 28.9,
|
||
"m10": 28.9,
|
||
"uc": "29",
|
||
"mst": 28.9,
|
||
"qa": 28.92,
|
||
"ue": "29",
|
||
"us": 28.9,
|
||
"ed": 28.9,
|
||
"st": "8120970688",
|
||
"gtp": 28.9,
|
||
"c": 28.9,
|
||
"ej": 28.9,
|
||
"m60": 28.9,
|
||
"ai": 28.9,
|
||
"m40": 28.9,
|
||
"m20": 28.9,
|
||
"va": 28.92,
|
||
"q": 28.92,
|
||
"vj": 28.92,
|
||
"pn05": 0.0,
|
||
"ph": 28.92,
|
||
"pj": 0.0,
|
||
"z": null,
|
||
"vt": 12.16,
|
||
"ts": "2022-08-19 18:45:02"
|
||
},
|
||
{
|
||
"tt": "2022-08-19 10:45",
|
||
"fl": 29.0,
|
||
"m50": 28.8,
|
||
"m30": 28.8,
|
||
"m10": 28.8,
|
||
"uc": "29",
|
||
"mst": 28.8,
|
||
"qa": 28.79,
|
||
"ue": "29",
|
||
"us": 28.8,
|
||
"ed": 28.8,
|
||
"st": "8120970688",
|
||
"gtp": 28.8,
|
||
"c": 28.8,
|
||
"ej": 28.8,
|
||
"m60": 28.8,
|
||
"ai": 28.8,
|
||
"m40": 28.8,
|
||
"m20": 28.8,
|
||
"va": 28.79,
|
||
"q": 28.79,
|
||
"vj": 28.79,
|
||
"pn05": 0.0,
|
||
"ph": 28.79,
|
||
"pj": 0.0,
|
||
"z": null,
|
||
"vt": 12.16,
|
||
"ts": "2022-08-19 18:44:34"
|
||
},
|
||
{
|
||
"tt": "2022-08-19 10:10",
|
||
"fl": 30.0,
|
||
"m50": 30.4,
|
||
"m30": 30.4,
|
||
"m10": 30.4,
|
||
"uc": "30",
|
||
"mst": 30.4,
|
||
"qa": 30.37,
|
||
"ue": "30",
|
||
"us": 30.4,
|
||
"ed": 30.4,
|
||
"st": "8120970688",
|
||
"gtp": 30.4,
|
||
"c": 30.4,
|
||
"ej": 30.4,
|
||
"m60": 30.4,
|
||
"ai": 30.4,
|
||
"m40": 30.4,
|
||
"m20": 30.4,
|
||
"va": 30.37,
|
||
"q": 30.37,
|
||
"vj": 30.37,
|
||
"pn05": 0.0,
|
||
"ph": 30.37,
|
||
"pj": 0.0,
|
||
"z": null,
|
||
"vt": 12.16,
|
||
"ts": "2022-08-19 18:10:01"
|
||
},
|
||
{
|
||
"tt": "2022-08-19 10:05",
|
||
"fl": 30.0,
|
||
"m50": 30.3,
|
||
"m30": 30.3,
|
||
"m10": 30.3,
|
||
"uc": "30",
|
||
"mst": 30.3,
|
||
"qa": 30.27,
|
||
"ue": "30",
|
||
"us": 30.3,
|
||
"ed": 30.3,
|
||
"st": "8120970688",
|
||
"gtp": 30.3,
|
||
"c": 30.3,
|
||
"ej": 30.3,
|
||
"m60": 30.3,
|
||
"ai": 30.3,
|
||
"m40": 30.3,
|
||
"m20": 30.3,
|
||
"va": 30.27,
|
||
"q": 30.27,
|
||
"vj": 30.27,
|
||
"pn05": 0.0,
|
||
"ph": 30.27,
|
||
"pj": 0.0,
|
||
"z": null,
|
||
"vt": 12.16,
|
||
"ts": "2022-08-19 18:05:00"
|
||
}
|
||
]
|
||
},
|
||
"requestId": "6ac3dfec-3394-4b96-8716-3c5e199e9ffb"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
### 返回数据结构
|
||
|
||
| 名称 | 类型 | 必选 |
|
||
| ------ | ------------- | ------------ |
|
||
| » ts | Timestamp | 设备上报时间 |
|
||
| » 其他 | string/double | 设备上报数据 |
|
||
|
||
|
||
|
||
## 获取设备状态
|
||
|
||
/api/v1/dataCenter/deviceStatus
|
||
|
||
根据设备ID、查询设备在线状态
|
||
|
||
### 请求参数
|
||
|
||
| 名称 | 位置 | 类型 | 必选 | 说明 |
|
||
| --------- | ------ | ---------------- | ----- | -------- |
|
||
| deviceId | body | string | true | 设备id |
|
||
| endTs | body | date(13位时间戳) | false | 结束时间 |
|
||
| Sign_Info | header | string | true | none |
|
||
|
||
body参数请求示例：
|
||
|
||
```
|
||
{
|
||
"deviceId":"1560516975124287489"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
> 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "000000",
|
||
"msg": "成功",
|
||
"data": {
|
||
"deviceId": null,
|
||
"online": 1,
|
||
"ts": "2022-08-19 20:38:43.246",
|
||
"duration": 0
|
||
},
|
||
"requestId": "2c3aa2cb-0ac8-4412-8d04-2ea36e532c9f"
|
||
}
|
||
```
|
||
|
||
|
||
|
||
### 返回数据结构
|
||
|
||
| 名称 | 类型 | 必选 | 约束 | 说明 |
|
||
| ---------- | ------- | ---- | ---- | -------------------- |
|
||
| » deviceId | long | true | none | 设备id |
|
||
| » online | integer | true | none | 在线状态 在线1 离线0 |
|
||
| » ts | string | true | none | 设备状态上报时间 |
|
||
| » duration | integer | true | none | 持续时间（单位分钟） |
|
||
|
||
##
|