提供一组与用户相关的服务接口，客户端应用通过本组服务接口可以实现用户绑定设备列表信息的获取，同时可以实现设备和push通道的解绑操作。

用户和设备绑定关系

设备分享

用户和消息绑定关系

虚拟用户

获取用户绑定的设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/listBindingByAccount 1.0.8 获取用户绑定的设备列表 是

请求参数

参数 类型 必填 描述
thingType String 否 设备的类型：
  • VIRTUAL（虚拟设备）
  • VIRTUAL_SHADOW（虚拟影子设备）
  • WEB
  • APP
  • DEVICE（普通设备）
nodeType String 否 设备的节点类型，可取值包括：DEVICE，GATEWAY
isSubDevice Boolean 否 是否为子设备
  • true 表示获取子设备列表
  • false 表示获取非子设备（直连设备）列表
  • null 表示获取全部设备列表
归属在某一个网关设备下的设备称为子设备。注意该参数只对 2020.01.08 之后新绑定的子设备生效，该日期之前绑定的子设备数据不支持根据该字段过滤
pageNo Integer 是 分页页码，从1开始
pageSize Integer 是 分页大小，大于等于1，小于等于100

返回参数

参数 子参数 类型 描述
total - Long 满足条件的设备总数。
pageNo - Integer 分页页码
pageSize - Integer 分页大小
data - JSONArray 设备的详情列表
- identityId String 用户的身份ID
- iotId String 设备的 iotId，设备的唯一标识
- deviceName String 设备的名称
- productKey String 设备所属产品的 ProductKey
- productName String 设备所属产品的名称
- productImage String 设备所属产品的图标，如果未定义产品图标，该字段和 categoryImage 字段一致
- productModel String 设备所属产品的型号
- categoryImage String 设备所属产品品类的图标
- nickName String 设备的昵称，可为空
- netType String 设备的入网类型，可取值：
  • NET_LORA（LoRa）
  • NET_CELLULAR（GPRS）
  • NET_WIFI（ WiFi）
  • NET_ZIGBEE（ZigBee）
  • NET_ETHERNET（以太网）
  • NET_OTHER（其他）
- thingType String 设备的类型：
  • VIRTUAL（虚拟设备）
  • VIRTUAL_SHADOW（虚拟影子设备）
  • WEB
  • APP
  • DEVICE（普通设备）
- status Byte 设备的状态，可取值：0（未激活），1（在线），3（离线），8（禁用）
- owned Integer 设备和用户的关系，可取值：0（分享者），1（拥有者）
- nodeType String 设备的节点类型，可取值包括：DEVICE，GATEWAY
- identityAlias String 用户的显示名（ mobile 或 loginName 或 email）
- subDevice Boolean 标识是否为子设备，true：表示为子设备，false 或者 null：表示非子设备（为直连设备）
- gmtModified Date 修改时间（绑定时间）

示例

  • 请求示例 
    {
    "id":"xxx",
    "version":"1.0.0",
    "request":{
        "language":"zh-CN",
        "appKey":"xxx",
        "iotToken":"xxx",
        "apiVer":"1.0.0"
    },
    "params":{
        "isSubDevice":false,
        "pageNo":1,
        "pageSize":10
    }
}
  • 正常返回示例 
    {
    "id":"4de2c367-xxxx-xxxx-aa15-8c585e595d92",
    "code":200,
    "message":"success",
    "localizedMsg":null,
    "data":{
        "total":2,
        "pageNo":1,
        "pageSize":10,
        "data":[
            {
                "identityId":"xxx",
                "iotId":"edwB6TqvxxxxxxNa000100",
                "deviceName":"摄像头1",
                "productKey":"产品 pk",
                "productName":"产品名称",
                "productImage":"产品图片",
                "productModel":"产品型号",
                "categoryImage":"xxx",
                "nickName":"设备昵称",
                "netType":"NET_WIFI",
                "thingType":"DEVICE",
                "status":1,
                "owned":1,
                "nodeType":"DEVICE",
                "identityAlias":"133xxx",
                "subDevice":false,
                "gmtModified":"xxx"
            },
            {
                "identityId":"xxx",
                "iotId":"xadqskxxxxxx9h000100",
                "deviceName":"摄像头2",
                "productKey":"产品 pk",
                "productName":"产品名称",
                "productImage":"产品图片",
                "productModel":"产品型号",
                "categoryImage":"xxx",
                "nickName":"设备昵称",
                "netType":"NET_WIFI",
                "thingType":"DEVICE",
                "status":1,
                "owned":1,
                "nodeType":"DEVICE",
                "identityAlias":"133xxx",
                "subDevice":false,
                "gmtModified":"xxx"
            }
        ]
    }
}

