定时任务 API v4

概述

API 层面支持定时功能。

这是一个相对独立的任务执行模块，维护一个 Schedule 对象。

注：调 API 创建的定时任务只能调 API 获取 / 修改 / 删除。

调用验证

详情参见 REST API 概述的鉴权方式说明。

Schedule 参数说明

每一个 schedule 任务，都由 name、enabled、trigger、push 这四个小节组成。

参数	类型	是否可选	含义
name	String	必填	表示 schedule 任务的名字，不得超过 255 字节，由汉字、字母、数字、下划线组成。
enabled	Boolean	必填	表示任务当前状态，创建任务时必须为 true。
trigger	JSON Object	必填	定时任务触发时间和触发条件。当前支持定时任务（single）和重复发送（periodical），详情参见后文说明。
push	JSON Object	必填	推送内容信息

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 表示按照用户终端所在的时区推送。

periodical 说明

参数	类型	是否可选	含义
start	String	必填	表示定期任务有效起始时间，格式必须严格为: "yyyy-MM-dd HH:mm:ss"，且时间必须为 24 小时制。
end	String	必填	表示定期任务的过期时间，格式同上。定期任务最大跨度不能超过一年。
time	String	必填	表示触发定期任务的定期执行时间，格式严格为: "HH:mm:ss"，且为 24 小时制。
time_unit	String	必填	表示定期任务的执行的最小时间单位有："day"、"week" 及 "month" 三种。大小写不敏感，如 "day", "Day", "DAy" 均为合法的 time_unit。
point	String	必填	一个列表，此项与 time_unit 相对应：见下表
zone_type	Int	必填	表示定时任务的类型，1 表示按照主站设置的时区推送，2 表示按照用户终端所在的时区推送。

point 参数详细信息:

time_unit	point	描述
day	NULL	当 time_unit 为 day 时 point 此项无效
week	"MON","TUE","WED","THU","FRI","SAT","SUN"	当 time_unit 为 week 时，point 为对应项的一项或多项，表示星期几进行触发，point 中的值大小写不敏感
month	"01","02","03" .... "31"	当 time_unit 为 month 时，point 为当前进行月对应的日期，且必须有效，如 month 为 2 月，则 31 或 30 日是不会进行触发的

创建定时任务

调用地址

v4/schedules

          
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":"web", "notification":{ "web": { "alert": "终端重复定期任务", "title": "终端重复定期任务", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "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":"web",
            "notification":{
                "web": {
                    "alert": "终端重复定期任务",
                    "title": "终端重复定期任务",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

此代码块在浮窗中显示

请求数据说明

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"
    }
}

此代码块在浮窗中显示

重复定时任务请求示例

{ "name":"定时推送示例 - 重复任务", "enabled":true, "trigger":{ "periodical": { "start": "2024-01-01 00:00:00", "end": "2024-02-10 00:00:00", "time": "12:00:00", "time_unit": "day", "point": [], "zone_type": 1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "终端重复定期任务", "title": "终端重复定期任务", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" }, } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"67890", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "name":"定时推送示例 - 重复任务",
    "enabled":true,
    "trigger":{
        "periodical": {
            "start": "2024-01-01 00:00:00",
            "end": "2024-02-10 00:00:00",
            "time": "12:00:00",
            "time_unit": "day",
            "point": [],
            "zone_type": 1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "终端重复定期任务",
                    "title": "终端重复定期任务",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
            },
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"67890",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

此代码块在浮窗中显示

请求数据说明

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 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 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 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

此代码块在浮窗中显示

返回数据

以下返回数据格式于2024年2月22日上线重复定时任务功能后更新，新增返回MsgIds数据，以替代旧版msgids，请开发者做好兼容。
ts 字段表示定时任务执行成功的时间戳，精确到毫秒。

{ "count": 1, "MsgIds": [ "{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}", "{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Cannot find sending target\"},\"needRetry\":false,\"ts\":1707278411611}" ] }

          {
    "count": 1,
    "MsgIds": [
        "{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}",
        "{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Cannot find sending target\"},\"needRetry\":false,\"ts\":1707278411611}"
    ]
}

此代码块在浮窗中显示

更新定时任务

更新指定 id 的 schedule 任务。

调用地址

PUT 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" 四项中的一项或多项。不支持部分更新。

返回示例

成功返回

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 }, "periodical": { "start": "2024-01-01 00:00:00", "end": "2024-02-10 00:00:00", "time": "12:00:00", "time_unit": "day", "point": [], "zone_type": 1 } }, ## 在实际请求中定时任务（single）与重复定期任务（periodical）不能同时存在 "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "终端重复定期任务", "title": "终端重复定期任务", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

          {
    "name":"定时推送示例",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        },
        "periodical": {
            "start": "2024-01-01 00:00:00",
            "end": "2024-02-10 00:00:00",
            "time": "12:00:00",
            "time_unit": "day",
            "point": [],
            "zone_type": 1
        }
    },
    ## 在实际请求中定时任务（single）与重复定期任务（periodical）不能同时存在
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "终端重复定期任务",
                    "title": "终端重复定期任务",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
    }
    }
}

此代码块在浮窗中显示

失败返回

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 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 通信错误。