Creates a scheduled task.

Description

  • If a scheduled task fails to execute a scaling rule due to an ongoing scaling activity in a scaling group or because the scaling group is disabled, the scheduled task is automatically retried during the period that is specified by the LaunchExpirationTime parameter. If the scheduled task still fails after the specified period ends, the task is automatically skipped.
  • If multiple tasks are scheduled at similar points in time to execute scaling rules in the same scaling group, the earliest task triggers the first scaling activity. Other tasks execute scaling rules within their launch expiration time. Only one scaling activity can be triggered in a scaling group at a time. If the previous scaling activity is complete and another scheduled task attempts to trigger a scaling activity, Auto Scaling executes the scaling rule that is specified in the scheduled task and then triggers a scaling activity.
  • A scheduled task supports the following scaling methods:
    • If you specify the ScheduledAction parameter, the scaling method of the scheduled task is to specify an existing scaling rule that you want to execute when the scheduled task is triggered.
    • If you specify the ScalingGroupId parameter, the scaling method of the scheduled task is to specify the minimum number, maximum number, or expected number of instances in the scaling group for which you create the scheduled task.
      Note You cannot specify the ScheduledAction and ScalingGroupId parameters at the same time.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateScheduledTask

The operation that you want to perform. Set the value to CreateScheduledTask.

RegionId String Yes cn-qingdao

The region ID of the scheduled task.

ScheduledTaskName String No scheduled****

The name of the scheduled task. The name must be 2 to 64 characters in length and can contain letters, digits, underscores (_), hyphens (-), and periods (.). The name must start with a letter or a digit. The name of the scheduled task must be unique in the region and within the Alibaba Cloud account.

By default, the value of the ScheduledTaskId parameter is used.

Description String No Test scheduled task.

The description of the scheduled task. The description must be 2 to 200 characters in length.

ScheduledAction String No ari:acs:ess:cn-hangzhou:140692647****:scalingrule/asr-bp12tcnol686y1ik****

The scaling rule that you want to execute when the scheduled task is triggered. Specify the unique identifier of the scaling rule. If you specify the ScheduledAction parameter, you must select an existing scaling rule for the scheduled task.

Note You cannot specify the ScheduledAction and ScalingGroupId parameters at the same time.
RecurrenceEndTime String No 2014-08-17T16:55Z

The end time of the scheduled task. Specify the time in the ISO 8601 standard in the YYYY-MM-DDThh:mmZ format.

The time must be in UTC. You cannot enter a point in time that is later than 365 days from the point in time at which the scheduled task is created.

LaunchTime String No 2014-08-17T16:52Z

The point in time at which the scheduled task is triggered. Specify the time in the ISO 8601 standard in the YYYY-MM-DDThh:mmZ format. The time must be in UTC. You cannot enter a point in time that is later than 90 days from the point in time at which the scheduled task is created.

  • If you specify the RecurrenceType parameter, the scheduled task is repeatedly executed at the point in time that is specified by the LaunchTime parameter.
  • If you do not specify the RecurrenceType parameter, the task is executed only once at the point in time that is specified by the LaunchTime parameter.
RecurrenceType String No Daily

The interval at which the scheduled task is repeatedly executed. Valid values:

  • Daily: The scheduled task is executed once every specified number of days.
  • Weekly: The scheduled task is executed on each specified day of a week.
  • Monthly: The scheduled task is executed on each specified day of a month.
  • Cron: The scheduled task is executed based on the specified cron expression.

You must specify the RecurrenceType and RecurrenceValue parameters at the same time.

RecurrenceValue String No 1

The number of recurrences of the scheduled task.

  • If you set the RecurrenceType parameter to Daily, you can specify only one value. Valid values: 1 to 31.
  • If you set the RecurrenceType parameter to Weekly, you can specify multiple values. Separate the values with commas (,). The values that correspond to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday are 0, 1, 2, 3, 4, 5, and 6.
  • If you set the RecurrenceType parameter to Monthly, you can specify two values in the A-B format. Valid values of A and B: 1 to 31. B must be greater than or equal to A.
  • If you set the RecurrenceType parameter to Cron, you can specify a cron expression. A cron expression is written in UTC time and consists of the following fields: minute, hour, day, month, and week. The expression can contain the letters L and W and the following wildcard characters: commas (,), question marks (?), hyphens (-), asterisks (*), number signs (#), and forward slashes (/).

You must specify the RecurrenceType and RecurrenceValue parameters at the same time.

TaskEnabled Boolean No true

Specifies whether to enable the scheduled task.

  • true: enables the scheduled task.
  • false: disables the scheduled task.

Default value: true.

LaunchExpirationTime Integer No 600

The period of time during which a failed scheduled task is retried. Unit: seconds. Valid values: 0 to 21600.

Default value: 600.

MinValue Integer No 0

The minimum number of instances in the scaling group if the scaling method of the scaling group is to specify the number of instances.

MaxValue Integer No 10

The maximum number of instances in the scaling group if the scaling method of the scaling group is to specify the number of instances.

DesiredCapacity Integer No 10

The expected number of instances in the scaling group if the scaling method of the scaling group is to specify the number of instances.

Note You must specify the DesiredCapacity parameter when you create a scaling group.
ScalingGroupId String No asg-bp18p2yfxow2dloq****

The ID of the scaling group whose number of instances is changed when the scheduled task is triggered. If you specify the ScalingGroupId parameter for a scheduled task, the scaling method of the scheduled task is to specify the number of instances in the scaling group. In this case, you must specify at least one of the MinValue, MaxValue, and DesiredCapacity parameters.

Note You cannot specify the ScheduledAction and ScalingGroupId parameters at the same time.

Response parameters

Parameter Type Example Description
ScheduledTaskId String edRtShc57WGXdt8TlPbr****

The globally unique ID of the scheduled task. The globally unique ID is generated by the system.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

The ID of the request.

Examples

Sample requests

http(s)://ess.aliyuncs.com/?Action=CreateScheduledTask
&RegionId=cn-qingdao
&ScheduledTaskName=scheduled****
&Description=Test scheduled task.
&ScheduledAction=ari:acs:ess:cn-hangzhou:140692647****:scalingrule/asr-bp12tcnol686y1ik****
&RecurrenceEndTime=2014-08-17T16:55Z
&LaunchTime=2014-08-17T16:52Z
&RecurrenceType=Daily
&RecurrenceValue=1
&TaskEnabled=true
&LaunchExpirationTime=600
&MinValue=0
&MaxValue=10
&DesiredCapacity=10
&ScalingGroupId=asg-bp18p2yfxow2dloq****
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateScheduledTaskResponse>
    <ScheduledTaskId>edRtShc57WGXdt8TlPbr****</ScheduledTaskId>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
</CreateScheduledTaskResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "ScheduledTaskId" : "edRtShc57WGXdt8TlPbr****",
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}

Error codes

For a list of error codes, visit the API Error Center.

HTTP status code

Error code

Error message

Description

404

InvalidRegionId.NotFound

The specified region does not exist.

The error message returned because the specified region does not exist.

400

InvalidScheduledTaskName.Duplicate

The specified value of parameter ScheduledTaskName is duplicated.

The error message returned because the specified name of the scheduled task already exists.

400

QuotaExceeded.ScheduledTask

Scheduled task quota exceeded.

The error message returned because the maximum number of scheduled tasks that can be created has been reached.

400

ScheduledAction.RegionMismatch

The specified scheduled task and the specified scheduled action are not in the same Region.

The error message returned because the specified scaling rule and the specified scheduled task do not reside in the same region.