根据设备获取绑定关系

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/listBindingByDev 1.0.2 根据设备获取绑定关系 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
iotId String 是 设备ID
pageNo Int 是 当前页号，从1开始的页序号
pageSize Int 是 页大小，单页的item数量上限
owned Int 否 表示设备绑定的类型：0：作为分享设备被他人分享；1：设备拥有者；null：所有

返回参数

参数 子键 类型 描述
total - Integer 云端总数
pageNo - Integer 当前页号
pageSize - Integer 页大小
data - List<> 用户绑定设备列表
- identityId String 用户的身份ID
- iotId String 设备的iotId
- productKey String 设备的productKey
- deviceName String 设备的deviceName
- productName String 设备的产品名称
- productImage String 设备的产品图片
- productModel String 设备的产品型号
- categoryImage String 品类图标
- nickName String 用户对设备的昵称，用户通过setDeviceNickName设置的昵称
- netType String 设备入网类型
- thingType String 设备的类型：
  • VIRTUAL（虚拟设备）
  • VIRTUAL_SHADOW（虚拟影子设备）
  • WEB
  • APP
  • DEVICE（普通设备）
- nodeType String 设备的节点类型：DEVICE，GATEWAY
- status Byte 设备的状态 0：未激活 ；1：在线；3：离线；8：禁用
- owned Byte 0：分享者；1：拥有者
- identityAlias String 用户的显示名：mobile，loginName或email
- gmtModified Date 修改绑定的时间
- description String 描述

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxxf62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "pageNo":1,
        "pageSize":10,
        "iotId":"fy2Z1oZFxxxxxxxx101edf00"

    },
    "version": "1.0"
}
  • 正常返回示例 
    {
  "code": 200,
  "data": [
    {
      "productModel": "testProduct",
      "iotId": "fy2Z1oZFxxxxxxx00101edf00",
      "netType": "NET_WIFI",
      "identityId": "5082opabf5192xxxxxxxx980ae6f6093",
      "thingType": "DEVICE",
      "nodeType": "DEVICE",
      "productKey": "a1xxxxJNb",
      "deviceName": "b65cb59xxxxxxxx08592cd695fb",
      "productName": "0dxxxx95",
      "status": 3
    }
  ],
  "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
}
  • 异常返回示例 
    {
 "code":2064,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"need authorize to bind"
}

设备列表排序

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/sortDevices 1.0.2 对设备进行排序 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 子键 类型 必填 描述
sortDeviceDTOList - List<> 是 设备排序有变化的数据
- iotId String 是 设备ID
- fromOrder Integer 是 排序变化前设备的位置
- toOrder Integer 是 排序变化后设备的位置

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxxf6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "sortDeviceDTOList":[
            {"iotId": "Z75bTa4dxxxxxxxxRW001056af10",
              "fromOrder": 1,
              "toOrder":  3            
            },
            {"iotId": "faHSHCOxxxxxxxxxZQoN00108dcf00",
              "fromOrder": 2,
              "toOrder":  1            
            },
            {"iotId": "Spb4eatt1Lxxxxxxxx00108a4410",
              "fromOrder": 3,
              "toOrder":  2            
            }
         ] 
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2000,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"sortDevice param error!"
}

