定时任务 API
最新更新:2023-01-06
定时任务 API
API 层面支持定时功能。
这是一个相对独立的任务执行模块,维护一个 Schedule 对象。
注: 调 API 创建的定时任务只能调 API 获取 / 修改 / 删除。
调用验证
详情参见 REST API 概述的 鉴权方式 说明。
Schedule 参数说明
每一个 schedule 任务,都由 name、enabled、trigger、push 这四个小节组成。
参数 | 类型 | 是否可选 | 含义 |
---|---|---|---|
name | String | 必填 | 表示 schedule 任务的名字,不得超过 255 字节,由汉字、字母、数字、下划线组成。 |
enabled | Boolean | 必填 | 表示任务当前状态,创建任务时必须为 true。 |
trigger | JSON Object | 必填 | 定时任务触发时间和触发条件。当前只支持定时任务(single),详情参见 single 说明。 |
push | JSON Object | 必填 | 推送内容信息,参考 app push 文档 中各个字段。 |
single 说明
表示 schedule 任务的触发条件,包含触发时间、定时任务类型。
参数 | 类型 | 是否可选 | 含义 |
---|---|---|---|
time | String | 必填 | 表示定时任务的触发时间,使用 yyyy-mm-dd hh:mm:ss的标准时间格式表示。如 "2014-02-15 13:16:59",不能为 "2014-2-15 13:16:59" 或 "2014-12-15 13:16",即日期时间格式必须完整。定时任务的最晚时间不能超过一年。 |
zone_type | Int | 必填 | 表示定时任务的类型,1 表示按照主站设置的时区推送,2 表示按照用户终端所在的时区推送。 |
创建定时任务
调用地址
POST https://push.api.engagelab.cc/v4/schedules
调用限制
- 有效定时任务(当前未过期数)总数默认为 1000 个,超过这个总数后新建定时任务会提示失败。
- 定时任务的最大跨度时间不限制,但建议不超过 1 年。
请求示例
请求报头
POST /v4/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
POST /v4/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
此代码块在浮窗中显示
请求数据
{
"name":"定时推送示例",
"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终端定时任务",
"android":{
"title":"api终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
{
"name":"定时推送示例",
"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终端定时任务",
"android":{
"title":"api终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
此代码块在浮窗中显示
请求数据说明
- zone_type 必需填写为指定字段值(1 或 2),否则会按照服务器所在时区进行推送。
- 定时任务首次创建时其 enabled 项必须为 true。不能创建 enabled:false 的任务,否则创建失败。
- push 必须为有效合法的 push 动作,否则创建失败。
返回示例
成功返回
< HTTP/1.1 200 OK
< Server: fasthttp
< Date: Thu, 01 Dec 2022 07:17:45 GMT
< Content-Type: application/json
< Content-Length: 85
< 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": "定时任务名称"
}
{
"schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
"name": "定时任务名称"
}
此代码块在浮窗中显示
失败返回
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json; charset=utf-8
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
{
"error": {
"code": 28400,
"message": "error message"
}
}
{
"error": {
"code": 28400,
"message": "error message"
}
}
此代码块在浮窗中显示
获取有效的定时任务列表
- 获取当前有效(未过期)的 schedule 列表。
调用地址
GET https://push.api.engagelab.cc/v4/schedules?page=
请求示例
请求报头
GET /v4/schedules?page=
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
GET /v4/schedules?page=
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
此代码块在浮窗中显示
- 返回当前请求页的详细的 schedule-task 列表,如未指定 page 则 page 为 1。
- 排序规则:创建时间,由 schedule-service 完成。
- 如果请求页数大于总页数,则 page 为请求值,schedules 为空。
- 每页最多返回 50 个 task,如请求页实际的 task 的个数小于 50,则返回实际数量的 task。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
{
"total_count": 1000, // 表示总数
"total_pages": 5, // 总页数。
"page": 4, // 当前为第四页。
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled":ture
},
{}, // 详细信息列表。]
}
{
"total_count": 1000, // 表示总数
"total_pages": 5, // 总页数。
"page": 4, // 当前为第四页。
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled":ture
},
{}, // 详细信息列表。]
}
此代码块在浮窗中显示
- 以上表示总共 1000 个 schedule-task,总共 5 页,当前为第 4 页,包含 50 个 schedule-task 的信息。
- 返回的 schedules 为 schedule-task 的详细信息列表。
获取定时任务详情
- 获取当前用户的 schedule 任务 id 为 {schedule_id} 的定时任务的详情。
调用地址
GET https://push.api.engagelab.cc/v4/schedules/{schedule_id}
请求示例
请求报头
GET /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
GET /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
此代码块在浮窗中显示
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "定时推送示例",
"enabled": true,
"trigger": {...},
"push": {...}
}
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "定时推送示例",
"enabled": true,
"trigger": {...},
"push": {...}
}
此代码块在浮窗中显示
- 如 schedule_id 不存在,则返回 404,否则返回实际 schedule-task 的详情。
获取某个定时任务的所有消息 id
- 获取当前用户的 schedule 任务 id 为 {schedule_id} 对应的所有消息 id 列表。
调用地址
GET https://push.api.engagelab.cc/v4/schedules/{schedule_id}/msg-ids
请求示例
请求报头
GET /v4/schedules/{schedule_id}/msg_ids
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
GET /v4/schedules/{schedule_id}/msg_ids
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
此代码块在浮窗中显示
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
{
"count": 3,
"msgids": [
"12345567",
"2234567",
"3234567"
]
}
{
"count": 3,
"msgids": [
"12345567",
"2234567",
"3234567"
]
}
此代码块在浮窗中显示
更新定时任务
- 更新指定 id 的 schedule 任务。
调用地址
PUT https://push.api.engagelab.cc/v4/schedules/{schedule_id}
请求示例
PUT /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/x-www-form-urlencoded
Accept: application/json
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": {...}
}
{
"name": "task",
"enabled": true,
"trigger": {...},
"push": {...}
}
此代码块在浮窗中显示
- 不能更新已过期的 schedule 任务。
- 按终端时区推送的定时任务与按主站时区推送的定时任务之间不能进行相互更新,反之亦然。
- 更新操作可为 "name","enabled"、"trigger" 或 "push" 四项中的一项或多项。不支持部分更新,如更新之前的任务为:
{
"name":"定时推送示例",
"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 终端定时任务",
"android":{
"title":"api 终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
{
"name":"定时推送示例",
"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 终端定时任务",
"android":{
"title":"api 终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
此代码块在浮窗中显示
- 则以下为错误的更新及与之对应的正确的更新示例:
## WRONG: 更新 push 中的平台为 ios:
{
"push": {
"body": {
"platform": "ios"
}
}
}
## RIGHT: 更新 push 中的平台为 ios:
{
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"ios",
"notification":{
"alert":"api 终端定时任务",
"ios":{
"title":"api 终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
## 此处的 push 更新后必须仍是有效的,否则也会更新失败。
## WRONG: 更新 push 中的平台为 ios:
{
"push": {
"body": {
"platform": "ios"
}
}
}
## RIGHT: 更新 push 中的平台为 ios:
{
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"ios",
"notification":{
"alert":"api 终端定时任务",
"ios":{
"title":"api 终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
## 此处的 push 更新后必须仍是有效的,否则也会更新失败。
此代码块在浮窗中显示
返回示例
成功返回
HTTP/1.0 200 CREATED
Content-Type: application/json
HTTP/1.0 200 CREATED
Content-Type: application/json
此代码块在浮窗中显示
{
"name":"定时推送示例",
"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 终端定时任务",
"ios":{
"title":"api 终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
{
"name":"定时推送示例",
"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 终端定时任务",
"ios":{
"title":"api 终端定时任务",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
此代码块在浮窗中显示
失败返回
- schedule_id 无效,不是有效的 id。
HTTP/1.0 404 Not Found
Content-Type: application/json
HTTP/1.0 404 Not Found
Content-Type: application/json
此代码块在浮窗中显示
- 更新操作不合法
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
此代码块在浮窗中显示
删除定时任务
调用地址
DELETE https://push.api.engagelab.cc/v4/schedules/{schedule_id}
schedule_id 为已创建的 schedule 任务的 id,如果 schedule_id 不合法即不是有效的 id,则 404。
请求示例
DELETE /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
DELETE /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
此代码块在浮窗中显示
返回示例
成功返回
HTTP/1.0 200
Content-Type: application/json
Content-Length: 0
HTTP/1.0 200
Content-Type: application/json
Content-Length: 0
此代码块在浮窗中显示
失败返回
HTTP/1.0 404 Not Found
Content-Type: application/json
Content-Length: 0
HTTP/1.0 404 Not Found
Content-Type: application/json
Content-Length: 0
此代码块在浮窗中显示
{
"error":{
"code":28404,
"message":"error message"
}
}
{
"error":{
"code":28404,
"message":"error message"
}
}
此代码块在浮窗中显示
错误码
Code | HTTP | 描述 | Error Message | 详细解释 |
---|---|---|---|---|
28000 | 200 | 正确返回 | nil | 成功状态码 |
28100 | 400 | 参数无效 | 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 | 鉴权失败 | Basic authentication failed. | appkey、masterscrect 不匹配。 |
28104 | 404 | 请求的 schedule 任务不存在 | Request schedule operation doesn't exist | 对应的任务已发送,或 schedule id 错误。 |
28105 | 404 | 设置时间无对应推送目标 | The push task is invalid. There is no push target for the scheduled time | push 时间参数错误 |
28200 | 500 | 系统内部错误 | Server Internal error. | 发生未预料错误。 |
28203 | 503 | 系统内部错误,建议稍后重试 | Execute action timeout, please try later again | 与 schedule-server 通信错误。 |