定時任務 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 通信錯誤。