生成分享用的二维码

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/generateShareQrCode 1.0.2 生成设备分享用的二维码，支持批量设备，有效期30分钟 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
iotIdList List< String > 否 设备iotId列表，列表最大个数为20，该参数不能为空

返回参数

参数 类型 描述
qrKey String 生成的二维码key

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049cxxxxxxxx6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "iotIdList":["xxxx"],
        "sceneIdList":["xxxx"]
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "data": {
        "qrKey": "xxxxxx"
    },
    "id": "6ec222eb-87fc-xxxx-xxxx-351df196ceb3"
}
  • 异常返回示例 
    {
  "code":2081,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"scene not found by sceneId"
}

通过扫描二维码绑定设备或者场景

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/scanBindByShareQrCode 1.0.6 通过扫描二维码绑定设备或者场景，绑定后是普通成员 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
homeId Strong 是 家的ID，家的唯一标识
qrKey String 是 扫描的二维码key

返回参数

参数 类型 描述
ScanShareQrCodeV2Resp Object 绑定的设备或者场景ID列表
ScanShareQrCodeV2Res结构
参数 类型 描述
iotIdList List 绑定的设备或者场景ID列表

示例

  • 请求示例 
    {
    "request":{
        "iotToken":"109049c80xxxxxxxx6f62e29a3ba",
        "apiVer":"1.0.2"
    },
    "id":150821281****,
    "params":{
        "homeId":"50f5opxxxxxxxxxxxxf28104512",
        "qrKey":"xxxx"
    },
    "version":"1.0"
}
  • 正常返回示例 
    {
    "code":200,
    "message":"success",
    "localizedMsg":"",
    "data":{
        "iotIdList":[
            "CKuX1xxxxxxxxxxxxxxxx00100",
            "vbiM2xxxxxxxxxxxxxxxx00100"
        ]
    },
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2067,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"qrKey not exist"
}

设备分享给指定的用户

定义描述

path 版本 描述 是否需要鉴权
/uc/shareDevicesAndScenes 1.0.7 通过指定手机、邮箱或具体identityId的方式将设备和场景分享给其他人；对于使用自有账号体系的用户，在智能生活平台一般不会保存对应账号的手机和邮箱等信息，此时可以借助自有账号ID和智能生活平台identityId映射关系（用户可自行存储该映射关系），来实现该分享接口的调用；每次分享最多可以分享20个设备 是，客户端SDK需启用用户身份的鉴权

请求参数

参数 类型 必填 描述
iotIdList List< String > 是 设备iotId列表，每次最多分享20个
targetIdentityId String 否 分享目标身份ID（用户属性对/身份ID 两者须至少有一个）
accountAttr String 否 唯一标识目标用户的属性（如：手机号、邮箱的值）
accountAttrType String 否 唯一标识目标用户的属性类型（如：手机号、邮箱等），手机号：MOBILE；邮箱：EMAIL
mobileLocationCode String 否 手机号区位码，如86

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxx5f6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "accountAttr":"1365663****",
        "accountAttrType": "MOBILE",
         "iotIdList":[
                        "inqfGrp0xxxxxxxxpD00100fd600",
                        "ETytXLwjxxxxxxxx4qG0010629e00"   
                     ]
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
   "code": 200,
   "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2064,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"need authorize to bind"
}

获取共享通知列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/getShareNoticeList 1.0.7 获取共享通知列表 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
pageNo Int 是 当前页号，从1开始的页序号
pageSize Int 是 页大小，单页的item数量上限
groupBy String 否 是否按照批次的方式来获取通知列表。可取值为 NONE, BATCH，如果传 BATCH，那么同一批次的分享，只会有一条通知。默认值为 NONE，表示不作 groupBy 处理。

返回参数

