空间API

更新时间：2020-06-15 15:18:08

概述

空间服务提供空间实例的管理服务，以及用户与空间的管理服务。

本文档分为两部分：

第一部分: 数据定义，是空间的基本数据接口。

第二部分: 接口文档，说明接口的入参、出参和示例。

接口分为四大类：

空间管理的相关接口

接口名	简介
创建顶层空间	创建顶层空间，顶层空间是所有空间的入口，相当于数据结构中树根节点。
创建子空间	创建子空间,顶层空间下所有空间都称为子空间。
删除空间	删除空间，目前仅支持空间下无子空间以及设备的删除。
更新空间	更新空间，目前仅支持单个空间的更新。
获取空间	获取空间信息，支持批量，目前最多一次查询100个。
查询子空间	获取子空间，目前仅支持获取下一层的子空间。
查询租户根空间列表	租户信息是根据云云对接所使用AppKey信息获得。

用户与空间的相关接口

接口名	简介
绑定用户与空间	绑定用户与空间，目前仅做关联关系的绑定，无权限判断。
解绑用户与空间	将用户与空间的绑定关系删除。
查询用户的空间	分页接口，查询用户的所有空间。
查询空间的用户	分页接口，查询空间的所有用户。
解绑空间的所有用户	将空间上绑定的所有用户解绑。
解绑用户的所有空间	将用户的所有空间解绑。

设备与空间的相关接口

接口名	简介
绑定设备与空间	建立设备与空间的逻辑关系。
解绑设备与空间	解除设备与空间的逻辑关系。
查询空间的设备	查询空间下的关联设备。
查询空间的设备摘要信息	查询空间下的关联设备（不返回设备TSL属性信息）
获取设备的空间	获取设备的关联空间信息。

虚拟设备的相关接口

接口名	简介
绑定虚拟设备和空间	建立虚拟设备与空间的逻辑关系。
删除空间的虚拟设备	解除虚拟设备与空间的逻辑关系。
查询空间虚拟设备	查询空间下的关联虚拟设备。
替换空间虚拟设备	用真实设备替换空间下的虚拟设备。

数据定义

SpaceInfo

名称	类型	备注
id	String	空间ID
name	String	空间名称
attribute	String	空间属性，业务自定义
descrpition	String	空间描述，业务自定义
gmtCreate	String	空间创建日期
gmtModified	String	空间修改日期
typeCode	String	空间类型代码，枚举字符串，具体定义见:链接
typeName	String	空间类型名称,具体定义见:链接
hasChild	Boolean	是否包含子空间
hasDeviceChild	Boolean	空间内是否包含设备
rootSpaceId	String	根空间ID
parentId	String	父空间ID. from V1.0.3
pathIds	String	空间路径上的空间ID列表，包含空间的自身ID. from V1.0.3

typeCode & typeName定义

typeCode	typeName
building	幢
area	区域
parking_space_import_and_export	车位进出口
public_area	公共区域
space_unit	空间单元
unit	单元
floor	楼层
default	根空间
house	房屋
room	房间

接口文档

创建顶层空间

顶层空间是所有空间的入口，相当于数据结构中树的根节点。

/home/paas/space/root/create

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceInfo	JSONObject	是	空间信息

spaceInfo对象

名称	类型	是否必填	备注
name	String	是	空间名称
attribute	String	否	空间属性，业务自定义
typeCode	String	是	空间类型代码，枚举字符串，具体定义见:链接
description	String	否	空间描述，业务自定义

出参

返回结果使用通用结果类型封装，下表是通用结果类型中data域的详细说明

参数	类型	备注
data	String	新增空间ID

示例

示例1

假如用户A(id为"idxxx")想创建一个名字为"绿地中心"的根空间，可以使用如下示例:

请求示例

{
    "operator":{
        "hid":"idxxx",
        "hidType":"OPEN"
    },
    "spaceInfo":{
        "name":"绿地中心",
        "typeCode":"default"
    }
}

返回示例

{
  "code": 200,
  "data": "rootSpaceId1",
  "message":"success"
}

创建子空间

顶层空间下所有空间都称为子空间

/home/paas/space/sub/create

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceInfo	JSONObject	是	空间信息

spaceInfo对象

