定时管理

更新时间：2023-05-22 06:38:12下载pdf

本文介绍了定时管理相关的接口。

API 列表

请求方式	API	描述
POST	/v1.0/devices/{device_id}/timers	设备添加定时任务
GET	/v1.0/devices/{device_id}/timers	查询设备下的定时任务列表
GET	/v1.0/devices/{device_id}/timers /categories/{category}	获取某⼀个分类下⾯的定时任务信息
PUT	/v1.0/devices/{device_id}/timers /groups/{group_id}	更新设备的某一个定时任务组的信息
PUT	/v1.0/devices/{device_id}/timers /categories/{category}/groups/{group_id}/status	更新设备定时任务组的状态
DELETE	/v1.0/devices/{device_id}/timers	删除设备下全部定时任务
DELETE	/v1.0/devices/{device_id}/timers /categories/{category}	删除某个分类的定时任务
DELETE	/v1.0/devices/{device_id}/timers /categories/{category}/groups/{group_id}	删除某个分类下面的某个定时组的定时任务

设备添加定时任务

接口描述

该接口为设备添加定时任务。通过参数 loops，可分为循环定时任务与非循环定时任务。

循环定时：以一周为循环，可设定周一到周日的循环定时。
非循环定时：设定指定时间节点的定时任务，接口会对设定的时间节点做限定。该时间节点需要在当前时间之后，否则无法创建定时任务，并提示定时任务已过期。

接口地址

POST  /v1.0/devices/{device_id}/timers

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID。
category	String	BODY	是	定时分类。
loops	String	BODY	是	请求失败返由 0 和 1 组成的七位数字，0 代表关闭，1 代表开启。例如`0000010`代表周日，周一，周⼆，周三，周四，周五定时任务关闭，周六定时任务开启。
time_zone	String	BODY	是	时区，中国区传 `+08:00`。
timezone_id	String	BODY	是	时区 ID，比如 `Asia/shanghai`。
instruct	Array<instruct>	BODY	是	定时任务具体的时间和设备指令，⽀持同时设置多个定时任务。
alias_name	String	BODY	否	别名。

instruct 说明

参数名	类型	必填	说明
time	String	是	定时任务执行的时间
functions	Array<functions>	是	定时执行的指令
date	String	否说明：传 `date` 时 `loops` 为 `0000000` ，`date` 格式为 20181212。	定时任务执行的日期

functions 说明

参数名	类型	必填	说明
code	String	是	要执⾏指令的 code
value	Object	是	要执⾏指令的 value

返回参数

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

result 说明

参数名	类型	说明
group_id	String	定时任务的 ID

请求示例

POST  /v1.0/devices/vdevo153490924111111/timers
{
    "instruct":[
        {
            "functions":[
                {
                    "code":"switch_led",
                    "value":true
                },
                {
                	"code":"bright_value_v2",
                    "value":500
                }
            ],
            "date":"20200210",
            "time":"17:41"
        }
    ],
    "loops":"0000000",
    "category":"test",
    "timezone_id":"Asia/Shanghai",
    "time_zone":"+8:00"
}

SDK 示例

暂无

返回示例

{
    "success": true,
    "result": {
        "group_id": "0000002ftg"
		} 
}

错误码

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

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

查询设备下的定时任务列表

接口描述

该接口用于查询指定设备 ID 下已添加定时任务的详细信息列表。

接口地址

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

请求参数

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

返回参数

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

result 说明

参数名	类型	说明
groups	Array<groups>	定时任务信息列表
category	Object<category>	定时任务的分类状态信息

groups 说明

参数名	类型	说明
timers	Object<timers>	定时任务信息
id	String	定时任务编号

category 说明

参数名	类型	说明
category	String	定时任务的分类
status	Integer	定时任务的分类的状态

timers 说明

参数名	类型	说明
date	String	设置定时的日期
timezone_id	String	时区 ID
loops	String	循环定时信息
time	String	设置的时间
status	Integer	定时任务的状态 0：关闭 1：开启 2：删除
functions	Array<functions>	定时的指令
group_order	Integer	指定排序
timer_id	Integer	定时信息的唯一标识
alias_name	String	备注

functions 说明

参数名	类型	必填	说明
code	String	是	要执⾏指令的 code
value	Object	是	要执⾏指令的 value

请求示例

GET /v1.0/devices/vdevo154458004640011/timers

SDK 示例

暂无

返回示例

{
    "result": [
        {
            "category": {
                "category": "test",
                "status": 1
            },
            "groups": [
                {
                    "id": "000000mwf3",
                    "timers": [
                        {
                            "alias_name": "",
                            "date": "20200210",
                            "functions": [
                                {
                                    "code": "bright_value_v2",
                                    "value": 5000
                                },
                                {
                                    "code": "switch_led",
                                    "value": true
                                }
                            ],
                            "group_order": 0,
                            "is_app_push": false,
                            "loops": "0000000",
                            "status": 0,
                            "time": "17:30",
                            "timer_id": 4906528,
                            "timezone_id": "Asia/Shanghai"
                        }
                    ]
                }
            ]
        }
    ],
    "success": true,
    "t": 1581336613789
}

错误码

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

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

获取设备某一个分类下⾯的定时任务信息

接口描述

该接口用于获取指定设备下某⼀个分类下⾯的定时任务信息。

接口地址

GET /v1.0/devices/{device_id}/timers/categories/{category}

请求参数

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

返回参数

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

result 说明

参数名	类型	说明
groups	Array<groups>	定时任务信息列表
category	Object<category>	设备状态更新时间

groups 说明

参数名	类型	说明
timers	Object<timers>	定时任务信息
id	String	定时任务编号

