Scheduled Tasks

Last Updated on : 2024-06-05 03:15:11download

API list

API endpoint	Description
timer.add	Add a scheduled task of a device.
timer.list	Query all scheduled tasks of a device.
timer.listByCategory	Get scheduled tasks of a category for a device.
timer.edit	Update information about a scheduled task of a device.
timer.status	Update the status of a scheduled task group of a device.
timer.delete	Delete all scheduled tasks of a device.
timer.deleteByCategory	Delete all scheduled tasks of a category for a device.
timer.deleteByGroup	Delete a scheduled task group of a category for a device.

Add a scheduled task of a device

API description

Add a scheduled task of a device. Set the loops parameter to make the scheduled task recur regularly or not:

Recurring scheduled task: The task can recur weekly on a day from Monday to Sunday.
Non-recurring scheduled task: The task runs on a specified point of time. This point of time must be later than the current time. Otherwise, the scheduled task cannot be created, and the system indicates that the task has expired.

API endpoint

action: timer.add

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
category	String	The category of the scheduled task.	Yes
loops	String	A seven-digit number that consists of `0` and `1`: - `0`: The scheduled task is off. -`1`: The scheduled task is on. Example: `0000010` represents that the scheduled task takes effect only on Friday and is disabled on other days in a week.	Yes
time_zone	String	The timezone, such as `+08:00`.	Yes
timezone_id	String	The time zone ID. Example: `Asia/Shanghai`.	Yes
instruct	Array	The effective time and command of a scheduled task. Multiple scheduled tasks can be configured at the same time.	Yes

Description of instruct

Parameter name	Type	Description	Required
time	String	The time when the specified scheduled task takes effect.	Yes
date	String	The date on which the specified scheduled task takes effect. If `date` is passed in, set `loops` to `0000000` and `date` in the format of `20181212`.	No
functions	Array	The command to be executed in the scheduled task.	Yes

Description of functions

Parameter name	Type	Description	Required
code	String	The `code` of the command to be executed.	Yes
value	Object	The `value` of the command to be executed.	Yes

Sample request