名称	类型	是否必填	备注
name	String	是	空间名称
description	String	否	空间描述
attribute	String	否	空间属性，业务自定义
rootSpaceId	String	是	顶层空间ID
parentId	String	是	父空间ID
typeCode	String	是	空间类型代码,具体定义见:链接

出参

返回结果使用通用结果类型，data域是字符串，见下表的说明：

参数	类型	备注
data	String	新增空间ID

示例

示例1

假如用户A(id为"idxxx")想创建一个位于"绿地中心"(id: "xxx")，名字为"1101"的房屋，可以使用如下示例:

请求示例

{
    "operator":{
        "hid":"idxxx",
        "hidType":"OPEN"
    },
    "spaceInfo":{
        "name":"1101",
        "typeCode":"house",
        "rootSpaceId":"xxx",
        "parentId":"xxx"
    }
}

返回示例

{
  "code": 200,
  "data": "subSpaceId1"
  "message":"success"
}

删除空间

/home/paas/space/delete

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	空间ID

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	Integer	实际删除的空间。

示例

示例1

假如用户A(id:"hidxxx") 删除id为"xxx"的空间，可使用如下示例：

请求示例

{
    "operator":{
        "hid":"hidxxx",
        "hidType":"OPEN"
    },
    "spaceId":"xxx"
}

返回示例

{
    "code":200,
    "data":1,
    "message":"success"
}

更新空间

/home/paas/space/update

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceInfo	JSONObject	是	空间信息

spaceInfo对象

名称	类型	是否必填	备注
spaceId	String	是	待更新的空间ID
description	String	否	空间描述
name	String	否	空间名称
attribute	String	否	空间属性，业务自定义

出参

返回结果使用通用结果类型，不使用data域，无值。

示例

示例1

用户A(id为"hidxxx")，需要更新空间id为"xxx"的空间信息，将其描述更改为"new description here", 可使用如下示例。

请求示例

{
    "operator":{"hid":"hidxxx"},
    "spaceInfo":{
        "description":"new description here",
          "spaceId":"0fb14444b"
    }
}

返回示例

{
  "code":200,
  "data": "",
  "message":"success"
}

获取空间

/home/paas/space/get

当前版本 1.0.3

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
rootSpaceId	String	否	顶层空间ID
spaceIdList	JSONArray	是	被查询的空间ID列表

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	空间信息数组，空间信息具体见spaceInfo定义:链接

示例

示例1

用户A(id为"hidxxx")，获取根空间"rootSpaceIdxxx"下"dda7e692dc7a4adf808393b1deb0ae34",的空间信息，可使用如下示例。

请求示例

{
    "operator":{
        "hid":"hidxxx",
        "hidType":"OPEN"
    },
    "rootSpaceId":"rootSpaceIdxxx",
    "spaceIdList":[
        "dda7e692dc7a4adf808393b1deb0ae34"
    ]
}

返回示例

{
    "code":200,
    "message":"success",
    "data":[
        {
            "gmtModified":1546366434000,
            "hasDeviceChild":false,
            "hasChild":false,
            "typeName":"房屋",
            "name":"xxx0e0a6773-39cf-470d-bd3c-17bbf77c6997",
            "description":"new descriptin herer",
            "id":"dda7e692dc7a4adf808393b1deb0ae34",
            "gmtCreate":1546366433000,
            "parentId":"227846892e844588a1b11d5c020a44e2",
            "typeCode":"house"
        }
    ]
}

查询子空间

/home/paas/space/sub/list

当前版本 1.0.3

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceQuery	JSONObject	是	子空间查询条件

spaceQuery定义

字段名	类型	是否必填	备注
spaceId	String	是	当前空间ID
rootSpaceId	String	是	顶层空间ID
pageNo	Integer	是	请求的页码, 默认1, 具体定义参考: 链接
pageSize	Integer	是	每页的记录数, 具体定义参考: 链接
name	String	否	按照空间名字检索，精确匹配
nameLike	String	否	按照空间名字检索，模糊匹配
typeCodeList	JSONArray	否	按照空间类型做检索

出参

返回结果使用通用结果类型，data域是分页查询结果对象（下表中的data是分页结果中的数据），见下表的详细说明

参数	类型	备注
data	JSONArray	空间信息数组，空间信息具体见spaceInfo定义:链接
total	Integer	数据总数
pageNo	Integer	每页的记录数, 具体定义参考: 链接
pageSize	Integer	每页的记录数, 具体定义参考: 链接

