如何在控制台配置HTTP任務 - SchedulerX

SchedulerX 2.0支援調度HTTP任務，包含Serverless、Agent兩種執行方式，通過控制台配置後即可使用。本文介紹如何在控制台配置HTTP任務。

前提條件

Serverless執行方式：通過雲函數或無伺服器架構觸發HTTP任務。適用於公網API調用和輕量型工作。
Agent執行方式：通過在目標裝置上安裝SchedulerX Agent執行HTTP任務，需要提前部署schedulerxAgent。適用於內網服務調用和需要複雜處理的情境。

說明

Serverless和Agent模式選擇，您可以在控制台建立HTTP任務時，選擇執行方式配置項為Serverless或者Agent。

執行方式

Serverless、Agent兩種執行方式的區別與使用限制如下所示：

執行模式	Serverless	Agent
是否需要接入用戶端	否，請求由SchedulerX發起調用。	是，請求由接入的使用者端發起調用。
請求方式	目前支援GET、POST。
結果解析	HTTP請求返回結果需為JSON格式，服務端通過解析指定Key的值與設定值是否一致判斷本次請求是否成功。
是否支援秒級任務	否，僅支援到分鐘層級。	是。
是否支援內部URL	否，Serverless執行方式下，請求URL需要有公網許可權，如果HTTP介面地址的格式為ip:port，需要機器開通公網許可權。	是。
任務名解析	如果任務名是中文，後端可通過`URLDecode.decode(jobName, "utf-8")`解碼。

如何建立HTTP任務

您可以通過GET和POST兩種請求方式，建立HTTP任務。

步驟一：基本配置

GET

部署可訪問的HTTP服務。
- 如果已具備可訪問的HTTP服務，繼續步驟 2中在任務調度控制台建立HTTP任務。確保已經準備好目標HTTP服務的URL、要求方法（如 GET 或 POST）以及其他相關配置資訊。
- 尚未部署HTTP服務。請參考以下使用Java語言開發HTTP介面的範例程式碼：
```
@GET
@Path("hi")
@Produces(MediaType.APPLICATION_JSON)
public RestResult hi(@QueryParam("user") String user) {
    TestVo vo = new TestVo();
    vo.setName(user);
    RestResult result = new RestResult();
    result.setCode(200);
    result.setData(vo);
    return result;
}
```
在分布式任務調度平台中建立HTTP任務。
HTTP任務GET方法的相關配置如下所示。關於建立調度任務，請參見建立調度任務。

POST

部署可訪問的HTTP服務。

如果已具備可訪問的HTTP服務，繼續步驟 2中在任務調度控制台建立HTTP任務。確保已經準備好目標HTTP服務的URL、要求方法（如 GET 或 POST）以及其他相關配置資訊。

尚未部署HTTP服務。請參考以下使用Java語言開發HTTP介面的範例程式碼：

import com.alibaba.schedulerx.common.constants.CommonConstants;

@POST
@Path("createUser")
@Produces(MediaType.APPLICATION_JSON)
public RestResult createUser(@FormParam("userId") String userId, 
        @FormParam("userName") String userName) {
    TestVo vo = new TestVo();
    System.out.println("userId=" + userId + ", userName=" + userName);
    vo.setName(userName);
    RestResult result = new RestResult();
    result.setCode(200);
    result.setData(vo);
    return result;
}

在分布式任務調度平台中建立HTTP任務。
HTTP任務POST方法相關配置資訊如下所示。關於建立調度任務，請參見建立調度任務。

Serverless HTTP和Agent HTTP任務參數說明：

說明

Serverless HTTP與Agent HTTP執行方式在任務調度控制台配置項相同。

配置項	描述
任務名	自訂任務名稱。
描述	任務描述，盡量簡潔地描述業務，便於後續搜尋。
應用ID	任務所屬分組。可以在下拉式清單中選擇。
任務類型	指任務所實現的語言，當前選擇HTTP類型。
完整的url	需要填寫完整的URL，以HTTP或者HTTPS開頭。
請求方式	選擇GET/POST請求方式。
應答解析模式	選擇應答解析模式。支援的模式如下： HTTP響應碼。通過HTTP響應碼應答，您需要設定標準的HTTP請求響應返回Code值。自訂JSON。返回校正Key和返回校正Value。服務端預設HTTP請求結果為JSON格式，根據填寫的Key和Value校正結果是否成功。 `{ "code": 200, "data": "true", "message": "", "requestId": "446655068791923614103381232971", "success": true }` 上面的範例程式碼可以校正Key為Success，校正value:true或者校正Code是否為200。自訂字串。按您自訂的返回字串內容完全符合判斷任務是否執行成功。
選擇應答解析模式為http響應碼時：
http響應碼	設定HTTP響應碼Code，預設為200。
選擇應答解析模式為自訂JSON時：
返回校正key	僅支援傳回值JSON格式，成功返回校正Key。
返回校正value	僅支援傳回值JSON格式，成功返回校正Value。
選擇應答解析模式為自訂字串時：
自訂字串	設定自訂字串。
執行逾時時間	serverless：基礎版最大30秒，專業版最大120秒。 agent：無限制。
ContentType	當請求方式為POST時，指定請求體的資料格式，支援的資料格式如下： `application/x-www-form-urlencoded`。 `application/json`。
post參數	當請求方式為POST時，指定POST表單參數，樣本如下： ContentType為`application/x-www-form-urlencoded`時：`key1=value&key2=value2`。 ContentType為`application/json`時：`{"key1":"val1","key2":"val2"}`。
cookie	例如`key1=val1;key2=val2`。多個值用半形分號（;）隔開，最大長度為300位元組。
執行方式	serverless：由服務端發起請求，需要公網可訪問的URL。 agent：需要提前部署schedulerxAgent，由用戶端發起請求，可以配置內部URL。（僅支援1.8.2以上的用戶端版本）。部署schedulerxAgent，請參見Agent接入（指令碼或HTTP任務）。
進階配置
任務失敗重試次數	任務執行失敗後重試次數，預設為0次。
任務失敗稍候再試	任務執行失敗後稍候再試，預設為30，單位秒。
任務並發數	同一個任務同一時間允許啟動並執行最大執行個體個數，1表示不允許重複執行。如果超過並發數，會跳過當前調度。
清理策略	任務執行記錄的清理策略，預設為保留最近N條，N為保留記錄數。保留最近N條。按狀態保留最近N條。
保留記錄數	任務歷史執行記錄的保留記錄數，預設300條。

