定时任务 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 通信错误。