实时数据接口

1. 根据设备id读取设备所有的点位数据

  • 请求语法
GET http://your-ip:9700/equipment/{id}/data/all
  • 请求参数
参数名称 类型 是否必选 位置 描述
id String 是 path 设备id
  • 响应结构
参数名称 类型 描述
code Number HTTP状态码。返回200表示成功，返回其它状态码表示失败。
message String 附加信息
data Object 点位数据信息存储其中
data.[key] any 属性键值对形式，key表示属性标识符，value标识实时读取到的值 ， 如"electric_current": 12.3 表示电流属性值为12.3

value数据类型根据实际类型进行数据返回，比如int类型数据返回整数值，bool类型返回bool值
data._type string 设备编码
data.name string 设备名称
data.id string 设备id
data.timestamp datetime 数据采集时间戳
data._status object 存放的是读取失败属性的错误信息，如果没有失败属性，_status对象为空
data._status.[key] object 失败属性标识符

示例中的equipment_health表示为设备健康度)
data._status.[key].respFailCategory string 错误类型，包括连接，读取，转换等异常分类
data._status.[key].code string 错误信息
data._status.[key].detail string 错误详情 ，可以为空

说明:

  1. 采用 key:value 键值对传输数据时，可以大大降低数据的传输量，在大量数据传输的情况的下，性能优势明显，处理数据也能带来便捷性
  2. 外部调用服务调用这个接口时，如果要访问数据，有两种方式
    1） 可以定义对象，直接讲Json数据序列化成对象，通过对象直接进行访问
    2） 通过Json直接用传入key的方式获取需要的数据，伪代码示例如下：
// 获取返回结果的data数据
JsonNode data = response.data

