Schedule API v3

概述

API 层面支持定时功能。
这是一个相对独立的任务执行模块，维护一个 Schedule 对象。
注：调 API 创建的定时任务只能调 API 获取/修改/删除。

调用地址

https://api.jpush.cn/v3/schedules

调用验证

HTTP Header（头）里加一个字段（Key/Value 对）：
Authorization: Basic base64_auth_string
其中 base64_auth_string 的生成算法为：base64(appKey:masterSecret)
即，对 appKey 加上冒号，加上 masterSecret 拼装起来的字符串，再做 base64 转换。

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
     }
  } 
}
{ 
  "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
  • 参考 push api 中各个字段。
• 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 的乘积共同表示的定期任务的执行周期，如 time_unit 为 day，frequency 为 2，则表示每两天触发一次推送，目前支持的最大值为 100。
        • point 一个列表，此项与 time_unit 相对应：

创建定时任务

POST https://api.jpush.cn/v3/schedules

Example Request

Request Header

POST /v3/schedules
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

Request Data

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

Request Data 说明

• 由于定时任务相对简单，我们例中只对定期任务进行说明
• 以上表示创建一个定期任务，起始生效时间必须 ‘2014-09-17 12:00:00’ 之后第一个 time 时间点，过期时间为 ‘2014-10-18 12:00:00’，在有效期内每两周的周三、周五中午 12 点分别执行一次
• 定期任务首次创建时的触发时间不得晚于其 end 中指定的时间。否则创建失败
• 定期任务（包括定时任务）首次创建时其 enabled 项必须为 true。不能创建 enabled:false 的任务，否则创建失败
• push 必须为有效合法的 push 动作，否则创建失败。

Example Response

Success Response

HTTP/1.1 200 CREATED 
 Content-Type: application/json; charset=utf-8

{
    "schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512",
    "name":"定时推送示例"    //长度最大 255 字节，数字、字母、下划线、汉字。
}

Failed Response

HTTP/1.1 400 BAD REQUEST
 Content-Type: application/json; charset=utf-8

{
  "error":
  {
    "code":8400,
    "message":"error message"
  }
}

获取有效的 Schedule 列表

GET https://api.jpush.cn/v3/schedules?page=

获取当前有效（endtime 未过期）的 schedule 列表

Example Request

Request Header

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。

Example Response

Success Response

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":...},{}, //详细信息列表。
    ]
}

• 以上表示总共 1000 个 schedule-task，总共 5 页，当前为第 4 页，包含 50 个 schedule-task 的信息。
• 返回的 schedules 为 schedule-task 的详细信息列表。

获取指定的定时任务

 GET https://api.jpush.cn/v3/schedules/{schedule_id}

Example Request

Request Header

GET /v3/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

• 获取当前用户的 schedule 任务 id 为 {schedule_id} 的定时任务的详情。

Example Response

Success Reponse

HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8

Response Data

{ 
      "schedule_id":"0eac1b80-c2ac-4b69-948b-c65b34b96512"
      "name": "定时推送示例", 
      "enabled": true, 
      "trigger": {
         ...
       },
      "push": { ... }
}

• 如 schedule_id 不存在，则返回 404，否则返回实际 schedule-task 的详情。

获取定时任务对应的所有 msg_id

 GET https://api.jpush.cn/v3/schedules/{schedule_id}/msg_ids

Example Request

Request Header

GET /v3/schedules/{schedule_id}/msg_ids
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

• 获取当前用户的 schedule 任务 id 为 {schedule_id} 对应的所有消息 id 列表。

Example Response

Success Reponse

HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8

新 Response Data

{
    "count":3,
    "msgids":[
    "{"msg_id":"1076080897","error":{"code":0,"message":""},"needRetry":false}",
    "{"msg_id":"1076080898","error":{"code":0,"message":""},"needRetry":false}",
    "{"msg_id":"1076080899","error":{"code":0,"message":""},"needRetry":false}",
    ]
}

旧 Response Data

{
    "count":3,
    "msgids":["12345567","2234567","3234567"]
}

• 新 Response Data 格式在 2018-09-12 至 2018-09-13 号上线，若 schedule_id 是 12 日前，则返回旧 Response Data 格式；若 schedule_id 是 13 日后，则返回新 Response Data 格式；需要开发者做好兼容。

修改指定的 Schedule

PUT https://api.jpush.cn/v3/schedules/{schedule_id}

Example Request

PUT /v3/schedules/{schedule_id}
 Authorization: Basic (base64 auth string) 
 Content-Type: application/x-www-form-urlencoded
 Accept: application/json

• 更新指定 id 的 schedule 任务。

{
   "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":"定时任务更新"}
   }
}

• 则以下为错误的更新及与之对应的正确的更新示例：

## 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 任务

Example Response

Success Response

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":"andiro", 
   "options":{"apns_production":"false"}, 
   "audience":"all", 
   "notification" : {"alert":"定时任务更新"}
   }
}

Fail Response

• schedule_id 无效，不是有效的 uuid。

HTTP/1.0 404 Not Found
 Content-Type: application/json

• 更新操作不合法

HTTP/1.0 400 BAD REQUEST
 Content-Type: application/json

删除指定的 Schedule 任务

DELETE https://api.jpush.cn/v3/schedules/{schedule_id}

schedule_id 为已创建的 schedule 任务的 id，如果 schedule_id 不合法即不是有效的 uuid，则 404。

Example Request

DELETE /v3/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

Example Response

Success Response

HTTP/1.0 200 
  Content-Type: application/json
  Content-Length: 0

Failed Response

HTTP/1.0 404 Not Found 
  Content-Type: application/json
  Content-Length: 0

{
  "error":{
    "code":8404,
    "message":"..."
  }
}

错误码描述

错误返回格式

{"error":{"code":errcode, "message":"error message"}}

调用限制

• 定时最多有效数（当前未过期数）与周期最多有效数（当前未过期数）总数 100 个。超过后失败。
• VIP 客户可申请提高总数上限，最高可达 2000 个，联系商务开通。
• 最大频率当前为 100/分。
• 定时任务（single）的最晚时间与定期任务（periodical）的最大跨度均不能超过 1 年。