示例

示例1

用户A(id为"hidxxx")，获取根空间(id为"ed839f21c93542a28a6168e8c2b192c9")的子空间信息，可使用如下示例：

请求示例

{
    "operator":{
        "hid":"hidxxx",
        "hidType":"OPEN"
    },
    "spaceQuery":{
        "spaceId":"ed839f21c93542a28a6168e8c2b192c9",//查看根空间的子空间信息
        "rootSpaceId":"ed839f21c93542a28a6168e8c2b192c9"
    }
}

返回示例

{
  "data":[
        {
            "description":"new descriptin here",
            "gmtCreate":1548072045000,
            "gmtModified":1548072046000,
            "hasChild":false,
            "hasDeviceChild":false,
            "id":"b3f6b98aa7154a0da84b8abf88206fc7",
            "name":"xxx36e59d1e-384a-48ca-8445-2a1c78ea5312",
            "parentId":"ed839f21c93542a28a6168e8c2b192c9",
            "typeCode":"house",
            "typeName":"房屋"
        },
        {
            "gmtCreate":1548072046000,
            "gmtModified":1548072046000,
            "hasChild":false,
            "hasDeviceChild":false,
            "id":"025e076eda264942be7698b1c737c527",
            "name":"xxx808adf59-4e40-4422-9214-d674787a8782",
            "parentId":"ed839f21c93542a28a6168e8c2b192c9",
            "typeCode":"room",
            "typeName":"房间"
        }
    ],
    "pageNo":1,
    "pageSize":20,
    "total":2
}

示例2

用户A(id为"hidxxx")，获取根空间(id为"ed839f21c93542a28a6168e8c2b192c9")且类型是"house"的子空间信息，可使用如下示例：

请求示例

{
    "operator":{
        "hid":"hidxxx",
        "hidType":"OPEN"
    },
    "spaceQuery":{
        "pageNo":1,
        "pageSize":100,
        "spaceId":"ed839f21c93542a28a6168e8c2b192c9",//查看根空间的子空间信息
        "rootSpaceId":"ed839f21c93542a28a6168e8c2b192c9",
        "typeCodeList": ["house"]
    }
}

返回示例

"data": {
    "total": 2,
    "data": [
      {
        "editorId": null,
        "gmtModified": 1545639469000,
        "hasDeviceChild": false,
        "openId": null,
        "typeName": "房屋",
        "creatorId": null,
        "description": null,
        "gmtCreate": 1545639469000,
        "parentId": "7032a7c5828a43c78357b8c3ab83ecb1",
        "typeCode": "house",
        "rootSpaceId": null,
        "hasChild": false,
        "name": "nulluX",
        "id": "d577561fbe604188ad2a056c0c426622",
        "attribute": null,
        "usesCode": null
      },
      {
        "editorId": null,
        "gmtModified": 1548883789000,
        "hasDeviceChild": false,
        "openId": null,
        "typeName": "房屋",
        "creatorId": null,
        "description": null,
        "gmtCreate": 1547709791000,
        "parentId": "7032a7c5828a43c78357b8c3ab83ecb1",
        "typeCode": "house",
        "rootSpaceId": null,
        "hasChild": false,
        "name": "绑定虚拟设备的子空间ug",
        "id": "a88ff520339f47ac864c186072f8e2f7",
        "attribute": null
      }
    ],
    "pageNo": 1,
    "pageSize": 100
}

示例3

用户A(id为"hidxxx")，获取根空间(id为"ed839f21c93542a28a6168e8c2b192c9")且名字中包含"测试"的子空间信息，可使用如下示例：

请求示例

{
    "operator":{
        "hid":"hidxxx",
        "hidType":"OPEN"
    },
    "spaceQuery":{
        "pageNo":1,
        "pageSize":100,
        "spaceId":"ed839f21c93542a28a6168e8c2b192c9",//查看根空间的子空间信息
        "rootSpaceId":"ed839f21c93542a28a6168e8c2b192c9",
        "nameLike": "测试"
    }
}

返回示例

