how to configure an HTTP job in the console-SchedulerX(SchedulerX)-阿里云帮助中心

Prerequisites

Serverless execution mode: Triggers an HTTP job by using a cloud function or serverless architecture. This mode is suitable for public API calls and lightweight tasks.
Agent execution mode: Executes an HTTP job using a SchedulerX agent installed on the target device. You must first deploy the SchedulerX agent. This mode is suitable for internal service calls and complex processing scenarios.

Note

You can select serverless or agent for the execution mode parameter when you create an HTTP job in the console.

Execution modes

The following table compares SchedulerX HTTP jobs and MSE-XXLJOB HTTP jobs.

	SchedulerX serverless (Deprecated)	SchedulerX agent	MSE-XXL-JOB
Client required	No. Requests are initiated by the server.	Yes. The server sends commands to the client, which then initiates the call.	No. Requests are initiated by the server.
Request method	Currently, only GET and POST are supported. Other methods will be supported based on user demand.
Request definition	Supports only cookie settings and POST parameters.		Supports all HTTP job parameter settings, including Header, Query, and Body.
Response definition	HTTP response code: Determines job success based on the HTTP response code. Response body JSON parsing: The response must be in JSON format. Job success is determined by a specific key-value pair. Response body: The response is a string. Job success is determined by an exact match for a specific string in the body.
Second-level scheduling	No. Only supports minute-level scheduling.	Yes	Yes
Internal URL support	No	Yes
Domain name requirement	No		Yes. Supports Kubernetes Service access without requiring a gateway or domain name.
Broadcast sharding support	No		Yes
Task name parsing	If a task name contains Chinese characters, the backend can decode it using `URLDecode.decode(jobName, "utf-8")`.

Create an HTTP job

You can create an HTTP job using either the GET or POST request method.

Step 1: Basic configuration

GET

Deploy an accessible HTTP service.
- If you already have an accessible HTTP service, proceed to Step 2 to create an HTTP job in the SchedulerX console. Have the target HTTP service's URL, request method (GET or POST), and other relevant configuration information ready.
- If you have not deployed an HTTP service, refer to the following sample Java code for developing an HTTP interface:
```
@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;
}
```
Create an HTTP job in the SchedulerX console.

The following are the relevant configurations for a GET HTTP job. For more information about how to create a scheduled job, see Create a scheduled job. Configure the following parameters: Set Task name to http_get, select Http for Task type, enter the target request address in the Full URL field, select GET for Request method, select Custom JSON for response analysis mode, enter code for Return Check Key, enter 200 for Return Check Value, set Execution Timeout to 10 seconds, and select serverless for execution mode.

POST

Deploy an accessible HTTP service.

If you already have an accessible HTTP service, proceed to Step 2 to create an HTTP job in the SchedulerX console. Have the target HTTP service's URL, request method (GET or POST), and other relevant configuration information ready.

If you have not deployed an HTTP service, refer to the following sample Java code for developing an HTTP interface:

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;
}

Create an HTTP job in the SchedulerX console.

The following are the relevant configurations for a POST HTTP job. For more information about how to create a scheduled job, see Create a scheduled job. Set Task name to http_post, select Http for Task type, enter the target interface address in the Full URL field, select POST for Request method, selectCustom JSON for response analysis mode, enter code for Return Check Key, enter 200 for Return Check Value, set Execution Timeout to 10 seconds, select application/x-www-form-urlencoded for ContentType, enter the POST parameters in the key1=value1&key2=value2 format, and select serverless for execution mode.

Parameters for serverless and agent HTTP jobs:

Note

The configuration parameters for serverless and agent execution modes are the same in the SchedulerX console.

Parameter	Description
Name	The custom name of the job.
Description	A brief description of the job's business purpose to facilitate future searches.
Application ID	The group to which the job belongs. You can select one from the drop-down list.
Job Type	The type of the job. For this scenario, select HTTP.
Full URL	Enter a full URL that starts with `http://` or `https://`.
Request method	Select GET or POST.
Response analysis mode	Select the response analysis mode. The supported modes are as follows: HTTP response code. Job success is determined by a specific HTTP response code that you set. Custom JSON. Set a return check key and a return check value. The server defaults to a JSON format for HTTP request results. It verifies success based on the entered key and value. `{ "code": 200, "data": "true", "message": "", "requestId": "446655068791923614103381232971", "success": true }` In the example above, you can verify success by checking if the key `success` has a value of `true`, or if the key `code` has a value of `200`. Custom string. Determines job success based on an exact match with a custom string in the response.
If you select HTTP Response Code for response analysis mode:
HTTP response code	Set the expected HTTP response code. The default is 200.
If you select Custom JSON for response analysis mode:
Return check key	Only supports JSON return values. The key to check for a successful response.
Return check value	Only supports JSON return values. The value to check for a successful response.
If you select Custom String for response analysis mode:
Custom string	Set the custom string.
Execution timeout	serverless: Up to 30 seconds for the Basic edition and up to 120 seconds for the Professional edition. agent: Unlimited.
Content type	When the Request method is POST, specifies the data format of the request body. Supported formats: `application/x-www-form-urlencoded` `application/json`
POST parameters	When the Request method is POST, specifies the POST form parameters. Examples: When Content type is `application/x-www-form-urlencoded`: `key1=value&key2=value2`. When Content type is `application/json`: `{"key1":"val1","key2":"val2"}`.
Cookie	For example, `key1=val1;key2=val2`. Separate multiple values with a semicolon (;). The maximum length is 300 bytes.
Execution mode	serverless: The server initiates requests, requiring a publicly accessible URL. agent: The client initiates requests, requiring a deployed SchedulerX agent. You can configure an internal URL. This mode is supported only for client versions 1.8.2 and later. To deploy a SchedulerX agent, see Agent Access (for scripts or HTTP jobs).
Advanced configuration
Task Failure Retry Count	The number of times to retry after a job fails. The default is 0.
Retry Interval	The interval between retries after a job fails. The default is 30 seconds.
Task Concurrency	The maximum number of instances of the same job allowed to run concurrently. A value of 1 prevents concurrent execution. If the concurrency limit is exceeded, the current schedule is skipped.
Cleanup Policy	The cleanup policy for job execution history. By default, it keeps the last N records, where N is the Record Count. Keep the last N records. Keep the last N records by status.
Record Count	The number of historical execution records to retain for the job. The default is 300.