category 说明

参数名	类型	说明
category	String	定时任务的分类
status	Integer	定时任务的分类的状态

timers 说明

参数名	类型	说明
date	String	设置定时的日期
timezone_id	String	时区 ID
loops	String	循环定时信息
time	String	设置的时间
status	Integer	定时任务的状态 0：关闭 1：开启 2：删除
functions	Array<functions>	定时的指令
group_order	Integer	指定排序
timer_id	Integer	定时信息的唯一标识
alias_name	String	备注

functions 说明

参数名	类型	必填	说明
code	String	是	要执⾏指令的 code
value	Object	是	要执⾏指令的 value

请求示例

GET /v1.0/devices/vdevo154458004640011/timers/categories/10

SDK 示例

暂无

返回示例

{
    "result": [
        {
            "category": {
                "category": "test",
                "status": 1
            },
            "groups": [
                {
                    "id": "000000mwf3",
                    "timers": [
                        {
                            "alias_name": "",
                            "date": "20200202",
                            "functions": [
                                {
                                    "code": "bright_value_v2",
                                    "value": 5000
                                },
                                {
                                    "code": "switch_led",
                                    "value": true
                                }
                            ],
                            "group_order": 0,
                            "is_app_push": false,
                            "loops": "0000000",
                            "status": 0,
                            "time": "17:30",
                            "timer_id": 4906528,
                            "timezone_id": "Asia/Shanghai"
                        }
                    ]
                }
            ]
        }
    ],
    "success": true,
    "t": 1581336613789
}

错误码

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

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

更新设备的某⼀个定时任务组的信息

接口描述

该接口用于更新设备的某一个定时任务组的信息。

接口地址

PUT /v1.0/devices/{device_id}/timers/groups/{group_id}

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID。
group_id	String	URI	是	定时任务组 ID。
loops	String	BODY	是	由 0 和 1 组成的七位数字，0 代表关闭，1 代表开启。例如：`0000010` 代表周日、周⼀、周⼆、周三、周四和周五定时任务关闭，周六定时任务开启。
category	String	BODY	是	定时任务类别。
time_zone	String	BODY	是	时区，中国区传 `+08:00`。
timezone_id	String	BODY	是	时区 ID，例如 `Asia/shanghai`。
instruct	Array<instruct>	BODY	是	定时任务具体的时间和设备指令，支持同时设置多个定时任务。
alias_name	String	BODY	否	别名。

instruct 说明

参数名	类型	必填	说明
time	String	是	定时任务执⾏的时间
functions	Array<functions>	是	定时执行的指令
date	String	否说明：传 `date` 时 `loops` 为 `0000000` ，`date` 格式为 20181212。	定时任务执⾏的日期

functions 说明

参数名	类型	必填	说明
code	String	是	要执⾏指令的 code
value	Object	是	要执⾏指令的 value

返回参数

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

请求示例

PUT /v1.0/devices/vdevo154458004640011/timers/groups/100
      
{
    "loops":"0001000",
    "time_zone":"+08:00",
    "timezone_id":"Asia/ShangHai",
    "category":"test",
    "instruct":[
        {
            "time":"12:00",
            "date":"20181212",
            "functions":[
                {
                    "code":"switch",
                    "value":true
                },
                {
                    "code":"bright",
                    "value":100
                }
            ]
        },
        {
            "time":"12:10",
            "date":"20181212",
            "functions":[
                {
                    "code":"switch",
                    "value":false
                }
            ]
        }
    ]
}

SDK 示例

暂无

返回示例

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

错误码

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

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

更新设备定时任务组的状态

接口描述

该接口用于更新设备定时任务组的状态。

接口地址

PUT  /v1.0/devices/{device_id}/timers/categories/{category}/groups/{group_id}/status

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID
group_id	String	URI	是	定时任务组 ID
category	String	URI	是	定时任务组分类
value	String	BODY	是	定时任务状态 0：关闭 1：开启 2：删除

返回参数

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

请求示例

PUT /v1.0/devices/vdevo154458004640011/timers/categories/100/groups/0000002ftg/status
{
	"value": "0"
}

SDK 示例

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

返回示例

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

错误码

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

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

删除设备下的所有定时任务

接口描述

该接口用于删除设备下的所有定时任务。

接口地址

DELETE  /v1.0/devices/{device_id}/timers

请求参数

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

返回参数

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

请求示例

DELETE  /v1.0/devices/vdevo154458004640011/timers

SDK 示例

暂无

返回示例

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

错误码

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

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

删除某个分类的定时任务

接口描述

该接口用于删除某个分类的定时任务。

接口地址

DELETE  /v1.0/devices/{device_id}/timers/categories/{category}

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID
category	String	URI	是	定时任务组分类

返回参数

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

请求示例

DELETE  /v1.0/devices/vdevo154458004640011/timers/categories/100

SDK 示例

暂无

返回示例

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

错误码

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

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

删除某个分类下⾯的某个定时组的定时任务

接口描述

删除某个分类下⾯的某个定时组的定时任务。

接口地址

DELETE  /v1.0/devices/{device_id}/timers/categories/{category}/groups/{group_id}

请求参数

参数名	类型	参数类型	必填	说明
device_id	String	URI	是	设备 ID
category	String	URI	是	定时任务分类
group_id	String	URI	是	定时任务组 ID

返回参数

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

请求示例

DELETE
/v1.0/devices/vdevo154458004640011/timers/categories/100/groups/0000002ftg

SDK 示例

暂无

返回示例

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

错误码

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

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

上一篇全屋智能场景联动

下一篇场景自动化