"data": {
    "total": 1,
    "data": [
      {
        "editorId": null,
        "gmtModified": 1550027688000,
        "hasDeviceChild": false,
        "openId": null,
        "typeName": "幢",
        "creatorId": null,
        "description": null,
        "gmtCreate": 1550027688000,
        "parentId": "7032a7c5828a43c78357b8c3ab83ecb1",
        "typeCode": "building",
        "rootSpaceId": null,
        "hasChild": false,
        "name": "测试的子空间",
        "id": "23f59decff74452f8e473cb0749328c5",
        "attribute": null
        "usesCode": null
      }
    ],
    "pageNo": 1,
    "pageSize": 100
}

查询租户根空间列表

租户信息是根据云云对接所使用AppKey信息获得。

/home/paas/space/root/list

当前版本 1.0.2

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceQuery	JSONObject	是	根空间查询条件

spaceQuery定义

字段名	类型	是否必填	备注
pageNo	Integer	是	请求的页码, 具体定义参考: 链接
pageSize	Integer	是	每页的记录数,具体定义参考: 链接

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	空间信息数组，空间信息具体见spaceInfo定义:链接
total	Integer	数据总数
pageNo	Integer	请求的页码, 具体定义参考: 链接
pageSize	Integer	每页的记录数, 具体定义参考: 链接

示例

示例1

用户A(id为"hidxxx")，获取所有的根空间，可使用如下示例:

请求示例

{
    "operator":{
        "hid":"hidxxx",
        "hidType":"OPEN"
    },
    "query":{
        "pageNo":1,
        "pageSize":20
    }
}

返回示例

{
    "code":200,
    "message":"success",
    "data":{
        "total":1,
        "data":[
            {
                "gmtModified":1546368041000,
                "hasDeviceChild":false,
                "hasChild":true,
                "typeName":"根空间",
                "name":"xxx34e859cd-b937-4c34-ad37-4772e743602a",
                "id":"ea08d72c333c488fa02b052665c3d7c0",
                "gmtCreate":1546368040000,
                "typeCode":"default"
            }
        ],
        "pageNo":1,
        "pageSize":20
    }
}

绑定用户与空间

用户与空间需要属于相同租户

/home/paas/user/space/bind

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
targetList	JSONArray	是	绑定用户信息, 具体定义见:链接
spaceId	String	是	空间ID

出参

返回结果使用通用结果类型，data域为空

示例

示例1

用户"1111299939433"想将用户"1111972077885"和"1111299939433"绑定到空间"d4c30a1a4f934fbea8fc2229504bf1d6",可使用如下示例:

请求示例

    {
    "spaceId":"d4c30a1a4f934fbea8fc2229504bf1d6",
    "targetList":[
        {
            "hid":"1111972077885",
            "hidType":"OPEN"
        },
        {
            "hid":"1111299939433",
            "hidType":"OPEN"
        }
    ],
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    }
}

返回示例

{
    "code":200,
    "id":"d7e21765-03f1-463a-8202-15e8a8815e14",
    "localizedMsg":"success",
    "message":"success"
}

解绑用户与空间

用户与空间需要属于相同租户

/home/paas/user/space/unbind

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
target	JSONObject	是	绑定用户信息, 具体定义见:链接
spaceId	String	是	空间ID

出参

返回结果使用通用结果类型，data域为空

示例

示例1

用户"1111299939433"想将用户"1111299939433"和空间"d4c30a1a4f934fbea8fc2229504bf1d6"解绑可使用如下示例:

请求示例

    {
    "spaceId":"d4c30a1a4f934fbea8fc2229504bf1d6",
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "target":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    }
}

返回示例

{
    "code":200,
    "id":"49e56685-2f50-4d6c-ac5e-3047f441d8b7",
    "localizedMsg":"success",
    "message":"success"
}

查询用户的空间

/home/paas/user/space/list

当前版本 1.0.1

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
target	JSONObject	是	绑定用户信息, 具体定义见:链接
userSpaceQuery	JSONObject	是	查询条件，具体定义链接

查询用户的空间userSpaceQuery定义

字段名	类型	备注
spaceType	String	空间类型代码，枚举字符串，具体定义见:链接
pageNo	Integer	请求的页码, 具体定义参考: 链接
pageSize	Integer	每页的记录数, 具体定义参考: 链接

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	空间ID数组
total	Integer	数据总数
pageNo	Integer	请求的页码, 具体定义参考: 链接
pageSize	Integer	每页的记录数, 具体定义参考: 链接

