管理 API

@cz 最后修改于 2020-08-30 22:22:08 rev.5516 - 最近修改

管理 API

概述

位置 (location) 能帮助分组管理设备，可以代表一个具体的物理位置（通常是室内位置），也可以是虚拟位置。

API 前缀

https://{domain-name}/v2/device/

版本

V2.1

作者

ChengZhen (zhen_cheng@sae.com.hk)

修改历史

2019/5/29

根据最新实现完善 API 定义
完善部分 API expand 查询详情

2018/8/2

基本属性添加最大长度一列

2018/7/27

/floor/get 添加 expand 参数, 可以展开查询返回 room
/floor/list 返回内容中的 room 要求返回 scope 属性

建筑

建筑表示一个地理位置，它通常会包含一到多个楼层。

建筑基本属性

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	true	ObjectId	-	建筑 ID
code	true	String	32	编号
description	-	String	100	简单描述
lat	true	Number	90	纬度
lng	true	Number	180	经度
location	-	Object	-	位置信息
metadata	-	Object	-	键值对元数据
name	true	String	32	显示名称
ownerId	-	ObjectId	-	所属的公司的 ID
scope	-	GeoJSON	-	建筑物显示范围坐标
type	true	String	32	类型
weight	true	Number	-	排序权值

位置信息

code 位置代码
province 省份
city 地级市
district 区或县
address 详细地址

创建一个新的建筑

POST /building/add

请求参数

NAME	REQUIRED	TYPE	DESCRIPTION
description	-	String	简单描述
code	-	String	编号
lat	-	Number	纬度
lng	-	Number	经度
name	true	String	显示名称
ownerId	-	ObjectId	所属的公司的 ID
location	-	Object	位置信息
metadata	-	Object	键值对元数据
coordinates	-	String	建筑物显示范围坐标,
type	-	String	建筑物类型

coordinates 格式为: lng1:lat1,lng2:lat2,lng3:lat3...

响应结果:

返回创建的建筑的信息

{
    "id": String,
    "ownerId": String,
    "description": String,
    "lat": Number,
    "lng": Number,
    "name": String,
    "scope": Object,
    "metadata": Object
}

查询指定建筑

POST /building/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	建筑 ID
expand	-	String	是否展开查询

响应结果:

返回指定的建筑的属性

{
    "id": String,
    "ownerId": String,
    "scope": {
        "type": "Polygon",
        "coordinates": [[[x1,y1],[x2,y2]]]
    },
    "description": String,
    "image": String,
    "lat": Number,
    "lng": Number,
    "name": String
}

返回指定的建筑的属性（expand=all)

{
    "id": String,
    "ownerId": String,
    "scope": {
        "type": "Polygon",
        "coordinates": [[[x1,y1],[x2,y2]]]
    },
    "description": String,
    "image": String,
    "lat": Number,
    "lng": Number,
    "name": String,
    "floors": [{
        "id": String,
        "name": String,
        "rooms": [{
            "id": String,
            "name": String
        }]
    }]
}

修改建筑属性

POST /building/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	建筑 ID
description	-	String	简单描述
lat	-	Number	纬度
lng	-	Number	经度
name	-	String	显示名称
ownerId	-	ObjectId	所属的公司的 ID
metadata	-	Object	键值对元数据
coordinates	-	String	建筑相对原点坐标

coordinates 格式为: lng1:lat1,lng2:lat2,lng3:lat3...

响应结果:

返回修改后的建筑的属性

{
    "id": String,
    "ownerId": String,
    "scope": Object,
    "description": String,
    "image": String,
    "lat": Number,
    "lng": Number,
    "name": String
}

删除一个建筑

POST /building/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	建筑 ID

响应结果:

返回删除的建筑的信息

{
    "id": String,
    "ownerId": String,
    "scope": Object,
    "description": String,
    "lat": Number,
    "lng": Number,
    "name": String
}

查询建筑列表

GET /building/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	id	排序字段名
q	String	-	搜索条件字符串
q.name	String	-	模糊搜索建筑物名称
expand	String	none	是否展开, 可以是 `none`, `floor`, `all`

示例:

GET /building/list?expand=none&q=name~=test

响应结果:

返回包含建筑信息的列表

{
    "total": Number,
    "buildings": [{
        "id": String,
        "ownerId": String,
        "scope": {
            "type": "Polygon",
            "coordinates": [[[x1,y1],[x2,y2]]]
        },
        "description": String,
        "lat": Number,
        "lng": Number,
        "name": String
    }]
}

