REST API

driver-box 提供了一套常用的 REST API，方便开发者结合自身需求将 driver-box 与自身的边缘应用集成起来。

所有接口的响应格式为：

{
  "success": true,
  "errorCode": 200,
  "errorMsg": "",
  "data": ... //{} 或者 []
}

设备服务

单点读取

请求方式： GET

请求路径： /api/v1/device/readPoint

接口描述：

设备的单点读取接口会通过 通讯插件 发起真实的读操作指令，待指令下发成功后再从设备影子中提取最新点位值。

如果插件本身不支持主动的读取操作，则会返回错误。
如果被读取的设备不支持同步 IO（例如：发送一个 MQTT 的读指令，其响应时间是不确定），则从影子中获取的数据可能不是最新值。

请求参数

字段名	字段类型	是否必填	字段描述
id	string	是	设备id
point	string	是	点位名

响应参数

字段名	字段类型	字段描述
value	string/int/float	点位值，字段类型取决于点位类型

示例

curl http://127.0.0.1:8081/api/v1/device/readPoint?id=swtich-1&point=onOff

{
    "success": true,
    "errorCode": 200,
    "errorMsg": "",
    "data": 1
}

{
    "success": false,
    "errorCode": 500,
    "errorMsg": "the protocol does not support getting connector",
    "data": null
}

单点写入

请求方式： GET/POST

请求路径： /api/v1/device/writePoint

接口描述： 设备的单点写入接口会通过 通讯插件 发起真实的写操作指令。

请求参数

字段名	字段类型	是否必填	字段描述
id	string	是	设备id
point	string	是	点位名
value	string/int/float	是	点位值，字段类型取决于点位类型

响应参数

字段名	字段类型	字段描述
-	-	-

示例

curl http://127.0.0.1:8081/api/v1/device/writePoint?id=swtich-1&point=onOff&value=1

{
    "success": true,
    "errorCode": 200,
    "errorMsg": "",
    "data": null
}

{
    "success": false,
    "errorCode": 500,
    "errorMsg": "point is readonly, can not write",
    "data": null
}

批量写入

请求方式： POST

请求路径： /api/v1/device/writePoint

接口描述： 设备的批量写入接口会通过 通讯插件 发起真实的写操作指令。

请求参数

字段名	字段类型	是否必填	字段描述
id	string	是	设备id
values	array[]	是	点位值数组，数组元素为对象。对象格式为：`{"name": "点位名", "value": "点位值"}`

响应参数

字段名	字段类型	字段描述
-	-	-

示例

设置空调的开关、模式及温度

curl -X POST -H "Content-Type: application/json" -d \
    '{"id":"ac_13","values":[{"name":"onOff","value":1},{"name":"runMode","value":1},{"name":"tempSetting","value":28}]}' \
    http://127.0.0.1:8081/api/v1/device/writePoints

{
    "success": true,
    "errorCode": 200,
    "errorMsg": "",
    "data": null
}

{
    "success": false,
    "errorCode": 500,
    "errorMsg": "unknown device",
    "data": null
}

设备影子

获取全部设备数据

请求方式： GET

请求路径： /api/v1/shadow/all

接口描述： 获取当前网关中运行着的全部设备影子数据。

请求参数

字段名	字段类型	是否必填	字段描述
-	-	-	-

响应参数

字段名	字段类型	字段描述
data	Device[]	设备影子列表

Device模型结构
DevicePoint模型结构

字段名	字段类型	字段描述
id	string	设备id
points	DevicePoint []	设备点位列表
online	boolean	设备是否在线
ttl	string	设备影子数据过期时间
disconnect_times	int	设备断线次数
updated_at	string	设备影子数据更新时间

字段名	字段类型	字段描述
name	string	点位名
value	string	点位值
updated_at	int	最近一次影子更新时间
write_time	int	最近一次点位写入时间

示例

请求
响应

curl http://127.0.0.1:8081/api/v1/shadow/all

{
    "success": true,
    "errorCode": 200,
    "errorMsg": "",
    "data": [
        {
            "id": "swtich-1",
            "points": [
                {
                    "name": "onOff",
                    "value": 1,
                    "updated_at": "2024-06-05 16:27:41",
                    "write_time": "0001-01-01 00:00:00"
                }
            ],
            "online": true,
            "ttl": "5m0s",
            "disconnect_times": 0,
            "updated_at": "2024-06-05 16:27:41"
        },
        {
            "id": "swtich-2",
            "points": [
                {
                    "name": "onOff",
                    "value": 1,
                    "updated_at": "2024-06-05 16:27:34",
                    "write_time": "0001-01-01 00:00:00"
                }
            ],
            "online": true,
            "ttl": "5m0s",
            "disconnect_times": 0,
            "updated_at": "2024-06-05 16:27:34"
        }
    ]
}

查询某个设备数据

请求方式： GET

请求路径： /api/v1/shadow/device

接口描述： 获取当前网关中指定设备 ID 的影子数据

请求参数

字段名	字段类型	是否必填	字段描述
id	string	是	设备 ID

响应参数

字段名	字段类型	字段描述
data	Device	设备影子

示例

请求
响应

curl http://127.0.0.1:8081/api/v1/shadow/device?id=swtich-1

{
    "success": true,
    "errorCode": 200,
    "errorMsg": "",
    "data": {
        "id": "swtich-1",
        "points": [
            {
                "name": "onOff",
                "value": 1,
                "updated_at": "2024-06-05 16:27:41",
                "write_time": "0001-01-01 00:00:00"
            }
        ],
        "online": false,
        "ttl": "5m0s",
        "disconnect_times": 0,
        "updated_at": "2024-06-05 16:32:41"
    }
}

查询某个设备点位数据

请求方式： GET

请求路径： /api/v1/shadow/devicePoint

接口描述： 获取当前网关中指定设备的某个点位影子数据

请求参数

字段名	字段类型	是否必填	字段描述
id	string	是	设备 ID
point	string	是	点位名

响应参数

字段名	字段类型	字段描述
data	DevicePoint	设备影子

示例

请求
响应

curl http://127.0.0.1:8081/api/v1/shadow/devicePoint?id=swtich-1&point=onOff

{
    "success": true,
    "errorCode": 200,
    "errorMsg": "",
    "data": {
        "name": "onOff",
        "value": 1,
        "updated_at": "2024-06-05 16:27:41",
        "write_time": "0001-01-01 00:00:00"
    }
}