示例

示例1

用户"1111299939433"想查询用户"1111972077885"的绑定的空间列表可使用如下示例:

请求示例


{
    "userSpaceQuery":{
        "spaceType":"room",
        "pageNo":1,
        "pageSize":100
    },
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "target":{
        "hid":"1111972077885",
        "hidType":"OPEN"
    }
}

返回示例

{

    "data":[
        "d4c30a1a4f934fbea8fc2229504bf1d6"
    ],
    "pageNo":1,
    "pageSize":100,
    "total":1
}

查询空间的用户

/home/paas/space/user/list

当前版本

版本号	说明
1.0.0	初始版本，出参的空间用户用openId表示
2.0.0	出参的空间用户用hid和hidType表示（不单独返回openId）

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
target	JSONObject	是	绑定用户信息, 具体定义见:链接
userSpaceQuery	JSONObject	是	查询条件，具体定义链接

查询空间的用户userSpaceQuery定义

字段名	类型	备注
pageNo	Integer	请求的页码, 具体定义参考: 链接
pageSize	Integer	每页的记录数, 具体定义参考: 链接
spaceId	String	空间ID

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONArray	用户信息数组，用户信息参考定义链接
total	Integer	数据总数
pageNo	Integer	请求的页码, 具体定义参考: 链接
pageSize	Integer	每页的记录数, 具体定义参考: 链接

空间用户信息定义

1.0.0

参数	类型	备注
openId	String	用户openId
tenantId	String	用户所属B端租户ID

2.0.0

参数	类型	备注
hid	String	用户ID
hidType	String	用户类型

示例

示例1

用户"1111299939433"想查询空间"8d663b3761424d029aaaa533618e1a2a"绑定的用户可使用如下示例:

请求示例

    {
    "userSpaceQuery":{
        "spaceId":"8d663b3761424d029aaaa533618e1a2a",
        "pageNo":1,
        "pageSize":100
    },
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    }
}

返回示例

1.0.0

{
    "data":[
        {
            "openId":"1111972077885",
            "tenantId":"58753E7FE2E04F4DAB4EE5C2CEFAFE4C"
        },
        {
            "openId":"1111299939433",
            "tenantId":"58753E7FE2E04F4DAB4EE5C2CEFAFE4C"
        }
    ],
    "pageNo":1,
    "pageSize":100,
    "total":2
}

2.0.0

{
    "data":[
        {
            "hid":"1111972077885",
            "hidType":"OPEN"
        },
        {
            "hid":"1111299939433",
            "hidType":"OPEN"
        }
    ],
    "pageNo":1,
    "pageSize":100,
    "total":2
}

解绑空间的所有用户

/home/paas/space/allusers/unbind

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	空间ID

出参

返回结果使用通用结果类型，data域为空

示例

示例1

用户"1111299939433"想解绑空间"d4c30a1a4f934fbea8fc2229504bf1d6"的所有用户可使用如下示例:

请求示例

{
    "spaceId":"d4c30a1a4f934fbea8fc2229504bf1d6",
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    }
}

返回示例

{
    "code":200,
    "localizedMsg":"success",
    "message":"success"
}

解绑用户的所有空间

/home/paas/user/allspaces/unbind

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
target	JSONObject	是	绑定用户信息, 具体定义见:链接

出参

返回结果使用通用结果类型，data域为空

示例

示例1

用户"1111299939433"想将用户"1111972077885"所有空间关系解绑可使用如下示例:

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "target":{
        "hid":"1111972077885",
        "hidType":"OPEN"
    }
}

返回示例

{
    "code":200,
    "localizedMsg":"success",
    "message":"success"
}

绑定设备与空间

绑定设备与空间的逻辑关系。

使用空间接口创建空间后，空间可以与设备建立逻辑关系。

接口支持批量操作，可以实现：

一个空间与一个设备建立逻辑关系；

一个空间与多个设备建立逻辑关系。

/home/paas/device/space/bind

