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

设备管理

更新时间：2024-09-10 01:49:16下载pdf

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

API 列表

请求方式 API 描述
GET /v1.0/devices/{device_id} 获取设备详情
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} 修改设备名称
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/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 云端指令
5 App 移除
6 App 恢复出厂设置
7 App 提醒升级
8 硬件强制升级
9 App 强制升级
10 App 检测升级
11 IoT 平台移除
12 涂鸦开发者移除
13 用户端移除
16 节能小程序
-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 系统错误

获取设备最新状态

接口描述

根据设备 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 系统错误
上一篇设备控制
下一篇全屋多路设备功能设置
语言
简体中文
简体中文
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