参数 子键 子键 类型 描述
total - - Integer 云端总量
pageNo - - Integer 当前页号
pageSize - - Integer 页大小
data - - List<> 分享列表
- initiatorAlias - String 发起分享用户别名
- receiverAlias - String 被分享用户别名
- targetId - String 共享的物的ID。
说明 按照 BATCH 查询时，如果批次内有多个记录，此字段不会返回
- targetType - String 共享的物的类型
- productImage - String 设备产品图片
- deviceName - String 设备的deviceName
说明 按照 BATCH 查询时，如果批次内有多个记录，此字段不会返回
- isReceiver - Integer 当前用户是否是消息接收者
- gmtCreate - Long 创建时间
- gmtModified - Long 修改时间
- recordId - String 分享记录唯一标识
说明 按照 BATCH 查询时，如果批次内有多个记录，此字段不会返回
- batchId - String 分享批次ID，批量分享设备时，同一批次ID相同，客户端可以根据此判断是否为同一批分享，由此做聚合展示等
- status - Integer 状态
  • -1: 初始化
  • 0：同意
  • 1：拒绝
  • 2：取消
  • 3：过期
  • 4：抢占
  • 5：删除
  • 6：发起者已解绑
  • 99：异常
- description - String 描述
- categoryImage - String 品类图标
说明 按照 BATCH 查询时，如果批次内有多个记录，此字段不会返回
- productName - String 产品名称
说明 按照 BATCH 查询时，如果批次内有多个记录，此字段不会返回
- batchInfo - Struct 如果批次内包含多个记录，此字段不为空，其中包含了该批次的信息。
- - recordCount Integer 当前批次中所包含的分享记录的数量，例如在一个批次中分享了 10 个设备，那么对应包含有 10 个分享记录。