当前版本 1.0.1, 2.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	需要做绑定的空间ID
iotIdList	JSONArray	是	需要做绑定的设备ID列表，每次请求最多绑定20个设备

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
successCount	Integer	成功绑定的设备数；
batchResultMap	JSONObject	此参数在1.0.x版本的返回结果中出现。以键值对的形式提供每个设备的绑定结果： key：设备ID；value：以通用结果类型表示设备ID的绑定结果。
batchResultList	JSONObject	此参数在2.0.x版本的返回结果中出现。key：设备ID；result：以通用结果类型表示设备ID的绑定结果。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要绑定的空间ID为9e944d47a67a40e89773d1365e048cf6。这个空间是根空间，所以rootSpaceId的值与spaceId相同。否则rootSpaceId为实际空间的根空间ID。

要绑定的设备ID为tMbycP1picrKhT0HQDCk001034b510。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "spaceId": "9e944d47a67a40e89773d1365e048cf6",
  "iotIdList": [
    "tMbycP1picrKhT0HQDCk001034b510"
  ]
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "batchResultMap": {
      "tMbycP1picrKhT0HQDCk001034b510": {
        "code": 200,
        "message": "success"
      }
    },
    "successCount": 1
  }
}

解绑设备与空间

解除设备与空间的逻辑关系。

设备与空间建立逻辑关系后，可以使用这个接口解除它们的关系。

接口支持批量操作，可以实现：

解除一个空间与一个设备的逻辑关系；

解除一个空间与多个设备的逻辑关系。

/home/paas/device/space/unbind

当前版本 1.0.0, 2.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	需要做解绑的空间ID。
iotIdList	JSONArray	是	需要做解绑的目标设备ID列表，每次请求最多解绑20个设备。

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
successCount	Integer	成功解绑的设备数。
batchResultMap	JSONObject	此参数在1.0.x版本的返回结果中出现。以键值对的形式提供每个设备的绑定结果： key：设备ID；value：以通用结果类型表示设备ID的绑定结果。
batchResultList	JSONObject	此参数在2.0.x版本的返回结果中出现。key：设备ID；result：以通用结果类型表示设备ID的绑定结果。

示例

例：

的操作员的用户ID是1111299939433，使用了三方账号体系。

要解绑的空间ID为9e944d47a67a40e89773d1365e048cf6。这个空间是根空间，所以rootSpaceId的值与spaceId相同。否则rootSpaceId为实际空间的根空间ID。

要解绑的设备ID为tMbycP1picrKhT0HQDCk001034b510。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "spaceId": "9e944d47a67a40e89773d1365e048cf6",
  "iotIdList": [
    "tMbycP1picrKhT0HQDCk001034b510"
  ]
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "batchResultMap": {
      "tMbycP1picrKhT0HQDCk001034b510": {
        "code": 200,
        "message": "success"
      }
    },
    "successCount": 1
  }
}

查询空间的设备

查询空间下的设备列表。

查询与空间建立了逻辑关系的设备。建立空间与设备的逻辑关系使用“绑定设备与空间”接口。

可以通过includeSubSpace参数指定是否包含空间下子空间的设备。

查询结果是一维的设备列表，不包含空间的结构关系。

/home/paas/space/device/list

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
rootSpaceId	String	是	一级（顶层）空间ID
spaceId	String	是	空间ID
includeSubSpace	Boolean	是	是否查询子空间的设备 True 查询子空间 False 不查询子空间
pageInfo	JSONObject	否	设备分页查询参数，见“分页参数”定义。

出参

返回结果使用通用结果类型，data域是分页查询结果对象（下表中的data是分页结果中的数据），见下表的详细说明：

参数	类型	备注
data	JSONArray	分页的设备数据，见设备信息定义。
total	Integer	总条数
pageNo	Integer	分页页码
pageSize	Integer	分页大小

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要查询的空间ID为9e944d47a67a40e89773d1365e048cf6，要查询这个空间，以及子空间下的所有设备。

查询第1页数据，每页记录数为20。

接口返回1条记录，总记录数为1条。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "spaceId": "9e944d47a67a40e89773d1365e048cf6",
  "includeSubSpace": true,
  "pageQuery": {
    "pageNo": 1,
    "pageSize": 20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "iotId": "tMbycP1picrKhT0HQDCk001034b510",
        "spaceNamePath": "/根节点1/",
        "attributeList": [
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1547797068655,
            "attribute": "LightMode",
            "batchId": "ce354176212c47448b6a7e97e2c85705",
            "value": 0
          },
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1548036653624,
            "attribute": "LightSwitch",
            "batchId": "188cde35f2544526b9660abfc60b4b6a",
            "value": 1
          }
        ],
        "thingType": "DEVICE",
        "productKey": "a1mB9mXoz0q",
        "deviceName": "fordev",
        "productName": "带服务的灯_qw",
        "status": 1,
        "productImage": "https://img.alicdn.com/tps/TB1_I0aPXXXXXajXpXXXXXXXXXX-100-82.png",
        "nickName": "dev1",
        "lastOnlineTime": "2019-01-01 12:00:00"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

