定時任務 API v4

概述

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 日是不會進行觸發的

注：透過 API 創建的定時任務只能透過 API 獲取 / 修改 / 刪除。

創建定時任務

調用地址

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":"web", "notification":{ "web": { "alert": "终端重复定期任务", "title": "终端重复定期任务", "url": "https://www.engagelab.com/", "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":"web",
            "notification":{
                "web": {
                    "alert": "终端重复定期任务",
                    "title": "终端重复定期任务",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "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"
    }
}

此代碼塊在浮窗中顯示

重複定時任務請求示例

{ "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":"web", "notification":{ "web": { "alert": "终端重复定期任务", "title": "终端重复定期任务", "url": "https://www.engagelab.com/", "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":"web",
            "notification":{
                "web": {
                    "alert": "终端重复定期任务",
                    "title": "终端重复定期任务",
                    "url": "https://www.engagelab.com/",
                    "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":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 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 任務。
按終端時區推播的定時任務與按主站時區推播的定時任務之間不能進行相互更新，反之亦然。
更新操作可為 "name"，"enabled"、"trigger" 或 "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":"api終端定時任務", "web":{ "alert":"api終端定時任務", "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":"web",
            "notification":{
                "alert":"api終端定時任務",
                "web":{
                    "alert":"api終端定時任務",
                    "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 通信錯誤。