示例

  • 请求示例 
    {
    "request":{
        "iotToken":"109049c80xxxxxxxx5fe29a3ba",
        "apiVer":"1.0.2"
    },
    "id":150821281****,
    "params":{
        "pageNo":1,
        "pageSize":10,
        "groupBy":"BATCH"
    },
    "version":"1.0"
}
  • 正常返回示例 
    {
    "code":200,
    "data":{
        "total":1,
        "pageNo":1,
        "pageSize":10,
        "data":[
            {
                "gmtCreate":"1390000****",
                "gmtModified":"1390000****",
                "description":"向1390000****共享设备中，待对方确认",
                "targetType":"DEVICE",
                "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5",
                "initiatorAlias":"1390000****",
                "receiverAlias":"1390000****",
                "isReceiver":0,
                "status":-1,
                "batchInfo":{
                    "recordCount":10
                }
            }
        ]
    },
    "id":"e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
}
  • 异常返回示例 
    {
 "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

获取批次内共享通知列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/user/device/shared/record/query 1.0.0 查询设备分享记录。支持按照批次ID进行查询。 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
pageNo Int 是 当前页号，从1开始的页序号
pageSize Int 是 页大小，单页的item数量上限，最大为 20
batchId String 是 要查询的批次ID

返回参数

参数 子键 类型 描述
total - Integer 云端总量
pageNo - Integer 当前页号
pageSize - Integer 页大小
data - List<> 分享列表
- initiatorAlias String 发起分享用户别名
- receiverAlias String 被分享用户别名
- targetId String 共享的物的ID。
- targetType String 共享的物的类型
- productImage String 设备产品图片
- deviceName String 设备的deviceName
- isReceiver Integer 当前用户是否是消息接收者
- gmtCreate Long 创建时间
- gmtModified Long 修改时间
- recordId String 分享记录唯一标识
- batchId String 分享批次ID，批量分享设备时，同一批次ID相同，客户端可以根据此判断是否为同一批分享，由此做聚合展示等
- status Integer 状态
  • -1: 初始化
  • 0：同意
  • 1：拒绝
  • 2：取消
  • 3：过期
  • 4：抢占
  • 5：删除
  • 6：发起者已解绑
  • 99：异常
- description String 描述
- categoryImage String 品类图标
- productName String 产品名称

示例

  • 请求示例 
    {
    "request":{
        "iotToken":"109049c80xxxxxxxx5fe29a3ba",
        "apiVer":"1.0.2"
    },
    "id":150821281****,
    "params":{
        "pageNo":1,
        "pageSize":10,
        "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5"
    },
    "version":"1.0"
}
  • 正常返回示例 
    {
    "code":200,
    "data":{
        "total":1,
        "pageNo":1,
        "pageSize":10,
        "data":[
            {
                "gmtCreate":"1390000****",
                "gmtModified":"1390000****",
                "targetId":"fy2Z1oZFW********0101edf00",
                "categoryImage":"http://xxx",
                "description":"向1390000****共享设备中，待对方确认",
                "targetType":"DEVICE",
                "recordId":"a1OwEjY****dfdFJNb",
                "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5",
                "deviceName":"b65cb59********92cd695fb",
                "productName":"0d****195",
                "initiatorAlias":"1390000****",
                "receiverAlias":"1390000****",
                "isReceiver":0,
                "status":-1
            }
        ]
    },
    "id":"e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
}
  • 异常返回示例 
    {
 "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

发起者取消分享

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/cancelShare 1.0.7 在分享用户接受分享前，发起者取消分享 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
recordIdList List< String > 否 分享记录列表。recordIdList 和 batchId 其中一个必传。
batchId String 否 批次ID，recordIdList 和 batchId 其中一个必传。 传入 batchId 时，将取消批次内所有设备的分享

返回参数

无

示例

  • 请求示例 
    {
    "request":{
        "iotToken":"109049c8xxxxxxxx6f62e29a3ba",
        "apiVer":"1.0.2"
    },
    "id":150821281****,
    "params":{
        "recordIdList":[
            "d4eb352adxxxxxxxx1d53febd503",
            "2568degt2xxxxxxxxe91fb61d53febd3"
        ]
    },
    "version":"1.0"
}
  • 正常返回示例 
    {
   "code": 200,
   "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
  "code":2093,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"forbidden to repeat cancel sharing."
}

被分享者同意或拒绝分享

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/confirmShare 1.0.7 被分享者同意/拒绝分享 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
recordIdList List< String > 否 分享记录列表，单次同意（拒绝）分享的数量上限为 10 个。recordIdList 和 batchId 其中一个必传
agree Integer 是 0：不同意；1：同意
batchId String 否 批次ID，recordIdList 和 batchId 其中一个必传。 传入 batchId 时，将同意或拒绝批次内所有设备的分享。

返回参数

无

示例

  • 请求示例 
    {
    "request":{
        "iotToken":"109049c80xxxxxxxxf62e29a3ba",
        "apiVer":"1.0.2"
    },
    "id":150821281****,
    "params":{
        "recordIdList":[
            "d4eb352adxxxxxxxx53febd503",
            "2568degt2xxxxxxxx91fb61d53febd3"
        ],
        "agree":1
    },
    "version":"1.0"
}
  • 正常返回示例 
    {
   "code": 200,
   "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2092,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"forbidden to repeat reject sharing."
}

设置设备昵称

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/setDeviceNickName 1.0.2 设置设备昵称 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
iotId String 是 设备ID
nickName String 是 昵称

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049cxxxxxxxxf6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "iotId": "5070op867xxxxxxxx49d87c207471699",
         "nickName":"nickName"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
   "code": 200,
   "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
  "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

解绑用户和设备

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/unbindAccountAndDev 1.0.2 解绑用户和设备
  • 若用户不是拥有者（管理员），则只解绑自己
  • 若用户是拥有者（管理员），则再解绑与该设备绑定的所有用户
  • 若用户是管理员且设备是网关，则还会解绑用户和其所有的子设备
 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
iotId String 否 设备ID

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c8xxxxxxxx62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "iotId":"xxxx"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
  "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

查询用户和设备的关系

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/getByAccountAndDev 1.0.2 查询用户和设备的关系，如不存在，返回一个空对象 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
iotId String 是 设备ID

返回参数

参数 类型 描述
identityId String 用户的身份ID
iotId String 设备的iotId
AproductKey String 设备的productKey
deviceName String 设备的deviceName
productName String 设备的产品名称
productImage String 设备的产品图片
productModel String 设备的产品型号
nickName String 用户对设备的昵称
netType String 设备入网类型
thingType String 设备的类型：
  • VIRTUAL（虚拟设备）
  • VIRTUAL_SHADOW（虚拟影子设备）
  • WEB
  • APP
  • DEVICE（普通设备）
nodeType String 设备的节点类型：DEVICE；GATEWAY
status Byte 设备的状态 0：未激活 ；1：在线；3：离线；8：禁用
owned Byte 0：分享者；1：拥有者
identityAlias String 用户的显示名：mobile，loginName或email
gmtModified Date 修改绑定的时间

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxx6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "iotId":"xxxx"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
  "code": 200,
  "data": 
    {
      "productModel": "testProduct",
      "iotId": "fy2Z1oZxxxxxxxx101edf00",
      "netType": "NET_WIFI",
      "identityId": "5082opabf51xxxxxxxx06fbdae6f6093",
      "thingType": "DEVICE",
      "nodeType": "DEVICE",
      "productKey": "a1OxxxxNb",
      "deviceName": "b65cb59e6xxxxxxxx2cd695fb",
      "productName": "0d2xxxx95",
      "status": 3
    },
  "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
}
  • 异常返回示例 
    {
 "code":2063,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"iotId not exist"
}

管理员解绑设备

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/unbindByManager 1.0.2 用户接受设备分享后，管理员解绑指定的用户和设备。要求当前登录用户是设备的管理员、拥有者。 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
targetIdentityId String 是 分享用户的identityId（设备的普通成员），非管理员的identityId
iotIdList List< String> 是 要解绑的设备ID列表

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxx62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "targetIdentityId":"xxxx",
        "iotIdList":[
                        "d4eb352adxxxxxxxx1d53febd503",
                        "2568degt2xxxxxxxx91fb61d53febd3"   
                     ]
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2083,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"you are not the manager of some devices"
}