查询空间的设备摘要信息

查询空间下的设备列表，区别于查询空间的设备，该接口不需要rootSpaceId参数，且不返回设备属性信息。

查询与空间建立了逻辑关系的设备。建立空间与设备的逻辑关系使用“绑定设备与空间”接口。

可以通过includeSubSpace参数指定是否包含空间下子空间的设备。

查询结果是一维的设备列表，不包含空间的结构关系。

/home/paas/space/device/simple/query

当前版本 1.0.0

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	空间ID
includeSubSpace	Boolean	是	是否查询子空间的设备 True 查询子空间 False 不查询子空间
pageInfo	JSONObject	否	设备分页查询参数，见“分页参数”定义。

出参

返回结果使用通用结果类型，data域是分页查询结果对象（下表中的data是分页结果中的数据），见下表的详细说明：

参数	类型	备注
data	JSONArray	分页的设备数据，见设备信息定义。设备信息中不返回设备属性信息
total	Integer	总条数
pageNo	Integer	分页页码
pageSize	Integer	分页大小

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要查询的空间ID为9e944d47a67a40e89773d1365e048cf6，要查询这个空间，以及子空间下的所有设备。

查询第1页数据，每页记录数为20。

接口返回1条记录，总记录数为1条。

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "spaceId": "9e944d47a67a40e89773d1365e048cf6",
  "includeSubSpace": true,
  "pageQuery": {
    "pageNo": 1,
    "pageSize": 20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "iotId": "tMbycP1picrKhT0HQDCk001034b510",
        "spaceNamePath": "/根节点1/",
        "attributeList": [
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1547797068655,
            "attribute": "LightMode",
            "batchId": "ce354176212c47448b6a7e97e2c85705",
            "value": 0
          },
          {
            "iotId": "tMbycP1picrKhT0HQDCk001034b510",
            "gmtModified": 1548036653624,
            "attribute": "LightSwitch",
            "batchId": "188cde35f2544526b9660abfc60b4b6a",
            "value": 1
          }
        ],
        "thingType": "DEVICE",
        "productKey": "a1mB9mXoz0q",
        "deviceName": "fordev",
        "productName": "带服务的灯_qw",
        "status": 1,
        "productImage": "https://img.alicdn.com/tps/TB1_I0aPXXXXXajXpXXXXXXXXXX-100-82.png",
        "nickName": "dev1",
        "lastOnlineTime": "2019-01-01 12:00:00"
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

获取设备的空间

查询某根空间下与设备建立逻辑关系的空间列表。

/home/paas/device/space/get

当前版本 1.0.2

入参

参数	类型	必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	设备ID

出参

返回结果使用通用结果类型，data域是对象，见下表的详细说明：

参数	类型	备注
data	JSONObject	空间信息，具体见spaceInfo定义:链接

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

根空间ID： 9e944d47a67a40e89773d1365e048cf6

设备ID： tMbycP1picrKhT0HQDCk001034b510

请求参数如下：

请求示例

{
  "operator": {
    "hid":"1111299939433",
    "hidType":"OPEN"
  },
  "rootSpaceId": "9e944d47a67a40e89773d1365e048cf6",
  "iotId": "tMbycP1picrKhT0HQDCk001034b510"
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "spaceName": "根节点1",
    "attribute": "",
    "parentId": null,
    "description": "根节点1",
    "typeCode": "default",
    "typeName": "默认",
    "hasChild": 0,
    "hasDeviceChild": 1
  }
}

绑定虚拟设备和空间

虚拟设备相对于真实的物理设备而言，并不需要存在此类设备的实体。主要应用与人居的使用流程的解决方案。

例如： SI在后台portal的房屋内添加好虚拟设备，然后把房屋指派给施工人员，施工人员将真实的设备完成配网后，再将虚拟设备替换为真实设备，完成施工。