步驟二：定時配置

在定時配置設定精靈頁，設定定時參數和進階配置參數，然後單擊下一步。

建立任務-定時配置

定時參數說明如下：

配置名稱	意義
時間類型	none：無調度方式，一般通過工作流程觸發。 cron：Cron運算式。 api：通過API觸發。 fixed_rate：固定頻率。 second_delay：秒級固定延遲。 onetime：一次性任務。
cron運算式（僅適用於cron時間類型）	填寫Cron運算式。可以直接按照Cron文法填寫，也可以使用工具產生並驗證。
固定頻率（僅適用於fixed_rate時間類型）	填寫固定頻率，單位為秒，只支援60秒以上。例如，200表示每200s調度一次。
固定延遲（僅適用於second_delay時間類型）	填寫固定延遲，單位為秒。範圍為1秒~60秒。例如，5表示延遲5秒觸發調度。
調度時間（僅適用於one_time時間類型）	選擇日期和時間。例如，`2025-4-2 12:00:00`調度一次。
進階配置
時間位移	資料時間相對於調度時間的位移，可以在調度時從上下文擷取該值。
時區	可以根據實際情況選擇不同時區，包括一些常用國家或地區，也包括標準的GMT表達方式。
日曆	設定任務生效日曆。每天調度。指定日曆，需要指定金融日或者工作日。
生效時間	設定任務生效時間。立即生效。開始時間，需要選擇開始的日期和時間。

步驟三：通知配置

HTTP任務支援錯誤判警，當出現上述逾時以及傳回值不符合預期的問題時，您可以在建立任務時設定警示條件，接收相應的警示資訊。

在通知配置設定精靈頁，設定警示參數及連絡人，然後單擊完成。
任務建立成功後，在任務管理頁面，單擊目標任務操作列的運行一次。

如何擷取任務基本資料

HTTP任務的基本資料在Header中，如需擷取任務的基本資料，需要在用戶端的pom.xml中增加以下依賴。

<dependency>
    <groupId>com.aliyun.schedulerx</groupId>
    <artifactId>schedulerx2-common</artifactId>
    <version>1.6.0</version>
</dependency>

以GET方法為例，通過以下方式擷取任務基本資料。

import com.alibaba.schedulerx.common.constants.CommonConstants;

@GET
@Path("hi")
@Produces(MediaType.APPLICATION_JSON)
public RestResult hi(@QueryParam("user") String user,
        @HeaderParam(CommonConstants.JOB_ID_HEADER) String jobId,
        @HeaderParam(CommonConstants.JOB_NAME_HEADER) String jobName) {
    TestVo vo = new TestVo();
    vo.setName("armon");
    //若JobName是中文，需要進行URLDecode解碼。
    String decodedJobName = URLDecoder.decode(jobName, "utf-8");
    System.out.println("user=" + user + ", jobId=" + jobId + ", jobName=" + decodedJobName);
    RestResult result = new RestResult();
    result.setCode(200);
    result.setData(vo);
    return result;
}

任務常量定義與說明

任務CommonConstants常量基本資料如下所示：

CommonConstants常量	key	value描述
JOB_ID_HEADER	schedulerx-jobId	任務ID。
JOB_NAME_HEADER	schedulerx-jobName	任務名。僅支援英文命名。
SCHEDULE_TIMESTAMP_HEADER	schedulerx-scheduleTimestamp	調度時間的時間戳記。
DATA_TIMESTAMP_HEADER	schedulerx-dataTimestamp	資料時間的時間戳記。
GROUP_ID_HEADER	schedulerx-groupId	應用ID。
USER_HEADER	schedulerx-user	使用者名稱。
MAX_ATTEMPT_HEADER	schedulerx-maxAttempt	執行個體最大重試次數。
ATTEMPT_HEADER	schedulerx-attempt	執行個體當前重試次數。
JOB_PARAMETERS_HEADER	schedulerx-jobParameters	任務參數。
INSTANCE_PARAMETERS_HEADER	schedulerx-instanceParameters	任務執行個體參數，需要API觸發。

結果驗證

HTTP任務執行結果在執行列表頁可以進行查詢，關於成功結果，請參見GET。

任務執行失敗時，單擊詳情可查看具體失敗原因，如下所示：

傳回值和期望不相同。
執行逾時。