清空共享消息列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/clearShareNoticeList 1.0.2 清空共享消息列表（包括本人发起和接收全部） 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

无

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "c4b3f64xxxxxxxe7a06a3c5dcb3",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

管理员批量查询设备和目标用户的被分享关系

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/user/device/shared/batch/get 1.0.0 管理员批量查询设备和目标用户的被分享关系。 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 子健 类型 必填 描述
targetIdentityId - String 是 目标用户的identityId，用户的唯一标识
deviceList JSONArray 是 设备列表，size的最大限制为50个
iotId String 否 设备唯一标识的iotId
  • 该字段为空时，则productKey和deviceName字段必填
  • 该字段为不为空时，即使配置了productKey和deviceName字段，仍以iotId为设备的唯一标识
productKey String 否 设备所属产品的productKey，当iotId字段为空时，该字段必填
deviceName String 否 设备的名称，当iotId字段为空时，该字段必填

返回参数

参数 子参 类型 描述
data - JSONArray 设备的被分享关系详情列表
- iotId String 设备的iotId，设备的唯一标识
- productKey String 设备所属产品的productKey
- deviceName String 设备的名称
- shared Boolean 设备是否分享给了目标用户

示例

  • 请求示例 
    {
    "id":"xxx",
    "version":"1.0.0",
    "request":{
        "language":"zh-CN",
        "appKey":"xxx",
        "iotToken":"xxx",
        "apiVer":"xxx"
    },
    "params":{
          "targetIdentityId": "xxx",
        "deviceList":[
            {
                "iotId":"edwB6xxxxNa000100"
            }
        ]
    }
}
  • 正常返回示例 
    {
    "code":200,
    "message":"success",
    "localizedMsg":"",
    "data":[
        {
            "iotId":"edwB6xxxxNa000100",
              "productKey":"xxx",
              "deviceName":"xxx",
            "shared":true
        }
    ]
}

绑定push通道

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/bindPushChannel 1.0.2 绑定push通道 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
deviceId String 是 push通道的deviceId
deviceType String 是 设备类型：iOS或ANDROID，值由业务方和app协商

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxxf62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "deviceId":"xxxx",
        "deviceType":"iOS"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

