Scheduled Tasks API
Overview
The API level supports the timing function.
This is a relatively independent task execution module that maintains a Schedule object.
notice: Call Api Function to Query/Update/Delete Schedule info.
Call Validation
For more information, see the Authentication method
Schedule Parameter Description
Every schedule task includes name、enabled、trigger、push those four fields.
Keyword | Type | Optianlal | Description |
---|---|---|---|
name | string | required | The name of the schedule task, which cannot exceed 255 bytes and consists of Chinese characters, letters, numbers and underscores. |
enabled | bool | required | The current status of the task. It must be true when creating a task. |
trigger | JSOS Object | required | Timing task trigger time and trigger conditions. Currently, only scheduled tasks (single) are supported. Please refer to the single description for details. |
push | JSOS Object | required | For push content information, refer to the fields in the Create a push API |
Single Description
The trigger conditions of the schedule task, including the trigger time and the scheduled task type.
Keyword | Type | Option | Description |
---|---|---|---|
time | string | required | The trigger time of the scheduled task, using the yyyy-mm-dd hh:mm:ss format, eg: "2014-02-15 13:16:59" can not be "2014-2-15 13:16:59" or "2014-12-15 13:16", The latest time for scheduled tasks cannot exceed one year |
zone_type | int | required | the type of the scheduled task: |
Create a scheduled task
request api task
POST https://webpush.api.engagelab.cc/v4/schedules
Call restrictions
- The total number of valid scheduled tasks (currently unexpired) is 1000 by default. If the total number is exceeded, the new scheduled task will prompt failure.
- The maximum span time of the task is unlimited, but it is recommended not to exceed 1 year.
Request Example
request header
POST /v4/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
request body
{
"name":"schedule push example",
"enabled":true,
"trigger":{
"single":{
"time":"2022-11-23 19:20:00",
"zone_type":1
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web",
"notification":{
"alert":"Api web timed task", //optional
"web":{
"alert":"Api web timed task",
"title":"Api web timed task",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
request body description
- zone_type is the required field, the value is 1 or 2, Otherwise, it will be pushed according to the time zone of the server
- The enabled field must be true when it is first created. Cannot create a task with enabled: false, otherwise the creation will fail.
- pUse must be a valid and legal push action, or the creation fails.
Return Example:
Return Success
< HTTP/1.1 200 OK
< Server: fasthttp
< Date: Thu, 01 Dec 2022 07:17:45 GMT
< Content-Type: application/json
< Content-Length: 85
{
"schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
"name": "the schedule task name"
}
Return Error
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json; charset=utf-8
{
"error": {
"code": 28400,
"message": "error message"
}
}
Get a valid scheduled task list
- Gets the list of currently valid (unexpired) schedules.
Request Api Url
GET https://webpush.api.engagelab.cc/v4/schedules?page=
Request Example
Request Header
GET /v4/schedules?page=
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
- Returns the detailed schedule-task list of the current request page. If no page is specified, the page is 1.
- Sorting rule: creation time, completed by schedule-service.
- If the number of requested pages is greater than the total number of pages, the page is the request value and the schedule is empty.
- Each page can return up to 50 tasks. If the actual number of tasks on the request page is less than 50, the actual number of tasks will be returned.
Return Example
Return success
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"total_count": 1000,
"total_pages": 5
"page": 4, // current page
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled":ture
},
{}, // detail info list]
}
- 1000 schedule-tasks,5 total pages, the current page is 4,including 50 schedule-tasks info。
- the schedules array is the schedule-tasks detail list
Get scheduled task details
- Get the details of the scheduled task with the current user's schedule task id {schedule_id}
Request Api Url
GET https://webpush.api.engagelab.cc/v4/schedules/{schedule_id}
Request Example
Request Header
GET /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Return Example
Return Success
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Data
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "the scheduled task example",
"enabled": true,
"trigger": {...},
"push": {...}
}
- if the schedule_id is not exists, then return 404, or it will return the detail of schedule-task
Get all the message ids of the scheduled task
- get all the message ids of the current user's scheduled task that is id {schedule_id}
Request Api Url
GET https://webpush.api.engagelab.cc/v4/schedules/{schedule_id}/msg-ids
Request Example
Request Header
GET /v4/schedules/{schedule_id}/msg_ids
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Return Example
Return Success
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Error
{
"count": 3,
"msgids": [
"12345567",
"2234567",
"3234567"
]
}
Update the Scheduled Task
- Update the schedule task of the specified id
Request Api Url
PUT https://webpush.api.engagelab.cc/v4/schedules/{schedule_id}
Request Example
PUT /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/x-www-form-urlencoded
Accept: application/json
{
"name": "task",
"enabled": true,
"trigger": {...},
"push": {...}
}
- Can not update the scheduled task that had expired
- The timing tasks pushed by the terminal time zone and the timing tasks pushed by the master time zone cannot be updated with each other, and vice versa.
- Can update the one or mulitples fileds in ["name", "enabled", "trigger", "push"] array. The update body can not a part, need to be a whole body. List below:
{
"name":"the scheduled task example",
"enabled":true,
"trigger":{
"single":{
"time":"2022-11-23 19:20:00",
"zone_type":1
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web",
"notification":{
"alert":"api web scheduled task",
"web":{
"title":"api web scheduled task",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
- The following are examples of incorrect updates and corresponding correct updates:
## Incorrect: only update the alert in the push field:
{
"push": {
"alert": "web scheduled task"
}
}
## Correct: update the alert in the push field:
{
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web scheduled task",
"notification":{
"alert":"web ",
"web":{
"title":"api web scheduled task",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
## the push field must be valid, or it will update failed
Return Example
Return Success
HTTP/1.0 200 CREATED
Content-Type: application/json
{
"name":"Timed push example",
"enabled":true,
"trigger":{
"single":{
"time":"2022-11-23 19:20:00",
"zone_type":1
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web",
"notification":{
"alert":"Web scheduled task",
"web":{
"title":"Web scheduled task",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
Return Error
- schedule_id is invalid
HTTP/1.0 404 Not Found
Content-Type: application/json
- Illegal update operation
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
Delete schedule Task
Request Api Url
DELETE https://webpush.api.engagelab.cc/v4/schedules/{schedule_id}
The schedule_id is the id of the created schedule task. If the schedule_id is illegal or not a valid id, then 404.
request example
DELETE /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
return example
Return Success
HTTP/1.0 200
Content-Type: application/json
Content-Length: 0
Return Error
HTTP/1.0 404 Not Found
Content-Type: application/json
Content-Length: 0
{
"error":{
"code":28404,
"message":"error message"
}
}
Error Code
Code | HTTP | Description | Error Message | Detail Desciption |
---|---|---|---|---|
28000 | 200 | return success | nil | success status |
28100 | 400 | parameter is invalid | The schedule-task is invalid:section is invalid;has been at term;expired;request data is not json;update target task;Delete target task;schedule request is not exist | |
28101 | 401 | Authentication failed | Basic authentication failed. | appkey、masterscrect are schedule servernot match |
28104 | 404 | the schedule task is not exists | Request schedule operation doesn't exist | The corresponding task has been sent, or the schedule id is incorrect. |
28105 | 404 | Set time without corresponding push target | The push task is invalid. There is no push target for the scheduled time | push time parameter is invalid |
28200 | 500 | internal error | Server Internal error. | An unexpected error occurred. |
28203 | 503 | Internal system error, please try again later | Execute action timeout, please try later again | Communication error with schedule-server. |