{
	"action": "timer.add",
	"params": {
    "device_id":"vdevo158417166464619",
    "loops":"0000000",
    "category":"test",
    "timezone_id":"Asia/Shanghai",
    "time_zone":"+8:00",
    "instruct":[
        {
            "functions":[
                {
                    "code":"switch",
                    "value":true
                },
                {
                	"code":"switch_vertical",
                    "value":true
                }
            ],
            "date":"20200320",
            "time":"17:41"
        }
    ]
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
group_id	String	The ID of the scheduled task.

Sample response

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

Query all scheduled tasks of a device

API description

Query all scheduled tasks that are added for a device ID.

API endpoint

action: timer.list

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
	"action": "timer.list",
	"params": {
    "device_id":"vdevo158417166464619"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
groups	Array	The list of scheduled tasks.
category	Object	The category status of the scheduled tasks.

Description of groups

Parameter name	Type	Description
timers	Object	The information about the scheduled tasks.
id	String	The ID of each scheduled task.

Description of category

Parameter name	Type	Description
category	String	The category of the scheduled tasks.
status	Integer	The category status of the scheduled tasks.

Description of timers

Parameter name	Type	Description
date	String	The date on which a scheduled task takes effect.
timezone_id	String	The time zone ID.
loops	String	The information about a recurring scheduled task.
time	String	The time when a scheduled task recurs.
status	Integer	The status of a scheduled task. - `0`: The scheduled task is off. - `1`: The scheduled task is on. - `2`: The scheduled task is deleted.
functions	Array	The command to be executed in the scheduled task.
group_order	Integer	The sequence of scheduled tasks in a group.
is_app_push	Boolean	Indicates whether push notifications are enabled on the app. (Unavailable currently)
timer_id	Integer	The unique identifier of a scheduled task.

Description of functions

Parameter name	Type	Description	Required
code	String	The `code` of the command to be executed.	Yes
value	Object	The `value` of the command to be executed.	Yes

Sample response

{
    "result": [
        {
            "category": {
                "category": "test",
                "status": 1
            },
            "groups": [
                {
                    "id": "000000mwf3",
                    "timers": [
                        {
                            "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
}

Get scheduled tasks of a category for a device

API description

Get scheduled tasks of a category for a device.

API endpoint

action: timer.listByCategory

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
category	String	The category of the scheduled task.	Yes

Sample request

{
	"action": "timer.listByCategory",
	"params": {
    "device_id":"vdevo158132564936223",
    "category":"test"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
groups	Array	The list of scheduled tasks.
category	Object	The time when the device status was last updated.

Description of groups

Parameter name	Type	Description
timers	Object	The information about the scheduled tasks.
id	String	The ID of each scheduled task.

Description of category

Parameter name	Type	Description
category	String	The category of the scheduled tasks.
status	Integer	The category status of the scheduled tasks.

Description of timers

Parameter name	Type	Description
date	String	The date on which a scheduled task takes effect.
timezone_id	String	The time zone ID.
loops	String	The information about a recurring scheduled task.
time	String	The time when a scheduled task recurs.
status	Integer	The status of a scheduled task. - `0`: The scheduled task is off. - `1`: The scheduled task is on. - `2`: The scheduled task is deleted.
functions	Array	The command to be executed in the scheduled task.
group_order	Integer	The sequence of scheduled tasks in a group.
is_app_push	Boolean	Indicates whether push notifications are enabled on the app. (Unavailable currently)
timer_id	Integer	The unique identifier of a scheduled task.

Description of functions

Parameter name	Type	Description	Required
code	String	The `code` of the command to be executed.	Yes
value	Object	The `value` of the command to be executed.	Yes

Sample response

{
    "result": [
        {
            "category": {
                "category": "test",
                "status": 1
            },
            "groups": [
                {
                    "id": "000000mwf3",
                    "timers": [
                        {
                            "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
}

Update information about a scheduled task group of a device

API description

Update information about a scheduled task group of a device.

API endpoint

action: timer.edit

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
group_id	String	The ID of the scheduled task group.	Yes
loops	String	A seven-digit number that consists of `0` and `1`: - `0`: The scheduled task is off. - `1`: The scheduled task is off. Example: `0000010` represents that the scheduled task takes effect only on Friday and is disabled on other days in a week.	Yes
category	String	The category of each scheduled task.	Yes
time_zone	String	The timezone, such as `+08:00`.	Yes
timezone_id	String	The time zone ID. Example: `Asia/Shanghai`.	Yes
instruct	Array	The effective time and command of a scheduled task. Multiple scheduled tasks can be configured at the same time.	Yes

Description of instruct

Parameter name	Type	Description	Required
time	String	The time when the specified scheduled task takes effect.	Yes
date	String	The date on which the specified scheduled task takes effect. If `date` is passed in, set `loops` to `0000000` and `date` in the format of `20181212`.	No
functions	Array	The command to be executed in the scheduled task.	Yes

Description of functions

Parameter name	Type	Description	Required
code	String	The `code` of the command to be executed.	Yes
value	Object	The `value` of the command to be executed.	Yes

Sample request

{
	"action": "timer.edit",
	"params": {
    "device_id":"vdevo158132564936223",
    "group_id":"000000mwf3",
    "loops":"0000000",
    "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
                }
            ]
        }
		}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful. This parameter value is empty if the API call fails.

Sample response

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

Update the status of a scheduled task group of a device

API description

Update the status of a scheduled task group of a device.

API endpoint

action: timer.status

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
group_id	String	The ID of the scheduled task group.	Yes
category	String	The category of the scheduled task group.	Yes
status	String	The status of a scheduled task. - `0`: The scheduled task is off. - `1`: The scheduled task is on. - `2`: The scheduled task is deleted.	Yes

Sample request

{
	"action": "timer.status",
	"params": {
    "device_id":"vdevo158132564936223",
    "category":"test",
    "group_id":"000000mwf3",
    "status":"0"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful. This parameter value is empty if the API call fails.

Sample response

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

Delete all scheduled tasks of a device

API description

Delete all scheduled tasks of a device.

API endpoint

action: timer.delete

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
	"action": "timer.delete",
	"params": {
    "device_id":"vdevo158132564936223"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful. This parameter value is empty if the API call fails.

Sample response

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

Delete all scheduled tasks of a category for a device

API description

Delete all scheduled tasks of a device.

API endpoint

action: timer.deleteByCategory

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
category	String	The category of the scheduled task group.	Yes

Sample request

{
	"action": "timer.deleteByCategory",
	"params": {
    "device_id":"vdevo158132564936223",
    "category":"test"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful. This parameter value is empty if the API call fails.

Sample response

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

Delete a scheduled task group of a category for a device

API description

Delete a scheduled task group of a category for a device.

API endpoint

action: timer.deleteByGroup

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
category	String	The category of the scheduled task group.	Yes
group_id	String	The ID of the scheduled task group.	Yes

Sample request

{
	"action": "timer.deleteByGroup",
	"params": {
    "device_id":"vdevo158132564936223",
    "category":"test",
    "group_id":"0000002ftg"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. - `true`: succeeded - `false`: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful. This parameter value is empty if the API call fails.

Sample response

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