解绑push通道

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/unbindPushChannel 1.0.2 绑定push通道 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
deviceId String 是 push通道的deviceId

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxf62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "deviceId":"xxxx"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}
  • 异常返回示例 
    {
 "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

获取网关的子设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/subdevices/list 1.0.2 获取用户绑定的网关子设备列表 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
iotId String 是 设备ID
pageNo Int 是 当前页号，从1开始的页序号
pageSize Int 是 页大小，单页的item数量上限

返回参数

参数 子键 类型 描述
total - Integer 云端总数
pageNo - Integer 当前页号
pageSize - Integer 页大小
data - List<> 子设备列表
- iotId String 设备的iotId
- productKey String 设备的productKey
- deviceName String 设备的deviceName
- nickName String 设备的产品名称
- image String 品类图片
- status Byte 设备的在线状态：0 - 未激活， 1 - 在线， 3 - 离线， 8 - 禁用

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c8xxxxxxxx6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 150821281****,
    "params": {
        "iotId":"xxxxxxx",
        "pageNo":1,
        "pageSize":10
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
  "code": 200,
  "data": [
    {
      "iotId": "testIot",
      "productKey": "fy2Z1oZxxxxxxxx0101edf00",
      "deviceName": "NET_WIFI",
      "nickName": "xxxxxx",
      "image": "http://abc.jpg",
      "status": 0
    },
    {
      "iotId": "testIot",
      "productKey": "fy2Z1oZFxxxxxxxx00101edf00",
      "deviceName": "NExxxxFI",
      "nickName": "xxxxxx",
      "image": "http://abc.jpg",
      "status": 0
    }
  ],
  "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
}
  • 异常返回示例 
    {
 "code":2062,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

创建虚拟用户

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/virtual/user/create 1.0.4 创建当前登录用户名下的虚拟用户 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
attrList List 否 用户的属性及属性值。 若为空，则表示只创建一个无属性的用户。属性Key必须是在规定的系统属性中选择
attrList列表结构
参数 类型 必填 描述
attrKey String 是 属性Key
attrValue String 是 属性值

返回参数

参数 类型 描述
userId String 创建的虚拟用户ID
attrList List 用户的属性值，意义同请求参数
attrList列表结构
参数 类型 必填 描述
attrKey String 是 属性Key
attrValue String 是 属性值

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049xxxxxxxxf62e29a3ba",
        "apiVer": "1.0.4"
    },
    "id": 150821281****,
    "params": {
        "attrList": [
              {
                 "attrKey":"name",
                 "attrValue":"小明"
              }
        ]
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "message": "success",
    "data": {
        "userId":"10B6336Exxxxxxxx428F58AA5A18",
        "attrList":[
            {
               "attrKey":"name",
               "attrValue":"小明"
            }
        ]
    }
}
  • 异常返回示例 
    {
 "code":503,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"服务不可用",
 "message":"service not available."
}

删除虚拟用户

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/virtual/user/delete 1.0.4 删除当前登录用户名下的虚拟用户 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
virtualUserId String 是 虚拟用户ID

返回参数

无

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxxf6f62e29a3ba",
        "apiVer": "1.0.4"
    },
    "id": 150821281****,
    "params": {
           "userId":"10B633xxxxxxxx99BDD428F58AA5A18"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "message": "success",
    "data": {
        "userId":"10B6336EFxxxxxxxx8F58AA5A18",
        "attrList":[
            {
               "attrKey":"name",
               "attrValue":"小明"
            }
        ]
    }
}
  • 异常返回示例 
    {
 "code":503,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"服务不可用",
 "message":"service not available."
}

更新虚拟用户信息

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/virtual/user/update 1.0.4 更新当前登录用户名下的虚拟用户信息 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
virtualUserId String 是 虚拟用户ID
opType Integer 是 更新时属性时的操作类型（opType）的类型，目前仅支持三种：1-ADD；2-UPDATE；3-DELETE
attrList List 是 用户的属性及属性值。属性Key必须是在规定的系统属性中选择，具体系统属性定义

attrList列表结构