返回包含建筑和楼层信息的列表, (expand=floor)

{
    "total": Number,
    "buildings": [{
        "id": String,
        "ownerId": String,
        "scope": {
            "type": "Polygon",
            "coordinates": [[[x1,y1],[x2,y2]]]
        },
        "description": String,
        "lat": Number,
        "lng": Number,
        "name": String,
        "floors": [{
            "id": String,
            "name": String
        }]
    }]
}

返回包含建筑,楼层和房间信息的列表, (expand=all)

{
    "total": Number,
    "buildings": [{
        "id": String,
        "ownerId": String,
        "scope": {
            "type": "Polygon",
            "coordinates": [[[x1,y1],[x2,y2]]]
        },
        "description": String,
        "lat": Number,
        "lng": Number,
        "name": String,
        "floors": [{
            "id": String,
            "name": String,
            "rooms": [{
                "id": String,
                "name": String
            }]
        }]
    }]
}

统计

GET /building/stat

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
level	-	String	统计级别
type	-	String	设备类型

响应结果:

返回统计信息

{
    "onwerId": String,
    "type": "ChargingPile",
    "cities": {
        "福州市": {
            "alert": 0,
            "buildings": 2,
            "fault": 0,
            "gateway": 0,
            "online": 0,
            "total": 28,
            "charging": 0
        }
    }
}

楼层

楼层表示一个室内的平面地理位置，比如一个楼层。它属于一个建筑，且通常包含多个房间等等。

楼层基本属性

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	true	ObjectId	-	楼层 ID
name	true	String	32	楼层名
description	-	String	200	简单描述
image	-	String	200	地图图片 URL
map	-	Object	-	地图信息
width	-	Number	-	楼层地图宽度 (单位:米)
height	-	Number	-	楼层地图高度 (单位:米)
building	-	Object	-	所属建筑信息
metadata	-	Object	-	元数据
buildingId	-	ObjectId	-	所属建筑 ID
type	-	String	32	地图类型

地图类型

Name	Description
floor	楼层室内地图
building	建筑物概览地图
district	园区等区域地图

地图参数

image

地图图片 URL 地址, 可以是绝对地址, 或相对地址.

width

地图图片对应的实际宽度, 单位为米.

height

地图图片对应的实际高度, 单位为米.

scale

地图比例, 单位像素的真实长度,真实距离/像素 (单位:m/px)

map 地图文件元数据

NAME	TYPE	DESCRIPTION
size	Number	地图文件大小, 单位为字节
hash	String	地图文件 Hash 值
type	String	地图文件类型，如 `png`, `jpeg`, `svg` 等
updated	Date	地图文件最后更新日期

注意:

地图图片总是以左下角为原点 (0,0).

在 UI 界面中, 用户只需要上传地图图片并指定地图宽度即可, 其他参数将自动推算:

// 使用图片 API 获取图片的像素宽度和高度
var width_pixel  = pixel_of_width(image_data);  // 1000
var height_pixel = pixel_of_height(image_data); // 800

// 推算出 scale 和 height 的值
var scale  = width / width_pixel;   // 36.7 / 1000 = 0.0367
var height = height_pixel * scale;  // 29.36

// 假设地图上有一个点: (367, 111), 对应的现实相对位置为:
var point = [367 * scale, 111 * scale] ~= [13.5, 4.1];

// 假设现实相对位置有一个点: (21.5, 8.4), 对应的地图位置为:
var point = [21.5 / scale, 8.4 / scale] ~= [586, 229];

创建一个新的楼层

POST /floor/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
name	true	String	楼层名
description	-	String	简要描述
image	-	String	地图图片 URL
width	-	Number	楼层地图宽度 (单位:米)
height	-	Number	楼层地图高度 (单位:米)
buildingId	-	ObjectId	所属建筑 ID
type	-	String	地图类型

响应结果:

返回创建的楼层的信息

{
    "id": String,
    "buildingId": String,
    "description": String,
    "height": Number,
    "image": String,
    "name": String,
    "type": String,
    "scale": Number,
    "width": Number
}

查询指定楼层

POST /floor/get

请求参数:

NAME	REQUIRED	TYPE	DEFAULT	DESCRIPTION
id	true	ObjectId	-	楼层 ID
expand	-	String	none	是否展开查询, 可选: `none`,`all`, `thing`, `room`

