Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
涂鸦 Cube（私有云）
search
根据文档目录筛选
涂鸦 Cube（私有云）智慧私有云 1.0应用开发服务API 网关API 参考IoT Core 服务全屋设备体系设备管理

设备管理

更新时间：2023-08-17 08:45:55下载pdf

本文为您介绍设备基础服务 API。

API 列表

请求方式 API 描述
GET /v1.0/devices/{device_id} 获取设备详情
GET /v1.0/users/{uid}/devices 获取用户下的设备列表
GET /v1.0/devices 获取设备列表
PUT /v1.0/devices/{device_id}/functions/{function_code} 修改功能点名称
GET /v1.0/devices/{device_id}/logs 查询设备日志
PUT /v1.0/devices/{device_id}/reset-factory 恢复设备出厂设置
DELETE /v1.0/devices/{device_id} 根据设备 ID 来移除设备
GET /v1.0/devices/{deviceId}/sub-devices 查询网关下的设备列表
GET /v1.0/devices/factory-infos 查询设备出厂信息
PUT /v1.0/devices/{device_id} 修改设备名称
PUT /v1.0/devices/{device_id}/multiple-name 修改多路名称
GET /v1.0/devices/{device_id}/multiple-names 获取多路名称

获取设备详情

接口描述

可查询设备的详情信息，包括设备属性和设备最新状态。

接口地址

GET /v1.0/devices/{device_id}

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 是 设备 ID

返回参数

参数名 类型 说明
code Integer 响应码，详见 错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
id String 设备编号
name String 设备名称
uid String 用户 ID
local_key String 密钥
category String 产品类别
product_id String 产品 ID
product_name String 产品名称
sub Boolean 判断是否为子设备
  • true：是
  • false：不是
uuid String 设备唯一标识
owner_id String 家庭 ID
online Boolean 设备在线状态
status Object<status> 设备功能状态
active_time Long 设备激活时间，时间戳，精确到秒
biz_type Long 应用 biztype
icon String 设备图标，中国区前缀是 https://images.tuyacn.com，如果您获取的相对路径是 smart/product_icon/cz.png，实际的图标地址为 https://images.tuyacn.com/smart/product_icon/cz.png
ip String 设备 IP

status 说明

参数名 类型 说明
code String 功能点 Code
value String 功能点的值
type String 功能点的类型

请求示例

GET /v1.0/devices/vdevo153490924188132

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
DeviceVo deviceVo = client.getDeviceInfo(DEV_ID);
System.out.println("获取设备信息: ");
System.out.println(JSONObject.toJSONString(deviceVo));

返回示例