/home/paas/space/virtualdevice/bind

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	空间id
deviceInfoList	JSONArray	是	产品定义

deviceInfoList定义

字段名	类型	是否必填	备注
productKey	String	是	产品标示
nickName	String	是	设备别名，比如床头灯1

出参

返回结果使用通用结果类型，data域是结果列表，见下表的详细说明：

字段名	类型	备注
productKey	String	产品标示
nickName	String	设备别名
iotId	String	设备id
thingType	String	设备类型，虚拟设备为"VIRTUAL"

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要绑定的空间ID为9e944d47a67a40e89773d1365e048cf6。

要绑定的设备的PK=a1aGFrtGWLw，nickName=风扇，iotId=EbtNIco8t2Ju9Q8h

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433"
    },
    "deviceInfoList":[
        {
            "productKey":"a1aGFrtGWLw",
            "nickName":"xxx"
        }
    ],
    "spaceId":"9e944d47a67a40e89773d1365e048cf6"
}

返回示例

{
    "data":[
        {
            "productKey":"a1aGFrtGWLw",
            "nickName":"风扇",
            "iotId":"xxxx"
        }
    ]
}

删除空间的虚拟设备

该接口提供虚拟设备删除，不能删除真实设备。

/home/paas/space/virtualdevice/delete

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotIdList	JSONArray	是	虚拟设备id列表
spaceId	String	是	设备所在空间id

出参

IoT通用返回。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

设备的空间ID为9e944d47a67a40e89773d1365e048cf6。

要删除的虚拟设备ID为EbtNIco8t2Ju9Q8h

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "iotIdList":[
        "EbtNIco8t2Ju9Q8h"
    ],
    "spaceId":"9e944d47a67a40e89773d1365e048cf6"
}

返回示例

{
  "code": 200,
  "message": "success"
}

查询空间虚拟设备

查询空间下的虚拟设备。

/home/paas/space/virtualdevice/list

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
spaceId	String	是	空间id
condition	JSONObject	是	查询条件

condition定义

字段名	类型	是否必填	备注
pageNo	Integer	是	页码，见“分页参数”定义。
pageSize	Integer	是	分页大小，见“分页参数”定义。
productKey	String	否	产品品类

出参

参数	类型	备注
data	JSONArray	分页数据，见虚拟设备信息定义
total	Integer	总条数，见“分页参数”定义。
pageNo	Integer	分页页码，见“分页参数”定义。
pageSize	Integer	分页大小，见“分页参数”定义。

虚拟设备信息定义

名称	类型	备注
iotId	String	设备id
name	String	设备名
nickname	String	用户对设备设置的昵称
productKey	String	设备ProductKey

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要查询的空间ID为9e944d47a67a40e89773d1365e048cf6。

请求参数如下：

请求示例

{
  "operator":{"hid":"1111299939433", "hidType":"OPEN"},
   "spaceId":"9e944d47a67a40e89773d1365e048cf6", 
  "condition":{
      "pageNo":1,
      "pageSize":20
  }
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}

替换空间虚拟设备

实际安装施工中，SI使用配网完成的设备去替换虚拟设备。完成一个从后台设计，到安装施工的过程。

替换设备会继承虚拟设备的设备别名。

/home/paas/space/virtualdevice/replace

当前版本 1.0.0

入参

字段名	类型	是否必填	备注
operator	JSONObject	是	操作员，见“身份信息”定义。
iotId	String	是	实际设备，源设备
virtualIotId	String	是	虚拟设备，被替换设备
spaceId	String	是	空间id

出参

IoT通用返回。

示例

例：

当前的操作员的用户ID是1111299939433，使用了三方账号体系。

要查询的空间ID为9e944d47a67a40e89773d1365e048cf6。

实际设备ID为lrSPldlWpr4maJyE

虚拟设备ID为EbtNIco8t2Ju9Q8h

请求参数如下：

请求示例

{
    "operator":{
        "hid":"1111299939433",
        "hidType":"OPEN"
    },
    "spaceId":"9e944d47a67a40e89773d1365e048cf6",
    "virtualIotId":"EbtNIco8t2Ju9Q8h",
    "iotId":"lrSPldlWpr4maJyE"
}

返回示例

{
  "code": 200,
  "message": "success"
}