响应结果:

返回指定楼层的信息

{
    "id": String,
    "building": {
        "id": String,
        "name": String
    },
    "description": String,
    "height": Number,
    "image": String,
    "name": String,
    "scale": Number,
    "type": String,
    "map": Object,
    "width": Number
}

返回指定楼层并展开所有房间的信息

{
    "id": String,
    "building": {
        "id": String,
        "name": String
    },
    "description": String,
    "height": Number,
    "image": String,
    "name": String,
    "scale": Number,
    "type": String,
    "width": Number,
    "rooms": [{
        "id": String,
        "name": String,
        "scope": {
            "type": "Polygon",
            "coordinates": [[[x1,y1],[x2,y2]]]
        }
    }]
}

返回指定楼层并展开所有信息

{
    "id": String,
    "building": {
        "id": String,
        "name": String
    },
    "description": String,
    "height": Number,
    "image": String,
    "name": String,
    "scale": Number,
    "type": String,
    "width": Number,
    "rooms": [{
        "id": String,
        "name": String,
        "scope": {
            "type": "Polygon",
            "coordinates": [[[x1,y1],[x2,y2]]]
        }
    }],
    "streams": {},
    "things": []
}

修改楼层属性

POST /floor/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	楼层 ID
name	-	String	楼层名
description	-	String	简要描述
image	-	String	楼层地图图片 URL
width	-	Number	楼层地图宽度 (单位:米)
height	-	Number	楼层地图高度 (单位:米)
buildingId	-	ObjectId	所属建筑 ID
type	-	String	地图类型
map	-	String	地图文件信息 JSON 字符串

响应结果:

返回修改后的楼层的信息

{
    "id": String,
    "buildingId": String,
    "description": String,
    "height": Number,
    "image": String,
    "name": String,
    "scale": Number,
    "type": String,
    "map": Object,
    "width": Number
}

删除一个楼层

POST /floor/del

请求参数

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	楼层 ID
force	-	Boolean	强制删除关联房间(默认:false)

响应结果:

返回删除的楼层的信息

{
    "id": String,
    "buildingId": String,
    "description": String,
    "height": Number,
    "image": String,
    "name": String,
    "scale": Number,
    "type": String,
    "width": Number
}

查询楼层列表

GET /floor/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	id	排序字段名
q	String	-	搜索条件字符串
q.name	String	-	模糊搜索楼层名称
buildingId	ObjectId	-	所属建筑 ID
type	String	floor	地图类型
expand	String	none	是否展开, 可以是 `none`, `all`

示例:

GET /floor/list?type=floor&q=name~=test

响应结果:

返回包含楼层信息的列表

{
    "total": Number,
    "floors": [{
        "id": String,
        "building": {
            "id": String,
            "name": String
        },
        "description": String,
        "height": Number,
        "image": String,
        "name": String,
        "scale": Number,
        "type": String,
        "map": Object,
        "width": Number
    }]
}

返回包含楼层和房间信息的列表 (expand=all)

{
    "total": Number,
    "floors": [{
        "id": String,
        "building": {
            "id": String,
            "name": String
        },
        "description": String,
        "height": Number,
        "image": String,
        "name": String,
        "scale": Number,
        "type": String,
        "map": Object,
        "width": Number,
        "rooms": [{
            "id": String,
            "name": String,
            "scope": {
                "type": "Polygon",
                "coordinates": [[[x1,y1],[x2,y2]]]
            }
        }],
        "things": [],
        "streams": {}
    }]
}

房间

房间表示楼层（室内地图）内的一个局部区域位置，也可以表示一个虚拟设备。

房间基本属性

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	true	ObjectId	-	房间 ID
name	true	String	32	房间名
type	true	String	32	类型
description	-	String	200	房间简介
floorId	-	ObjectId	-	楼层 ID
floor	-	Object	-	所属楼层信息
metadata	-	Object	-	元数据
scope	-	GeoJSON	-	房间显示范围坐标,

scope - 坐标范围

scope 使用 GeoJSON 数据格式

https://tools.ietf.org/html/rfc7946

type - 类型:

Polygon 坐标为 4 个或多个点的数组组成的闭环
LineString 坐标为两个或多个点的数组
MultPoint 坐标为多个点的数组
Point 坐标为单个点

创建一个新的房间

