定時任務 API
最新更新: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 | 必填 | 推播內容信息,參考 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 表示按照用戶終端所在的時區推播。 |
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 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":{
"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":"android",
"notification":{
"alert":"api終端定時任務",
"android":{
"title":"api終端定時任務",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"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":"android",
"notification":{
"alert":"api終端重複定期任務",
"android":{
"title":"api終端重複定期任務",
"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":"android",
"notification":{
"alert":"api終端重複定期任務",
"android":{
"title":"api終端重複定期任務",
"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":true
},
{}, // 詳細信息列表。]
}
{
"total_count": 1000, // 表示總數
"total_pages": 5, // 總頁數。
"page": 4, // 當前為第四頁。
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled":true
},
{}, // 詳細信息列表。]
}
此代碼塊在浮窗中顯示
- 以上表示總共 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 任務。
- 按下終端時區推播的定時任務與按主站時區推播的定時任務之間不能進行相互更新,反之亦然。
- 更新後的 trigger 必須仍是有效合法的,否則即使 trigger 整體更新也會失敗。
- 不支援部分更新,例如更新之前的任務為:
{
"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": "12345",
"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": "android",
"notification": {
"alert": "api 終端定時任務",
"android": {
"title": "api 終端定時任務",
"extras": {
"key1": "value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
此代碼塊在浮窗中顯示
錯誤的更新操作範例
// WRONG:更新push中的平台為iOS:
{
"push": {
"body": {
"platform": "ios"
}
}
}
// WRONG:更新 periodical 中的過期時間延遲一個月:
{
"trigger": {
"periodical": {
"end": "2024-03-10 00:00:00"
}
}
}
// WRONG:更新push中的平台為iOS:
{
"push": {
"body": {
"platform": "ios"
}
}
}
// WRONG:更新 periodical 中的過期時間延遲一個月:
{
"trigger": {
"periodical": {
"end": "2024-03-10 00:00:00"
}
}
}
此代碼塊在浮窗中顯示
正確的更新操作範例
在更新操作中,您需要包含 push
欄位下的所有相關子字段,以確保更新操作符合完整更新的要求。這裡提供了更新後的完整 push
設定:
// RIGHT:更新push中的平台为iOS:
{
"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":"ios",
"notification":{
"alert":"api 終端定時任務",
"ios":{
"title":"api 終端定時任務",
"extras":{
"key1":"value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
// RIGHT:更新 periodical 中的過期時間延遲一個月:
{
"name": "定時推播範例",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00", // 保持原始開始時間
"end": "2024-03-10 00:00:00", // 延後一個月至3月10日
"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": "12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
// RIGHT:更新push中的平台为iOS:
{
"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":"ios",
"notification":{
"alert":"api 終端定時任務",
"ios":{
"title":"api 終端定時任務",
"extras":{
"key1":"value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
// RIGHT:更新 periodical 中的過期時間延遲一個月:
{
"name": "定時推播範例",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00", // 保持原始開始時間
"end": "2024-03-10 00:00:00", // 延後一個月至3月10日
"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": "12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
此代碼塊在浮窗中顯示
此處的 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":{
"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":"ios",
"notification":{
"alert":"api 終端定時任務",
"ios":{
"title":"api 終端定時任務",
"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 通信錯誤。 |