设备管理

更新时间:2023-08-17 08:46:42下载pdf

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

API 列表

请求方式 API 描述
GET /v1.0/devices/{device_id} 获取设备详情
GET /v1.0/users/{uid}/devices 获取用户下的设备列表
GET /v1.0/devices 获取设备列表
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}/status 获取设备最新状态

获取设备详情

接口描述

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

接口地址

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 权限非法

查询设备日志

接口描述

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

接口地址

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":""
    }]
}

获取设备最新状态

接口描述

根据设备 ID 来查询设备最新状态。

接口地址

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

请求参数

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

返回参数

参数名 类型 说明
code Integer 错误码
success Boolean 判断请求是否成功。
true:成功
false:失败
msg String 请求失败返回的信息,成功则返回空值。
result Boolean 是否成功。

请求示例

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

SDK 示例

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
List<Status> deviceStatus= client.getDeviceStatus(DEV_ID);
System.out.println("获取设备状态信息: ");
System.out.println(JSONObject.toJSONString(deviceStatus));

响应示例

{
      "success": true,
      "t": 1545447665981,
      "result": [
          {
              "code": "switch_led",
              "value": true
          },
          {
              "code": "work_mode",
              "value": "scene_2"
          },
          {
              "code": "bright_value",
              "value": 25
          },
          {
              "code": "temp_value",
              "value": 0
          },
          {
              "code": "colour_data",
              "value": "{\"h\":37.0,\"s\":255.0,\"v\":189.0}"
          },
          {
              "code": "scene_data",
              "value": ""
          },
          {
              "code": "flash_scene_1",
              "value": ""
          },
          {
              "code": "flash_scene_2",
              "value": ""
          },
          {
              "code": "flash_scene_3",
              "value": ""
          },
          {
              "code": "flash_scene_4",
              "value": "{\"bright\":255,\"frequency\":80,\"hsv\":[{\"h\":0.0,\"s\":255.0,\"v\":255.0},{\"h\":120.0,\"s\":255.0,\"v\":255.0},{\"h\":240.0,\"s\":255.0,\"v\":255.0},{\"h\":300.0,\"s\":255.0,\"v\":255.0},{\"h\":240.0,\"s\":255.0,\"v\":255.0},{\"h\":0.0,\"s\":255.0,\"v\":255.0}],\"temperature\":255}"
          }
      ]
  }

错误码

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

错误码 说明
500 系统错误