定時任務 API v4
最新更新:2022-12-30
定時任務 API v4
概述
API 層面支援定時功能。
這是一個相對獨立的任務執行模塊,維護一個 Schedule 對象。
註: 調 API 創建的定時任務隻能調 API 獲取 / 修改 / 刪除。
調用驗證
詳情參見 REST API 概述的 鑒權方式 說明。
Schedule 參數說明
每一個 schedule 任務,都由 name、enabled、trigger、push 這四個小節組成。
參數 | 類型 | 是否可選 | 含義 |
---|---|---|---|
name | string | 必填 | 表示 schedule 任務的名字,不得超過 255 字節,由漢字、字母、數字、下劃線組成。 |
enabled | bool | 必填 | 表示任務當前狀態,創建任務時必須為 true。 |
trigger | JSOS Object | 必填 | 定時任務觸發時間和觸發條件。當前隻支援定時任務(single),詳情參見 single 說明。 |
push | JSOS Object | 必填 | 推播內容信息,參考 建立推播 API 中各個字段。 |
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 表示按照用戶終端所在的時區推播。 |
創建定時任務
調用地址
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":{
"alert":"api終端定時任務",
"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":{
"alert":"api終端定時任務",
"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"
}
}
此代碼塊在浮窗中顯示
獲取有效的定時任務列表
- 獲取當前有效(未過期)的 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
此代碼塊在浮窗中顯示
返回數據
{
"count": 3,
"msgids": [
"12345567",
"2234567",
"3234567"
]
}
{
"count": 3,
"msgids": [
"12345567",
"2234567",
"3234567"
]
}
此代碼塊在浮窗中顯示
更新定時任務
- 更新指定 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
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web",
"notification":{
"alert":"api 終端定時任務",
"web":{
"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":{
"alert":"api 終端定時任務",
"web":{
"title":"api 終端定時任務",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
此代碼塊在浮窗中顯示
- 則以下為錯誤的更新及與之對應的正確的更新示例:
## WRONG: 更新 push 中的 alert 為 web 終端定時任務:
{
"push": {
"alert": "web 終端定時任務"
}
}
## RIGHT: 更新 push 中的 alert 為 web 終端定時任務:
{
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web",
"notification":{
"alert":"web 終端定時任務",
"web":{
"title":"api 終端定時任務",
"extras":{
"key1":"value1"
}
}
},
"message":{
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":"business info"
}
}
## 此處的 push 更新後必須仍是有效的,否則也會更新失敗。
## WRONG: 更新 push 中的 alert 為 web 終端定時任務:
{
"push": {
"alert": "web 終端定時任務"
}
}
## RIGHT: 更新 push 中的 alert 為 web 終端定時任務:
{
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web",
"notification":{
"alert":"web 終端定時任務",
"web":{
"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
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"web",
"notification":{
"alert":"web 終端定時任務",
"web":{
"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":{
"alert":"web 終端定時任務",
"web":{
"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 通信錯誤。 |