定时任务 API v4

最新更新:2024-02-22

概述

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 日是不会进行触发的

创建定时任务

调用地址

POST https://webpush.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":"web", "notification":{ "web":{ "alert":"api终端定时任务", "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":"web",
            "notification":{
                "web":{
                    "alert":"api终端定时任务",
                    "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"
    }
}

        
此代码块在浮窗中显示

重复定时任务请求示例

{ "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":"android", "notification":{ "alert":"api终端重复定期任务", "android":{ "title":"api终端重复定期任务", "extras":{ "key1":"value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"67890", "custom_args":"business info" } }
          {
    "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":"android",
            "notification":{
                "alert":"api终端重复定期任务",
                "android":{
                    "title":"api终端重复定期任务",
                    "extras":{
                        "key1":"value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"67890",
        "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://webpush.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://webpush.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://webpush.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

        
此代码块在浮窗中显示

返回数据

  • 以下返回数据格式于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 https://webpush.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 }, "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":"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
        },
        "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":"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 }, "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":"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
        },
        "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":"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://webpush.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 通信错误。
    在文档中心打开