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
}