定时推送任务 API
最近更新:2022-07-224
展开全部
定时推送任务 API
概述
API 层面支持定时功能。
这是一个相对独立的任务执行模块,维护一个 Schedule 对象。
注:调 API 创建的定时任务只能调 API 获取/修改/删除。
调用地址
https://api.jpush.cn/v3/schedules
调用验证
详情参见 REST API 概述的 鉴权方式 说明。
Schedule 对象定义
定时任务:
{
"cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
"name": "Schedule_Name",
"enabled": true,
"trigger": {
"single":{
"time": "2014-09-17 12:00:00" //yyyy-MM-dd HH:mm:ss
}
},
"push": {
"platform": "all",
"audience": "all",
"notification": {
"alert" : "Hello, JPush!"
},
"message": {
"msg_content":"Message!"
},
"options": {
"time_to_live":60
}
}
}
{
"cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
"name": "Schedule_Name",
"enabled": true,
"trigger": {
"single":{
"time": "2014-09-17 12:00:00" //yyyy-MM-dd HH:mm:ss
}
},
"push": {
"platform": "all",
"audience": "all",
"notification": {
"alert" : "Hello, JPush!"
},
"message": {
"msg_content":"Message!"
},
"options": {
"time_to_live":60
}
}
}
此代码块在浮窗中显示
定期任务:
{ "cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
"name": "Schedule_Name",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-09-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK", //month, week, day, 大小写不敏感
"frequency": 1,
"point": ["WED","FRI"] //time_unit为 day 的时候,point 不能存在。WED,FRI 大小写不敏感。month:"01","02"
}
},
"push": {
"platform": "all",
"audience": "all",
"notification": {"alert" : "Hello, JPush!" },
"message": {"msg_content":"Message!" },
"options": {"time_to_live":60}
}
}
{ "cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
"name": "Schedule_Name",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-09-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK", //month, week, day, 大小写不敏感
"frequency": 1,
"point": ["WED","FRI"] //time_unit为 day 的时候,point 不能存在。WED,FRI 大小写不敏感。month:"01","02"
}
},
"push": {
"platform": "all",
"audience": "all",
"notification": {"alert" : "Hello, JPush!" },
"message": {"msg_content":"Message!" },
"options": {"time_to_live":60}
}
}
此代码块在浮窗中显示
字段说明
每一个 schedule 任务,都由 name、enabled、trigger、push 这四个小节组成。
cid
- 和 push api 中 cid 用法一致,详见 cid 说明 。注:schedule api payload 中的 push 字段中含有 cid 字段将会被忽略。
push
name
- 表示 schedule 任务的名字,由 schedule-api 在用户成功创建 schedule 任务后返回,不得超过 255 字节,由汉字、字母、数字、下划线组成。
enabled
- 表示任务当前状态,布尔值,必须为 true 或 false,创建任务时必须为 true。
trigger
- 表示 schedule 任务的触发条件,当前只支持定时任务(single)与定期任务(periodical)。
- single
- 表示定时任务
- time 为必选项且格式为 "yyyy-MM-dd HH:mm:ss",如 "2014-02-15 13:16:59",不能为 "2014-2-15 13:16:59" 或 "2014-12-15 13:16",即日期时间格式必须完整。定时任务的最晚时间不能超过一年。
- 表示定时任务
- periodical
- 表示定期任务
- start 表示定期任务有效起始时间,格式与必须严格为: "yyyy-MM-dd HH:mm:ss",且时间必须为 24 小时制。
- end 表示定期任务的过期时间,格式同上。定期任务最大跨度不能超过一年。
- time 表示触发定期任务的定期执行时间,格式严格为: "HH:mm:ss",且为 24 小时制。
- time_unit 表示定期任务的执行的最小时间单位有:"day"、"week" 及 "month" 三种。大小写不敏感,如 "day", "Day", "DAy" 均为合法的 time_unit。
- frequency 此项与 time_unit 的乘积共同表示的定期任务的执行周期,frequency 目前支持的最大值为 100 。如 time_unit 为 day,frequency 为 2,则表示每两天触发一次推送,首次执行是间隔起始日期 1 天后的第一个执行时间点。如 time_unit 为 week,frequency 为 2,则表示每两周触发一次推送,首次执行是间隔起始日期 7 天后的第一个执行时间点。
- point 一个列表,此项与 time_unit 相对应:
- 表示定期任务
- single
- 表示 schedule 任务的触发条件,当前只支持定时任务(single)与定期任务(periodical)。
time_unit | point | 描述 |
---|---|---|
day | NIL | 当 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://api.jpush.cn/v3/schedules
POST https://api.jpush.cn/v3/schedules
此代码块在浮窗中显示
请求示例
请求报头
POST /v3/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
POST /v3/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
此代码块在浮窗中显示
请求数据
{
"name": "定时普通推送示例",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-10-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK", //month, week, day;大小写不敏感
"frequency": 2,
"point": ["WED","FRI"] //time_unit 为 day 的时候,point 不能存在。WED,FRI 大小写不敏感。month:"01","02"
}
},
"push": {
"platform": "all",
"audience": "all",
"notification": {
"ios": {
"alert":"this a test",
"sound":"default",
"badge":"+1"
}
},
"message": {},
"options": {"apns_production":false}
}
}
{
"name": "定时普通推送示例",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-10-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK", //month, week, day;大小写不敏感
"frequency": 2,
"point": ["WED","FRI"] //time_unit 为 day 的时候,point 不能存在。WED,FRI 大小写不敏感。month:"01","02"
}
},
"push": {
"platform": "all",
"audience": "all",
"notification": {
"ios": {
"alert":"this a test",
"sound":"default",
"badge":"+1"
}
},
"message": {},
"options": {"apns_production":false}
}
}
此代码块在浮窗中显示
{
"name":"定时文件推送示例",
"enabled":true,
"trigger":{
"periodical":{
"start":"2021-02-19 12:00:00",
"end":"2021-03-19 18:30:00",
"time":"18:05:00",
"time_unit":"day",
"frequency":1
}
},
"push":{
"platform":"all",
"audience":{
"file":{
"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"
}
},
"notification":{
"alert":"Hello, JPush!"
},
"message":{
"msg_content":"Hello, JPush!"
},
"options":{
"time_to_live":600,
"apns_production":false
}
}
}
{
"name":"定时文件推送示例",
"enabled":true,
"trigger":{
"periodical":{
"start":"2021-02-19 12:00:00",
"end":"2021-03-19 18:30:00",
"time":"18:05:00",
"time_unit":"day",
"frequency":1
}
},
"push":{
"platform":"all",
"audience":{
"file":{
"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"
}
},
"notification":{
"alert":"Hello, JPush!"
},
"message":{
"msg_content":"Hello, JPush!"
},
"options":{
"time_to_live":600,
"apns_production":false
}
}
}
此代码块在浮窗中显示
请求参数说明
- 由于定时任务相对简单,我们例中只对定期任务进行说明
- 以上定时普通推送示例表示创建一个定期任务,起始时间为 '2014-09-17 12:00:00' ,过期时间为 '2014-10-18 12:00:00',执行时间点 time 为 "12:00:00",time_unit 为 week,frequency 为 2,point 为["WED","FRI"],则表示在有效期内每两周的周三、周五中午 12 点分别执行一次推送。
- 首次执行是起始日期 7 天后的第一个执行时间点,起始日期'2014-09-17'当天是周三,则第一个执行时间点为'2014-09-24 12:00:00'(周三中午12点)。
- 定期任务首次创建时的触发时间不得晚于其 end 中指定的时间。否则创建失败
- 定期任务(包括定时任务)首次创建时其 enabled 项必须为 true。不能创建 enabled:false 的任务,否则创建失败
- push 必须为有效合法的 push 动作,否则创建失败。
返回示例
成功返回
HTTP/1.1 200 CREATED
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 CREATED
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
{
"schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name":"定时推送示例" //长度最大 255 字节,数字、字母、下划线、汉字。
}
{
"schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name":"定时推送示例" //长度最大 255 字节,数字、字母、下划线、汉字。
}
此代码块在浮窗中显示
失败返回
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":8400,
"message":"error message"
}
}
{
"error":
{
"code":8400,
"message":"error message"
}
}
此代码块在浮窗中显示
获取有效的定时任务列表
- 获取当前有效(endtime 未过期)的 schedule 列表。
调用地址
GET https://api.jpush.cn/v3/schedules?page=
GET https://api.jpush.cn/v3/schedules?page=
此代码块在浮窗中显示
请求示例
请求报头
GET /v3/schedules?page=
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
GET /v3/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":...},{}, //详细信息列表。
]
}
{
"total_count":1000, //表示总数
"total_pages":5, //总页数。
"page":4, //当前为第四页。
"schedules":[
{"schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512","name":"","enabled":...},{}, //详细信息列表。
]
}
此代码块在浮窗中显示
- 以上表示总共 1000 个 schedule-task,总共 5 页,当前为第 4 页,包含 50 个 schedule-task 的信息。
- 返回的 schedules 为 schedule-task 的详细信息列表。
获取定时任务详情
- 获取当前用户的 schedule 任务 id 为 {schedule_id} 的定时任务的详情。
调用地址
GET https://api.jpush.cn/v3/schedules/{schedule_id}
GET https://api.jpush.cn/v3/schedules/{schedule_id}
此代码块在浮窗中显示
请求示例
请求报头
GET /v3/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
GET /v3/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://api.jpush.cn/v3/schedules/{schedule_id}/msg_ids
GET https://api.jpush.cn/v3/schedules/{schedule_id}/msg_ids
此代码块在浮窗中显示
请求示例
请求报头
GET /v3/schedules/{schedule_id}/msg_ids
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
GET /v3/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":[
"{"msg_id":"1076080897","error":{"code":0,"message":""},"needRetry":false,"ts":1647331621836}",
"{"msg_id":"1076080898","error":{"code":0,"message":""},"needRetry":false,"ts":1647331641022}",
"{"msg_id":"1076080899","error":{"code":0,"message":""},"needRetry":false,"ts":1647331669510}",
]
}
{
"count":3,
"msgids":[
"{"msg_id":"1076080897","error":{"code":0,"message":""},"needRetry":false,"ts":1647331621836}",
"{"msg_id":"1076080898","error":{"code":0,"message":""},"needRetry":false,"ts":1647331641022}",
"{"msg_id":"1076080899","error":{"code":0,"message":""},"needRetry":false,"ts":1647331669510}",
]
}
此代码块在浮窗中显示
旧返回数据
{
"count":3,
"msgids":["12345567","2234567","3234567"]
}
{
"count":3,
"msgids":["12345567","2234567","3234567"]
}
此代码块在浮窗中显示
- 新返回数据格式在 2018-09-12 至 2018-09-13 号上线,若 schedule_id 是 12 日前,则返回旧返回数据格式;若 schedule_id 是 13 日后,则返回新返回数据格式;需要开发者做好兼容。
- 新返回数据格式中的 ts 字段表示定时任务执行成功的时间戳,精确到毫秒,对于 2022-03-17 后创建的定时任务,返回的内容中将增加该字段。
更新定时任务
- 更新指定 id 的 schedule 任务。
调用地址
PUT https://api.jpush.cn/v3/schedules/{schedule_id}
PUT https://api.jpush.cn/v3/schedules/{schedule_id}
此代码块在浮窗中显示
请求示例
PUT /v3/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/x-www-form-urlencoded
Accept: application/json
PUT /v3/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": { ... }
}
此代码块在浮窗中显示
- 更新操作可为 "name","enabled"、"trigger" 或 "push" 四项中的一项或多项。
- 不支持部分更新,如更新之前的任务为:
{
"name": "定时推送示例",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-10-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK",
"frequency": 2,
"point": ["WED","FRI"]
}
},
"push": {
"platform":"ios",
"options":{"apns_production":false},
"audience":"all",
"notification" : {"alert":"定时任务更新"}
}
}
{
"name": "定时推送示例",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-10-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK",
"frequency": 2,
"point": ["WED","FRI"]
}
},
"push": {
"platform":"ios",
"options":{"apns_production":false},
"audience":"all",
"notification" : {"alert":"定时任务更新"}
}
}
此代码块在浮窗中显示
- 则以下为错误的更新及与之对应的正确的更新示例:
## WRONG: 更新 push 中的平台为安卓:
{
"push":{"platform":"android"}
}
## RIGHT: 更新 push 中的平台为安卓:
{
"push":{
"platform":"android",
"options":{"apns_production":false},
"audience":"all",
"notification" : {"alert":"定时任务更新"}
}
}
## 此处的 push 更新后必须仍是有效的,否则也会更新失败。
## WRONG: 更新 periodical 中的过期时间延后一个月:
{
"trigger":{
"end":"2014-11-18 12:00:00"
}
## RIGHT: 更新 periodical 中的过期时间延后一个月:
{
"trigger":{
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-11-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK",
"frequency": 2,
"point": ["WED","FRI"]
}
}
}
## time、time_unit、frequency、point 的更新同上。
## 更新后的 trigger 必须仍是有效合法的,否则即使 trigger 整体更新也会失败。可以更新 enable:false 的任务。
## 定时任务(single)与定期任务(periodical)之间不能进行相互更新,即,原先为 single 类任务,则不能更新为 periodical 任务,反之亦然。
## 不能更新已过期的 schedule 任务
## WRONG: 更新 push 中的平台为安卓:
{
"push":{"platform":"android"}
}
## RIGHT: 更新 push 中的平台为安卓:
{
"push":{
"platform":"android",
"options":{"apns_production":false},
"audience":"all",
"notification" : {"alert":"定时任务更新"}
}
}
## 此处的 push 更新后必须仍是有效的,否则也会更新失败。
## WRONG: 更新 periodical 中的过期时间延后一个月:
{
"trigger":{
"end":"2014-11-18 12:00:00"
}
## RIGHT: 更新 periodical 中的过期时间延后一个月:
{
"trigger":{
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-11-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK",
"frequency": 2,
"point": ["WED","FRI"]
}
}
}
## time、time_unit、frequency、point 的更新同上。
## 更新后的 trigger 必须仍是有效合法的,否则即使 trigger 整体更新也会失败。可以更新 enable:false 的任务。
## 定时任务(single)与定期任务(periodical)之间不能进行相互更新,即,原先为 single 类任务,则不能更新为 periodical 任务,反之亦然。
## 不能更新已过期的 schedule 任务
此代码块在浮窗中显示
返回示例
成功返回
HTTP/1.0 200 CREATED
Content-Type: application/json
HTTP/1.0 200 CREATED
Content-Type: application/json
此代码块在浮窗中显示
{
"name": "定时推送示例",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-11-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK",
"frequency": 2,
"point": ["WED","FRI"] }
},
"push": {
"platform":"android",
"options":{"apns_production":false},
"audience":"all",
"notification" : {"alert":"定时任务更新"}
}
}
{
"name": "定时推送示例",
"enabled": true,
"trigger": {
"periodical": {
"start":"2014-09-17 12:00:00",
"end": "2014-11-18 12:00:00",
"time": "12:00:00",
"time_unit": "WEEK",
"frequency": 2,
"point": ["WED","FRI"] }
},
"push": {
"platform":"android",
"options":{"apns_production":false},
"audience":"all",
"notification" : {"alert":"定时任务更新"}
}
}
此代码块在浮窗中显示
失败返回
- schedule_id 无效,不是有效的 uuid。
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
此代码块在浮窗中显示
删除定时任务
- 删除指定 schedule_id 的任务,schedule_id 为已创建的 schedule 任务的 id,如果 schedule_id 不合法即不是有效的 uuid,则 404。
调用地址
DELETE https://api.jpush.cn/v3/schedules/{schedule_id}
DELETE https://api.jpush.cn/v3/schedules/{schedule_id}
此代码块在浮窗中显示
请求示例
DELETE /v3/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
DELETE /v3/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":8404,
"message":"..."
}
}
{
"error":{
"code":8404,
"message":"..."
}
}
此代码块在浮窗中显示
错误码描述
Code | HTTP | 描述 | Error Message | 详细解释 |
---|---|---|---|---|
8000 | 200 | 正确返回 | nil | 成功状态码 |
8104 | 404 | 请求的 schedule 任务不存在 | Request schedule operation doesn't exist | 对应的任务已发送,或 schedule id 错误 |
8101 | 401 | 鉴权失败 | Basic authentication failed. | appkey masterscrect 不匹配 |
8100 | 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 | 参数不合法或者无效,或 推送超过限制(比如推送广播超限制、定时任务数超限制、定速任务超限制),或 参数体超长 |
8203 | 503 | 系统内部错误,建议稍后重试 | Execute action timeout, please try later again | 与 schedule-server 通信错误 |
8200 | 500 | 系统内部错误 | Server internal error. | 发生未预料错误。 |
错误返回格式
{"error":{"code":errcode, "message":"error message"}}
{"error":{"code":errcode, "message":"error message"}}
此代码块在浮窗中显示
调用限制
- 定时最多有效数(当前未过期数)与周期最多有效数(当前未过期数)总数 100 个。超过后失败。
- VIP 客户可申请提高总数上限,最高可达 2000 个,联系商务开通。
- 定时任务(single)的最晚时间与定期任务(periodical)的最大跨度均不能超过 1 年。
文档内容是否对您有帮助?