String fieldName = "identify" // 要获取的属性标识符
if (data.has(fieldName)）{
    // 属性读取成功
   Integer value = data.get(fieldName).asInt() // 这里假设该属性为int类型进行数据读取
  
   // 后续的处理
   ...
} else {
   // 属性读取失败
   JsonNode statusData = data.get("_status")
   
   // 获取失败信息
   JsonNode failResp = data.get(fieldName)
   if (failResp != null) {
       failResp.get("code").asText() // 错误信息 
        failResp.get("respFailCategory").asText() // 错误分类
   }
}

respFailCategory属性失败类型表

分类名称 说明
连接 错误发生在和设备建立的过程
设备 错误发生在设备本身
读取 错误发生在属性读取的阶段
数据转换 错误发生在数据转换的阶段
计算 错误发生在数据计算的阶段
写入 错误发生在属性写入的阶段
未知异常 未覆盖的类型

code属性错误信息描述表

错误名称 说明
正确
连接异常 未成功与设备建立连接通道
服务连接失败
设备未连接
连接未配置
地址未定义 属性地址在设备端未进行定义
禁止访问 设备端禁止属性的访问
不支持的操作
访问超时
错误的地址格式 属性地址为非法的格式
服务错误
远程服务忙
远程服务错误
没有值返回 设备端未返回数据值
错误的返回数据 返回的数据类型与属性定义的类型不匹配
错误的数据类型
错误的请求数据
表达式错误 属性配置的表达式计算错误
枚举转换错误 枚举类型的属性进行枚举值转换时发生错误
未知错误

请求示例

  • 响应示例

下面以如下设备为例，说明接口返回数据格式

设备ID 名称 编码
7155869383728828416 左前门-12-转台 ZT0001

该设备下有如下4个属性：

属性名称 属性标识 类型
电流 electric_current 32位浮点数
运行状态 running_status 布尔值
设备类型 equipment_type 设备状态
设备健康度 equipment_health 32位整数

请求：

curl -X GET "http://192.168.10.12:9700/equipment/7069178636166762496/data/all" -H "accept: */*"

响应数据：

{
    "data": {
        "electric_current": 12.3,     // 电流属性值，键值对形式，key表示属性标识符，value标识实时读取到的值
        "running_status":  true,      // 运行状态属性值
        "equipment_type": "T1",       // 设备类型属性值 
        "_status": {                  // _status中存放的是读取失败属性的错误信息，如果没有失败属性，_status对象为空
           "equipment_health": {                 // 表示设备健康度读取结果失败
                "respFailCategory": "读取",       // 表示失败分类，详见下面属性失败类型表
                "code": "错误的地址格式",           // 表示错误的信息，详见下面属性错误描述表
                "detail": null,                  // 错误详细信息
            }
        }
        "_type": "ZT0001",                 // 设备编码
        "name": "左前门-12-转台",            // 设备名称
        "id": "7155869383728828416",       // 设备在IoT系统中的唯一ID，雪花算法生成
        "timestamp": "2022-01-13T10:01:02.217+08:00" // 数据时间戳
    },
    "code": number,
    "message": String
}

2. 根据设备编码code读取设备所有的点位数据

  • 请求语法
GET http://your-ip:9700/equipment/{code}/data-by-code/all
  • 请求参数
参数名称 类型 是否必选 位置 描述
code String 是 path 设备编码
  • 响应示例
{
    "data": {
        "fieldCode1": "string"|boolean|number, // 数据值与类型对应
        "fieldCode2": "string"|boolean|number, // 数据值与类型对应
        "_status": {
        	"fieldCode3": {
                "respFailCategory": "string",
                "code": "string",
                "detail": "string"
            }
        }
        "_type": "string",
        "name": "string",
        "id": "string",
        "timestamp": "date"
    },
    "code": number,
    "message": String
}
  • 响应结构
参数名称 类型 描述
code Number HTTP状态码。返回200表示成功，返回其它状态码表示失败。
message String 附加信息
data Object 点位数据信息存储其中
data.fieldCode1 Object fieldCode1 点位的数据值，数据值类型由该点位类型决定

(fieldCode1代指点位标识符)
data.fieldCode2 Object fieldCode2 点位的数据值，数据值类型由该点位类型决定

(fieldCode2代指点位标识符)
data._type string 设备编码
data.name string 设备名称
data.id string 设备id
data.timestamp datetime 当前时间
data._status object 对于异常点位的记录均在此处
data._status.fieldCode3 object 异常点位编码fieldCode3

(fieldCode3代指点位标识符)
data._status.fieldCode3.respFailCategory string 异常类型，包括连接，读取，转换等异常分类
data._status.fieldCode3.code string 异常编码
data._status.fieldCode3.detail string 异常详情

请求示例

请求：

curl -X GET "http://192.168.10.12:9700/equipment/testEquipment5301/data-by-code/all" -H "accept: */*"

响应：

{
  "data": {
    "main_axle_speed": 1940,
    "_status": {
      "test1": {
        "respFailCategory": "读取",
        "code": "错误的地址格式",
        "detail": null
      }
    },
    "running_status": false,
    "_type": "testEquipment5301",
    "name": "rxt测试设备5301",
    "id": "7069178636166762496",
    "timestamp": "2023-05-31T10:39:27.334+08:00"
  },
  "code": 200,
  "message": null
}

3. 读取单个设备的单个点位数据

  • 请求语法
GET http://your-ip:9700/equipment/{code}/field-by-code/{fieldName}
  • 请求参数
参数名称 类型 是否必选 位置 描述
code String 是 path 设备编码
fieldName string 是 path 点位编码
  • 响应示例
{
  "data": "23.5",
  "code": 200,
  "message": ""
}
  • 响应结构
参数名称 类型 描述
code Number HTTP状态码。返回200表示成功，返回其它状态码表示失败。
message String 附加信息
data Object 点位数据信息存储其中，若点位读取失败则返回Null

请求示例

请求：

curl -X GET "http://192.168.10.12:9700/equipment/testEquipment5301/field-by-code/test1" -H "accept: */*"

响应

{
  "data": true,
  "code": 200,
  "message": null
}

4. 读取单个设备的多个点位数据

  • 请求语法
POST /equipment/{code}/fields-by-code
根据设备code、fieldNames的值读取Field列表的参数值
参数名称 类型 是否必选 位置 描述
code String 是 path 设备编码
fieldNames string[] 是 body 属性编码列表
  • 响应语法
{
    "data": {
        "fieldCode1": "string"|boolean|number, // 数据值与类型对应
        "fieldCode2": "string"|boolean|number, // 数据值与类型对应
        "_status": {
        	"fieldCode3": {
                "respFailCategory": "string",
                "code": "string",
                "detail": "string"
            }
        }
        "_type": "string",
        "name": "string",
        "id": "string",
        "timestamp": "date"
    },
    "code": number,
    "message": String
}
  • 响应参数
参数名称 类型 描述
code Number HTTP状态码。返回200表示成功，返回其它状态码表示失败。
message String 附加信息
data Object 点位数据信息存储其中
data.fieldCode1 Object fieldCode1 点位的数据值，数据值类型由该点位类型决定

(fieldCode1代指点位标识符)
data.fieldCode2 Object fieldCode2 点位的数据值，数据值类型由该点位类型决定

(fieldCode2代指点位标识符)
data._type string 设备编码
data.name string 设备名称
data.id string 设备id
data.timestamp datetime 当前时间
data._status object 对于异常点位的记录均在此处
data._status.fieldCode3 object 异常点位编码fieldCode3

(fieldCode3代指点位标识符)
data._status.fieldCode3.respFailCategory string 异常类型，包括连接，读取，转换等异常分类
data._status.fieldCode3.code string 异常编码
data._status.fieldCode3.detail string 异常详情

请求示例

请求

curl -X POST "http://192.168.10.12:9700/equipment/testEquipment5301/fields-by-code" -H "accept: */*" -H "Content-Type: application/json" -d "[ \"main_axle_speed\",\"running_status\",\"test1\"]"

响应

{
  "data": {
    "main_axle_speed": 1740,
    "_status": {
      "test1": {
        "respFailCategory": "读取",
        "code": "错误的地址格式",
        "detail": null
      }
    },
    "running_status": true,
    "_type": "testEquipment5301",
    "name": "rxt测试设备5301",
    "id": "7069178636166762496",
    "timestamp": "2023-05-31T10:47:44.371+08:00"
  },
  "code": 200,
  "message": null
}
2024-03-26
关注慧程公众号
© 2024 HiperM³ 产品帮助中心 版权所有 沪ICP备16004401号-1
1