参数 类型 必填 描述
attrKey String 是 属性Key
attrValue String 是 属性值

返回参数

参数 类型 描述
userId String 创建的虚拟用户ID
attrList List 用户的属性值，意义同请求参数

attrList列表结构

参数 类型 必填 描述
attrKey String 是 属性Key
attrValue String 是 属性值

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c8xxxxxxxx6f62e29a3ba",
        "apiVer": "1.0.4"
    },
    "id": 150821281****,
    "params": {
           "userId":"10B6336EFxxxxxxxx28F58AA5A18",
           "opType":2,
           "attrList":[
               {
                    "attrKey":"name",
                    "attrValue":"小李"
               }
           ]
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "message": "success",
    "data": {
        "userId":"10B6336EFxxxxxxxx428F58AA5A18",
        "attrList":[
            {
               "attrKey":"name",
               "attrValue":"小明"
            }
        ]
    }
}
  • 异常返回示例 
    {
 "code":503,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"服务不可用",
 "message":"service not available."
}

查询虚拟用户列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/virtual/user/list 1.0.4 查询当前登录用户名下的虚拟用户列表 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
pageNo Integer 是 当前页号，从1开始的页序号
pageSize Integer 是 页大小，单页的item数量上限

返回参数

参数 类型 描述
total Long 虚拟用户总数
pageNo Integer 当前页号
pageSize Integer 页大小
data List 虚拟用户列表
data列表结构
参数 类型 必填 描述
userId String 是 虚拟用户ID
attrList List 是 用户的属性及属性值。属性Key必须是在规定的系统属性中选择
attrList列表结构
参数 类型 必填 描述
attrKey String 是 属性Key
attrValue String 是 属性值

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049c80xxxxxxxxf62e29a3ba",
        "apiVer": "1.0.4"
    },
    "id": 150821281****,
    "params": {
           "pageNo":1,
           "pageSize":10
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "message": "success",
    "data": {
        "total":1,
        "pageNo":1,
        "pageSize":10,
        "data":[
            {
                "userId":"10B633xxxxxxxxBDD428F58AA5A18",
                "attrList":[
                   {
                       "attrKey":"name",
                       "attrValue":"小明"
                   }
                ]
            }
        ]
    }
}
  • 异常返回示例 
    {
 "code":503,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"服务不可用",
 "message":"service not available."
}

查询虚拟用户详情

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/virtual/user/query 1.0.4 查询当前登录用户名下的虚拟用户详情 是，客户端SDK需启用身份的鉴权，进行身份认证

请求参数

参数 类型 必填 描述
virtualUserId String 是 虚拟用户ID

返回参数

参数 类型 是否必选 描述
userId String 是 虚拟用户ID
attrList List 是 用户的属性及属性值。属性Key必须是在规定的系统属性中选择
attrList列表结构
参数 类型 必填 描述
attrKey String 是 属性Key
attrValue String 是 属性值

示例

  • 请求示例 
    {
    "request": {
        "iotToken": "109049cxxxxxxxxf6f62e29a3ba",
        "apiVer": "1.0.4"
    },
    "id": 150821281****,
    "params": {
           "userId":"10B6336Exxxxxxxx428F58AA5A18"
    },
    "version": "1.0"
}
  • 正常返回示例 
    {
    "code": 200,
    "message": "success",
    "data": {
         "userId":"10B633xxxxxxxx28F58AA5A18",
         "attrList":[
               {
                    "attrKey":"name",
                    "attrValue":"小明"
               }
         ]
    }
}
  • 异常返回示例 
    {
 "code":503,
 "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
 "localizedMsg":"服务不可用",
 "message":"service not available."
}

虚拟用户属性定义表

参数 类型 描述
displayName String 显示名
name String 姓名
gender Integer 性别（1男；2女）
birthday String 生日
QQ String QQ号码
employeeID String 工号
extNum String 办公分机号
homeAddress String 家庭地址
companyAddress String 公司地址
companyName String 公司名称
country String 国家名称
region String 所在地区
avatar String 头像（头像的图片URL地址）