{
    "success": true,
    "result": {
        "active_time": 1589505938,
        "biz_type": 299009,
        "category": "qt",
        "create_time": 1560827137,
        "icon": "smart/icon/15402589135gknz23xajb_0.png",
        "id": "60613135b121cddc294****",
        "ip": "120.198.****.****",
        "local_key": "3a9b50126fe473****",
        "name": "体脂秤",
        "online": true,
        "owner_id": "1070****",
        "product_id": "g0er6hSKgMqr****",
        "product_name": "Wifi scales_OEM",
        "status": [
            {
                "code": "weight",
                "value": 48900
            },
            {
                "code": "left_hand_r",
                "value": 0
            },
            {
                "code": "right_hand_r",
                "value": 0
            },
            {
                "code": "left_leg_r",
                "value": 0
            },
            {
                "code": "right_leg_r",
                "value": 0
            },
            {
                "code": "body_r",
                "value": 653
            },
            {
                "code": "battery_low",
                "value": false
            }
        ],
        "sub": false,
        "time_zone": "+08:00",
        "uid": "ay157896239864843g****",
        "update_time": 1589764585,
        "uuid": "60613135b23cddc294****"
    }
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误
1106 权限非法

获取用户下设备列表

接口描述

可查询用户下可操作的设备列表，包括设备属性、设备最新状态。

接口地址

GET /v1.0/users/{uid}/devices

请求参数

参数名 类型 参数类型 必填 说明
uid String URI 是 涂鸦用户 ID
from String query 否 来源。
  • home：查询当前用户房屋下的设备
  • sharing：查询当前用户接收到的分享设备
page_no Integer query 否 当前页，1 为第一页
page_size Integer query 否 分页大小

返回参数

参数名 类型 说明
code Integer 响应码，详见 错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Object<result> 返回结果。

result 说明

参数名 类型 说明
id String 设备编号
uid String 用户 ID
local_key String 密钥
category String 产品类别
product_id String 产品 ID
sub Boolean 判断是否是子设备
  • true：是
  • false：不是
uuid String 设备唯一标识
owner_id String 设备拥有者 ID
online Boolean 设备在线状态
name String 设备名称
ip String IP 地址
time_zone String 时区
create_time Long 设备初次配网时间
update_time Long 最后一次设备信息更新时间
active_time Long 设备上次配网时间
status List<status> 设备功能状态

status 说明

参数名 类型 说明
code String 功能点 Code
value String 功能点的值

请求示例

GET /v1.0/users/ay15*******/devices

GET /v1.0/users/ay15*******/devices?page_no=1&page_size=50

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
List<DeviceVo> deviceFunctions = client.getUserDevices(UID);
System.out.println("获取用户设备列表: ");
System.out.println(JSONObject.toJSONString(deviceFunctions));

返回示例

{
    "result":[
        {
            "sub":false,
            "create_time":1540691155,
            "local_key":"11a53bdd67e4****",
            "owner_id":"357****",
            "ip":"**.62.43.**",
            "biz_type":293964,
            "icon":"smart/product_icon/cz.png",
            "time_zone":"+08:00",
            "uuid":"27511006b4e62d4b****",
            "product_name":"Wi-Fi 智能计量插座",
            "active_time":1548584422,
            "uid":"ay1548569152777Q****",
            "update_time":1548584559,
            "product_id":"EvolhYPyZNWYP***",
            "name":"xxx测试",
            "online":true,
            "id":"27511006b4e62d4b****",
            "category":"cz",
            "status":[
                {
                    "code":"cur_power",
                    "value": 0
                },
                {
                    "code":"cur_voltage",
                    "value": 2196
                },
                {
                    "code":"switch",
                    "value": false
                },
                {
                    "code":"countdown_1",
                    "value": 0
                },
                {
                    "code":"cur_current",
                    "value": 0
                }
            ]
        }
    ],
    "t":1564996327422,
    "success":true
}

错误码

以下为该接口常见的业务异常。更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误
1106 权限非法

获取设备列表

接口描述

提供按应用、产品、设备 ID 查询设备列表的能力，调用该接口时，建议请求参数三选一。数据权限维度满足以下任意一种，则可获取相关设备数据：

  • 应用维度
    应用维度针对于设备采购商。设备采购商通过将应用（在涂鸦平台创建的 OEM App 或者基于涂鸦的客户端 SDK 自行开发）绑定设备的方式来获取设备的数据。

  • 产品维度
    产品维度针对于设备生产厂商。生产厂商通过在涂鸦平台创建产品，然后基于这个产品来生产设备（设备连接云端），最终获取或管控厂商所生产设备的数据。

    云 API 提供查询处于激活状态的真实设备以及虚拟设备，与涂鸦 IoT 开发平台中设备管理的查询策略不完全一致。涂鸦 IoT 开发平台设备管理仅提供真实设备查询，支持查询激活状态和移除状态的设备。查询的起始和终止时间最大跨度为30天，建议基于设备日增量缩短查询时间，来进行更快速的查询。

接口地址

GET /v1.0/devices

请求参数

参数名 类型 参数类型 必填 说明
page_no Integer query 是 当前页
page_size Integer query 是 分页大小
schema String query 否 应用标识
product_id String query 否 产品 ID
device_ids String query 否 设备 ID 列表
start_time String query 否 查询的起始时间，10 位时间戳
end_time String query 否 查询的截止时间，10 位时间戳

返回参数

参数名 类型 说明
code Integer 响应码，详见 错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Object<result> 返回结果

result 说明

参数名 类型 说明
total Long 总数
devices List<devices> 设备列表
last_id String 设备最后查询 ID

devices 说明

参数名 类型 说明
id String 设备编号
uid String 用户 ID
local_key String 密钥
category String 产品类别
product_id String 产品 ID
sub Boolean 判断是否是子设备
  • true：是
  • false：不是
uuid String 设备唯一标识
owner_id String 设备拥有者 ID
online Boolean 设备在线状态
name String 设备名称
ip String IP 地址
time_zone String 时区
create_time Long 设备初次配网时间
update_time Long 最后一次设备信息更新时间
active_time Long 设备上次配网时间
status List<status> 设备功能状态

status 说明

参数名 类型 说明
code String 标准状态 code
value Object 标准状态值。value 详情可以参考标准状态集文档，可能是 Boolean、Integer、String。请以实际设备为准。

当查询数据总量过大时，建议使用 page_size + last_id 组合取代 page_size + page_no 组合，详细说明参见示例。

请求示例

GET /v1.0/devices?schema=testApp

GET /v1.0/devices?product_id=*******

GET /v1.0/devices?device_ids=vdevo15****88132,vdevo1***188132

GET /v1.0/devices?last_id=1584939***&page_size=20

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
BatchDevices batchDevices = client.getDeviceListInfo(devIds);
System.out.println("批量获取设备详细信息: ");
System.out.println(JSONObject.toJSONString(batchDevices));

返回示例

{
    "result": {
        "devices": [
            {
                "active_time": 1584063323,
                "biz_type": 310002,
                "category": "znyxss",
                "create_time": 1575017570,
                "icon": "smart/program_category_icon/znyxss.png",
                "id": "747b2165d9449964****",
                "ip": "58.251.**.****",
                "local_key": "11d7f7286caa****",
                "model": "SS190",
                "name": "Wi-Fi 智能音箱 SS190",
                "online": false,
                "owner_id": "1160****",
                "product_id": "i9vkz***",
                "product_name": "Wi-Fi 智能音箱 SS190",
                "status": [
                    {
                        "code": "smartspeaker_vol",
                        "value": 26
                    },
                    {
                        "code": "smartspeaker_mic",
                        "value": true
                    },
                    {
                        "code": "smartspeaker_play",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_wm_switch",
                        "value": "btm"
                    },
                    {
                        "code": "smartspeaker_bt_switch",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_pre",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_next",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_play_mode",
                        "value": "random"
                    },
                    {
                        "code": "smartspeaker_alarm_clock",
                        "value": ""
                    },
                    {
                        "code": "smartspeaker_alert",
                        "value": ""
                    },
                    {
                        "code": "ir_send",
                        "value": "{\"control\":\"study_exit\"}"
                    },
                    {
                        "code": "ir_study_code",
                        "value": ""
                    }
                ],
                "sub": false,
                "time_zone": "+08:00",
                "uid": "ay156531946658X****",
                "update_time": 1584939489,
                "uuid": "12****"
            }
        ],
        "last_id": "158493****",
        "total": 1
    },
    "success": true,
    "t": 1586741851210
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误
1106 权限非法

修改功能点名称

接口描述

满足多路子设备，可以进行子设备名称修改。

接口地址

PUT /v1.0/devices/{device_id}/functions/{function_code}

请求参数

参数名 类型 参数位置 必填 说明
device_id String URI 是 设备 ID
function_code String URI 是 功能点
name String Body 是 功能点名称

请求示例

PUT /v1.0/devices/vdevo156083035305868/functions/switch_1

{
  "name":"lalal"
}

返回参数

参数名 类型 说明
code Integer 响应码，详见 全局错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Object 返回结果
t Long 时间戳

返回示例

{
     "success": true,
     "t": 1562229928732,
     "result": true
}

查询设备日志

接口描述

根据查询条件查询设备操作历史记录。

接口地址

GET /v1.0/devices/{device_id}/logs

请求参数

参数名 类型 参数位置 必填 说明
device_id String URI 是 设备 ID
type String URL 是 日志查询支持的类型。支持多个事件类型的查询，用半角逗号（,）隔开，必传，详情请参考 事件类型说明。
start_time Long URL 是 查询的 13 位开始时间戳。如果为 0 或者为空，会自动设置为近 7 天前的时间戳，建议 start_time 设置大一点，避免一次查询太多的数据导致超时。
end_time Long URL 是 查询的 13 位结束时间戳。
codes String URL 否 设备支持的功能点。支持多个功能点的查询，用半角逗号（,）隔开，默认为空。
start_row_key String URL 否 免费版参数，查询 Hbase 的行键。默认值为空。
last_row_key String URL 否 收费版分页参数，最后一条数据的行键。默认值为空，查第一页，收费版必传。
last_event_time Long URL 否 收费版分页参数，最后一条数据的事件发生时间。默认为空查第一页，收费版必传。
size int URL 否 查询的日志数量大小。默认为 20。
query_type Integer URL 否 查询类型，默认为 1。
  • 1：免费版
  • 2：收费版

请求示例

免费版示例

{{url}}/v1.0/devices/78304402ecfabc1fd5b2/logs?start_row_key=&type=1,2&start_time=0&end_time=1545898159935&size=20

收费版示例

GET /v1.0/devices/03200026dc4f221b6d6d/logs?type=7&start_time=0&end_time=1545898159935&size=20&query_type=2&last_row_key=650823455f68a9cbafce08700557_9223370475075511414_1&last_event_time=1561779264393

返回参数

参数名 类型 说明
code Integer 响应码，详见 全局错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Object<result> 返回结果
t Long 时间戳

result 说明

参数名 类型 说明
logs Object<logs> 日志消息体。
has_next Boolean 是否还有下一条。
device_id String 设备 ID。
current_row_key String 免费版参数，Hbase 的当前行键。
next_row_key String 免费版参数，下一条满足查询条件的 Hbase 行键。
说明：如果返回值为 null，表示为没有满足查询条件的下一条日志。
count Long 收费版参数，满足查询条件的日志总数。

logs 说明

参数名 类型 说明
code String 功能点 Code
value String 功能点的值
event_time String 事件发生的时间戳
event_from String 事件触发的来源，请参考 事件来源说明。
event_id String 事件的类型，请参考 事件类型说明。
status String 数据有效，没有被删除。默认值为 1。
row String 收费版参数，为当前 Hbase 行键。

返回示例

返回成功示例

  • 免费版

    {
"success": true,
"t": 1561344464370,
"result": {
    "logs": [
        {
            "code": "switch_1",
            "value": "false",
            "event_time": 1560872567955,
            "event_from": "1",
            "event_id": 7
        },
        {
            "code": "switch_1",
            "value": "false",
            "event_time": 1560783276382,
            "event_from": "1",
            "event_id": 7
        }
    ],
    "device_id": "75500780ecfabc9a****",
    "has_next": true,
    "current_row_key": "NjUwODIzNDU1ZjY4YTljYmFmY2UwODcwMDU1N185MjIzMzcwNDc1OTgyMjA3ODUyXzdfMQ==",
    "next_row_key": "NjUwODIzNDU1ZjY4YTljYmFmY2UwODcwMDU1N185MjIzMzcwNDc2MDcxNDk5OTM0XzdfMQ=="
	}
}

  • 收费版

    {
"success":true,
    "t":1561344464370,
    "result":{
        "count":32,
        "device_id":"75500780ecfabc9a****",
        "has_next":true,
        "logs":[
            {
                "event_id":1,
                "event_time":1562031576431,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474823199376_1",
                "status":"1"
            },
            {
                "event_id":1,
                "event_time":1562031394665,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474823381142_1",
                "status":"1"
            },
            {
                "event_id":1,
                "event_time":1562031277824,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474823497983_1",
                "status":"1"
            },
            {
                "event_id":1,
                "event_time":1561935500636,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474919275171_1",
                "status":"1"
            }
        ]
    }
}

返回失败示例

	{
    "success": false,
    "code": 2009,
    "msg": "not support this device",
    "t": 1561348644346
	}

事件来源说明

code 说明
1 设备本身
2 客户端指令
3 第三方平台
4 云端指令
-1 未知

事件类型说明

code 说明
1 上线
2 下线
3 设备激活
4 设备重置
5 指令下发
6 固件升级
7 数据点上报
8 设备信号量
9 设备重启
10 定时信息

恢复设备出厂设置

接口描述

根据设备 ID 来恢复出厂设置。

接口地址

PUT /v1.0/devices/{device_id}/reset-factory

请求参数

参数名 类型 必填 说明
device_id String 是 设备 ID

请求示例

PUT /v1.0/devices/6c362ac3c53fbd6f3e****/reset-factory

返回参数

参数名 类型 说明
code Integer 响应码，详见 全局错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Boolean 返回结果。

返回示例

{
    "success": true,
    "t": 1550642917632,
    "result": true
}

移除设备

接口描述

根据设备 ID 来移除设备。

接口地址

DELETE /v1.0/devices/{device_id}

请求参数

参数名 类型 必填 说明
device_id String 是 设备 ID

请求示例

DELETE /v1.0/devices/6c362ac3c53fbd6f3ew***

返回参数

参数名 类型 说明
code Integer 响应码，详见 全局错误码。
success Boolean 判断请求是否成功。
  • true：成功
  • false：失败
msg String 请求失败返回的信息，成功则返回空值。
result Boolean 返回结果。

查询网关下的设备列表

接口描述

查询网关下的设备列表。

接口地址

GET /v1.0/devices/{deviceId}/sub-devices

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 是 设备 ID

返回参数

名称 类型 描述
t Long 时间戳
success Boolean 是否成功
result List<result> 结果

result 说明

参数名 参数类型 说明
id String 设备 ID
name String 设备名称
online Boolean 在线状态
owner_id Long 家庭 ID
category Integer 类型
product_id Integer 产品
active_time String 激活时间
update_time String 更新时间

请求示例

GET /v1.0/devices/vedeo16236124/sub-devices

返回示例

{
     "result": [
         {
             "active_time": 1586169374,
             "category": "sj",
             "id": "6c0746cfe887e21e8b****",
             "name": "水浸警报",
             "online": true,
             "owner_id": "1059****",
             "product_id": "rzeSU2h9uoklx***",
             "update_time": 1586169379
         }
     ],
     "success": true,
     "t": 1586169580204
 }

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误

查询设备出厂信息

接口描述

查询设备出厂信息。

接口地址

GET /v1.0/devices/factory-infos

请求参数

参数名 类型 参数类型 必填 说明
device_ids String URL 是 设备 ID，以逗号分隔

返回参数

名称 类型 描述
t Long 时间戳
success Boolean 是否成功
result List<result> 结果

result 说明

参数名 参数类型 说明
id String 设备 ID
uuid String 设备名称
sn String 设备序列号
mac String 设备 MAC 地址

请求示例

GET /v1.0/devices/factory-infos?device_ids=002008535ccf7f530***

返回示例

{
    "result": [
        {
            "id": "002008535ccf7f53****",
            "mac": "5c:cf:7f:53:**:**",
            "uuid": "002008535ccf7f53****"
        }
    ],
    "success": true,
    "t": 1585619435816
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误

修改设备名称

修改设备名称。

接口地址

PUT /v1.0/devices/{device_id}

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 是 设备 ID
name String BODY 是 名称

返回参数

名称 类型 描述
t Long 时间戳
success Boolean 是否成功
result Boolean 结果

请求示例

PUT /v1.0/devices/vedeo234567
{
    "name":""
}

返回示例

{
    "t":1234876331,
    "success":true,
    "result": true
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误

修改多路名称

当设备存在多路名称时可修改，现支持排插类设备。

接口地址

PUT /v1.0/devices/{device_id}/multiple-name

请求参数

参数名 类型 参数类型 说明 必填
device_id String URI 是 设备 ID
identifier String BODY 是 标识
name String BODY 是 名称

返回参数

名称 类型 描述
t Long 时间戳
success Boolean 是否成功
result Boolean 结果

请求示例

PUT /v1.0/devices/vedeo234567/multiple-name
{
    "identifier":"",
    "name":""
}

返回示例

{
    "t":1234876331,
    "success":true,
    "result": true
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误

获取多路名称

获取设备多路名称。

接口地址

GET /v1.0/devices/{device_id}/multiple-names

请求参数

参数名 类型 参数类型 必填 说明
device_id String URI 是 设备 ID

返回参数

名称 类型 描述
t Long 时间戳
success Boolean 是否成功
result List 结果

result 说明

名称 类型 描述
identifier String 标识
name String 名称

请求示例

GET /v1.0/devices/vedeo234567/multiple-names

返回示例

{
    "t":1234876331,
    "success":true,
    "result": [
    {
        "identifier":"",
        "name":""
    }]
}

错误码

以下为该接口常见的业务异常，更多的异常错误，请参考 全局错误码。

错误码 说明
500 系统错误
上一篇获取应用的名称、logo、描述、创建时间等
下一篇全屋智能 API
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2024 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English