Scheduled Tasks API
Overviews
The API supports the timing function.
This is a relatively independent task execution module, which maintains a Schedule object.
tips: Scheduled tasks created by calling API can only be called API Query/Modify/Delete.
Request Authentication
See REST API overview for details: Authentication method .
Schedule Parameter Description
Each schedule task consists of four fields: name, enabled, trigger, and push
parameter | type | option | description |
---|---|---|---|
name | String | required | Schedule name, which cannot exceed 255 bytes, consists of Chinese characters, letters, numbers and underscores |
enabled | Boolean | required | Schedule task status,Must be true when creating a task |
trigger | JSON Object | required | Timing task trigger time and trigger conditions. Currently, only scheduled tasks (single) are supported,See the single description for details |
push | JSON Object | required | Push content,see the Create Push API for details |
single description
Indicates the trigger condition of schedule task, including trigger time and scheduled task type.
parameters | type | option | description |
---|---|---|---|
time | String | required | Indicates the trigger time of the scheduled task, which is expressed in the standard time format of yyyy mm dd hh: mm: ss. For example, "2014-02-15 13:16:59" cannot be "2014-2-15 13:16:59" or "2014-12-15 13:16", that is, the date time format must be complete. The latest time of scheduled tasks cannot exceed one year. |
zone_type | Int | required | Indicates the type of timed task, 1 indicates push according to the time zone set by the master station, and 2 indicates push according to the time zone where the user terminal is located. |
Create schedule task
Request Api Url
POST https://push.api.engagelab.cc/v4/schedules
Request api limit
- The total number of valid scheduled tasks (currently unexpired) is 1000 by default. If the total number is exceeded, a new scheduled task will prompt failure.
- The maximum span time of fixed time tasks is not limited, 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":"the schedule 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":"android",
"notification":{
"alert":"api schedule task example",
"android":{
"title":"api schedule task example",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
Request Data Description
- zone_type must be filled in as the specified field value (1 or 2), otherwise it will be pushed according to the time zone of the server
- The enabled item of a scheduled task must be true when it is first created. Cannot create the enabled: false task, otherwise the creation fails.
- The push must be a valid and legal push action, otherwise the creation fails.
Response example
Success response
< 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"
}
failed response
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
- Get a valid scheduled task list
request api url
GET https://push.api.engagelab.cc/v4/schedules?page=
Request example
request headers
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
- Collation: creation time, completed by schedule service.
- If the number of request pages is greater than the total number of pages, page is the request value and schedules 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.
Response example
Success response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"total_count": 1000, // the total count of schedule task is 1000
"total_pages": 5, // total page is 5
"page": 4, // the current page is 4
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled":ture
},
{}, // Detailed list of information.]
}
- The above indicates that there are 1000 schedule tasks in total, 5 pages in total. Currently, it is the fourth page, containing 50 schedule tasks.
- Schedules field is the detailed information list of schedule task
Get scheduled task details
- Get the details of the scheduled task whose schedule task id is {schedule_id} for the current user
Request api url
GET https://push.api.engagelab.cc/v4/schedules/{schedule_id}
Request example
request headers
GET /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
response example
Success response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
response data
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "schedule push task example",
"enabled": true,
"trigger": {...},
"push": {...}
}
- if schedule_id does not exist,return code 404, or return the detail of the schedule-task.
Get all message ids of a scheduled task
- Get the list of all message ids corresponding to the schedule task id {schedule_id} of the current user.
request api url
GET https://push.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
response example
Success response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
response data
{
"count": 3,
"msgids": [
"12345567",
"2234567",
"3234567"
]
}
Update scheduled tasks
- Update the schedule task with the specified id.
Request api url
PUT https://push.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": {...}
}
- You cannot update an expired schedule task.
- Timed tasks pushed by terminal time zone cannot be updated with those pushed by master station time zone.
- The update operation can be one or more of "name", "enabled", "trigger" or "push". The message body need include all the fields, does not suport the part of the task.
{
"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":"android",
"notification":{
"alert":"api device scheduled tasks",
"android":{
"title":"api device scheduled tasks",
"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:
## WRONG: Update the platform in push to ios:
{
"push": {
"body": {
"platform": "ios"
}
}
}
## RIGHT: Update the platform in push to ios:
{
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"ios",
"notification":{
"alert":"api device scheduled tasks",
"ios":{
"title":"api device scheduled tasks",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
## The push here must still be valid after updating, otherwise the update will fail.
Response example
Success response
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":"ios",
"notification":{
"alert":"api device scheduled tasks",
"ios":{
"title":"api device scheduled tasks",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
Failed response
- schedule_id is invalid, is not a valid id。
HTTP/1.0 404 Not Found
Content-Type: application/json
- Illegal update operation
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
Delete scheduled task
Request api url
DELETE https://push.api.engagelab.cc/v4/schedules/{schedule_id}
The schedule_id is the ID of the created schedule task. If the schedule_id is illegal, that is, it is not a valid ID. And then returen 404
Request response
DELETE /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Response example
Success response
HTTP/1.0 200
Content-Type: application/json
Content-Length: 0
Failed response
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 Description |
---|---|---|---|---|
28000 | 200 | return success | nil | Success status code |
28100 | 400 | Invalid parameter | 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. | The appkey and mastersketch do not match. |
28104 | 404 | The requested schedule task does not exist | Request schedule operation doesn't exist | The corresponding task has been sent, or the schedule id is wrong. |
28105 | 404 | Setting time has no corresponding push target | The push task is invalid. There is no push target for the scheduled time | Wrong push time parameter |
28200 | 500 | System internal error | Server Internal error. | An unexpected error occurred. |
28203 | 503 | System internal error, please try again later | Execute action timeout, please try later again | Communication error with schedule server. |