Step 2: Timing configuration

On the Schedule Configuration page of the setup wizard, set the timing parameters and advanced configuration parameters, then click Next.

The timing parameters are described below:

Parameter	Description
Time Type	none: Disables automatic scheduling. Jobs are typically triggered by a workflow. cron: Cron expression. api: Triggered via API. fixed_rate: Fixed frequency. second_delay: Fixed delay in seconds. onetime: One-time job.
Cron Expression (only for cron time type)	Enter a cron expression. You can write it directly following Cron syntax or use a tool to generate and validate it.
Fixed frequency (only for fixed_rate time type)	Enter a fixed frequency in seconds. Values must be 60 seconds or longer. For example, 200 means scheduling every 200 seconds.
Fixed delay (only for second_delay time type)	Enter a fixed delay in seconds. The range is from 1 to 60 seconds. For example, 5 means a 5-second delay before triggering the schedule.
Schedule time (only for onetime time type)	Select a date and time. For example, `2025-4-2 12:00:00` schedules the job once.
Advanced configuration
Time offset	The offset of the data time relative to the schedule time. You can get this value from the context during scheduling.
Time Zone	You can select different time zones based on your needs, including common countries or regions, as well as standard GMT formats.
Calendar	Set the effective calendar for the job. Schedule daily. Specify a calendar, such as financial days or workdays.
Effective Time	Set the effective time for the job. Effective immediately. Start time: Requires selecting a start date and time.

Step 3: Notification configuration

HTTP jobs support failure alerts. When issues such as timeouts or unexpected return values occur, you can set up alert rules during job creation to receive corresponding notifications.

On the Notification Configuration page of the setup wizard, set the alert parameters and contacts, then click Complete.

Configurable parameters include: Timeout alert (enabled), Timeout period (in seconds), Terminate on timeout (disabled), Success notification (disabled), Failure alert (enabled), Consecutive failures (set to 1), and No available machine alert (enabled). For Notification channels and contacts, you can select Application group contacts or Custom.
After the job is created successfully, go to the Task management page and click Run Once in the Actions column for the target job.

On the details page of the job instance record, view the execution result and logs.

Get basic job information

The basic information for an HTTP job is in the header. To get this information, you need to add the following dependency to your client's pom.xml file.

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

The following example shows how to get basic job information using the GET method.

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");
    // If the jobName contains Chinese characters, it needs to be URL-decoded.
    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;
}

Job constant definitions

The following table describes the basic information for CommonConstants.

Constant	Key	Description
JOB_ID_HEADER	schedulerx-jobId	Job ID.
JOB_NAME_HEADER	schedulerx-jobName	Job name.
SCHEDULE_TIMESTAMP_HEADER	schedulerx-scheduleTimestamp	The timestamp of the scheduling time.
DATA_TIMESTAMP_HEADER	schedulerx-dataTimestamp	The timestamp of the data time.
GROUP_ID_HEADER	schedulerx-groupId	Application ID.
USER_HEADER	schedulerx-user	Username.
MAX_ATTEMPT_HEADER	schedulerx-maxAttempt	The maximum number of retries for the instance.
ATTEMPT_HEADER	schedulerx-attempt	The current retry count for the instance.
JOB_PARAMETERS_HEADER	schedulerx-jobParameters	Job parameters.
INSTANCE_PARAMETERS_HEADER	schedulerx-instanceParameters	Parameters for a specific job instance, passed when triggering the job via an API.

Verify results

You can check the execution results of an HTTP job on the execution list page. For information on successful results, see GET.

If a job fails, click Details to view the specific reason for the failure, as shown below:

The returned value is different from the expected value. The Result or Error Message field on the instance details page shows the specific cause of the failure. For example, the error message The returned value is different from the expected value indicates that "success":false in the returned JSON does not match the expected value, causing the job to fail.
Execution timeout. When an HTTP job execution times out, the Result or Error Message field on the instance details page shows a java.net.SocketTimeoutException exception, which indicates a socket connection timeout.