POST /room/add

NAME	REQUIRED	TYPE	DESCRIPTION
name	true	String	房间名
type	-	String	类型
description	true	String	房间简介
floorId	true	ObjectId	楼层 ID
coordinates	-	String	房间相对原点坐标

coordinates 格式为: x1:y1,x2:y2,x3:y3,x4:y4

响应结果:

{
    "id": String,
    "name": String,
    "type": String,
    "floorId": String,
    "description": String,
    "scope": {
        "type": "Polygon",
        "coordinates": [[[x1,y1], [x2,y2]]]
    }
}

查询指定房间

POST /room/get

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	String	房间 ID
expand	-	String	是否展开查询: none, all

响应结果:

返回指定房间的信息

{
    "id": String,
    "name": String,
    "type": String,
    "description": String,
    "floor": {
        "id": String,
        "name": String,
        "building": {
            "id": String,
            "name": String            
        }
    },
    "scope": {
        "type": "Polygon",
        "coordinates": [[[x1,y1],[x2,y2]]]
    }
}

返回指定房间以及该区域内所有设备的信息(expand=all)

{
    "id": String,
    "name": String,
    "description": String,
    "floor": {
        "id": String,
        "name": String,
        "building": {
            "id": String,
            "name": String            
        }
    },
    "things": [],
    "streams": {},
    "scope": {
        "type": "Polygon",
        "coordinates": [[[x1,y1],[x2,y2]]]
    }
}

修改房间属性

POST /room/update

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	String	房间 ID
name	-	String	房间名
type	-	String	类型
description	-	String	房间简介
floorId	-	ObjectId	楼层 ID
coordinates	-	String	房间相对原点坐标

coordinates 参考: 12:45,43.4:34.0,34:59.4,49.1:12

响应结果:

返回修改后的房间的信息

{
    "id": String,
    "name": String,
    "type": String,
    "description": String,
    "coordinates": String,
    "floorId": String,
    "scope": {
        "type": "Polygon",
        "coordinates": [[[x1,y1], [x2,y2]]]
    }
}

删除一个房间

GET /room/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	房间 ID

响应结果:

返回删除的房间的信息

{
    "id": String,
    "name": String,
    "type": String,
    "description": String,
    "floorId": String,
    "scope": {
        "type": "Polygon",
        "coordinates": [[[x1,y1], [x2,y2]]]
    }
}

查询房间列表

GET /room/list

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	id	排序字段名
q	String	-	搜索条件字符串
q.name	String	-	模糊搜索房间名称
floorId	String	-	楼层 ID
expand	-	String	是否展开查询: none, all

示例:

GET /room/list?q=name~=test

响应结果:

返回包含房间信息的列表

{
    "total": Number,
    "rooms": [{
        "id": String,
        "name": String,
        "type": String,
        "description": String,
        "scope": {
            "type": "Polygon",
            "coordinates": [[[x1,y1], [x2,y2]]]
        },
        "floorId": String
    }]
}

返回包含房间和设备信息的列表(expand=all)

{
    "total": Number,
    "rooms": [{
        "id": String,
        "name": String,
        "description": String,
        "scope": {
            "type": "Polygon",
            "coordinates": [[[x1,y1], [x2,y2]]]
        },
        "things": [],
        "streams": {},
        "floorId": String
    }]
}

地图

下载地图图片

GET /floor/image

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	楼层 ID

响应结果:

返回包含地图图片文件的内容

支持浏览器缓存机制

上传地图图片

POST /upload/map

请求格式:

Content-Type: multipart/form-data

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
file	true	Byte[]	地图图片文件内容

响应结果:

返回上传结果

{
    "url": String,      // URL 地址
    "name": String,     // 原始文件名
    "etag": String,     // 文件的 hash 值
    "mimetype": String, // 图片类型: `jpg`, `png`
    "size": String      // 图片大小
}

地图文件

图片文件上传后, 统一保存到如下路径:

${base}/device/public/upload/map/:hash.jpg

其中 hash 为图片文件的 MD5 hash 值.

在数据库中将只保留这个图片的相关路径:

/upload/map/:hash.jpg

权限列表

表示系统支持并可以分配的权限列表:

注意如果没有 device 系统权限时不可以查看 device 服务下的所有信息.

NAME	DESCRIPTION	NOTE
device.location	表示所有操作位置信息的权限,	没有权限时仅且可以查看所有位置信息