Creating a Scheduled O&M Task_Scheduled O&M_API_API Reference

Function

This API is used to create a scheduled O&M task, which triggers operations such as script execution and job management at a specified time or periodically.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
coc:schedule:create	Write	schedule	g:EnterpriseProjectId	-	-
		instance	coc:ApplicationCode coc:ApplicationGroupCode g:EnterpriseProjectId
		document	coc:DocumentRiskLevel g:EnterpriseProjectId
		-	coc:TicketLevel coc:TicketScope coc:RequestScope coc:TicketCurrentHandlers coc:TicketStatus coc:TicketType coc:TicketBeginTime coc:TicketEndTime coc:RequestTarget coc:TicketTarget coc:OperatorName coc:EscapeSwitchIsEnabled

URI

POST /v1/schedule/task

Request Parameters

**Table 1** Request body parameters
Parameter	Mandatory	Type	Description
ticket_infos	No	Array of TicketInfo objects	Definition For details about the configuration information related to change management, see Change Management. Constraints If service ticket authorization has been enabled for the current API in the change control module, this parameter is mandatory, that is, the corresponding privilege escalation information is provided. Range N/A Default Value N/A
name	Yes	String	Definition Task name. Constraints N/A Range The value can contain 3 to 100 characters, including letters, digits, hyphens (-), and underscores (_). Default Value N/A
enterprise_project_id	No	String	Definition Enterprise project ID. Constraints If no, create one inEnterprise Management. Range Select an existing enterprise project ID. Default Value 0
agency_name	No	String	Definition Specifies the agency name. Constraints If the selected agency does not have sufficient permissions, the task cannot be executed. Create an agency and grant permissions inIAM. Range Select an existing agency name. Default Value ServiceAgencyForCOC (recommended)
version_no	Yes	String	Definition Version number. Constraints N/A Range The value can be customized and contains 1 to 50 characters. Default Value 1.0.0
trigger_time	Yes	TriggerTime object	Definition Execution time details of a scheduled task. Constraints N/A Range For details, see the constraints on the value of TriggerTime. Default Value For details, see the constraints on the value of TriggerTime.
task_type	Yes	String	Definition Task type. Constraints N/A Range SCRIPT: script RUNBOOK: job Default Value SCRIPT
associated_task_id	Yes	String	Definition Associated task ID (script or job ID). Constraints The associated task must exist in the script or job management module. Range N/A Default Value N/A
associated_task_type	Yes	String	Definition Type of an associated task. Constraints N/A Range CUSTOMIZATION: custom script or job COMMUNAL: public script or job Default Value CUSTOMIZATION
associated_task_name	Yes	String	Definition Associated task name (script name or job name). Constraints This parameter is used together with associated_task_id. Range N/A Default Value N/A
associated_task_name_en	No	String	Definition Name of an associated task. Constraints This parameter is used together with associated_task_id. Range N/A Default Value N/A
associated_task_enterprise_project_id	No	String	Definition ID of the enterprise project of the associated task. Constraints This parameter is used together with associated_task_id. Range N/A Default Value N/A
runbook_instance_mode	No	String	Definition Mode of the target instance. Constraints Association method of instance resources. When the associated task type is job, this parameter is mandatory. Range SAME: All job steps are associated with the same instance resource. DIFF: Each task in each job step is associated with an independent instance resource. Default Value SAME
risk_level	Yes	String	Definition Risk level of a scheduled task. Constraints N/A Range HIGH MEDIUM LOW Default Value HIGH
input_param	Yes	Map<String,String>	Definition Task execution parameters, that is, execution parameters of the script or job. Constraints JSON string, which contains a maximum of 50 key-value pairs. The length of each value is 0 to 16777215 characters. The value must be the same as the execution parameters of the script or job. For example, if the script is used, you need to specify the execution user, timeout interval, and input parameters. Range N/A Default Value N/A
target_instances	Yes	Array of ScheduleInstance objects	Definition Target instance information. Constraints If the task is associated with a script, the array has only one element, that is, the resource instance associated with the script. If the task is associated with a job and the target instance is SAME, the array has only one element, that is, the resource instance associated with the job. If the task is associated with a job and the target instance is DIFF, the number of elements in the array is the same as the number of steps of the associated job, that is, the resource instance to be operated is specified separately for each task in each step. Range N/A Default Value N/A
enable_approve	Yes	Boolean	Definition Whether to enable manual review upon data input. Constraints N/A Range A boolean value. Default Value true
reviewer_notification	No	MessageNotification object	Definition Reviewer notification information. Constraints N/A Range For details, see the constraints on the value of MessageNotification. Default Value For details, see the constraints on the value of MessageNotification.
reviewer_user_name	No	String	Definition Reviewer nickname. Constraints Select a person whose information is available inPersonnel Management. Range N/A Default Value N/A
enable_message_notification	Yes	Boolean	Definition Whether to enable notification. Constraints N/A Range A boolean value. Default Value false
message_notification	No	MessageNotification object	Definition Notification information. Constraints N/A Range For details, see the constraints on the value of MessageNotification. Default Value For details, see the constraints on the value of MessageNotification.

**Table 2** TicketInfo
Parameter	Mandatory	Type	Description
ticket_id	No	String	Definition ID of the service ticket related to change management. Constraints Select the service ticket that takes effect currently. Range N/A Default Value N/A
ticket_type	No	String	Definition Service ticket type Constraints N/A Range CHANGE: change ticket. INCIDENT: incident ticket. WARROOM: war room ticket. Default Value N/A
target_id	No	String	Definition ID of the application associated with the service ticket. Constraints Select the application ID associated with the service ticket. Range N/A Default Value N/A
scope_id	No	String	Definition Region ID. Constraints Select the region ID associated with the service ticket. Range N/A Default Value N/A

**Table 3** TriggerTime
Parameter	Mandatory	Type	Description
time_zone	Yes	String	Definition Time zone. Constraints N/A Range An existing time zone Default Value Asia/Shanghai (GMT+8)
policy	Yes	String	Definition Execution policy of a scheduled task. Constraints N/A Range PERIODIC: The task is executed periodically. ONCE: The task is executed only once. CRON: The task is executed in cron expression. Default Value ONCE
single_scheduled_time	No	Long	Definition Execution time of a one-off scheduled task. Constraints When the scheduled task execution policy is one-off, this parameter is mandatory. Range Milliseconds-level UTC timestamp. Default Value N/A
periodic_scheduled_time	No	String	Definition Daily execution time of a periodic scheduled task. Constraints When the scheduled task execution policy is periodic, this parameter is mandatory. Range Time string in 24-hour format. If the task is executed at 5:30 PM on the current day, the value is 17:30:00. Default Value Current time
period	No	String	Definition Week days of a periodic scheduled task. Constraints When the scheduled task execution policy is periodic, this parameter is mandatory. Range Week days are separated by commas (,). Sunday is 1, and Monday is 2. Example: 1,2,4,5, indicating that the task is executed every Monday, Wednesday, Thursday, and Sunday. Default Value N/A
cron	No	String	Definition Cron expression of the scheduled task executed based on the cron expression. Constraints When the scheduled task execution policy is CRON, this parameter is mandatory. Range Use a valid cron expression. For example, if the task is executed at 10:15 AM every day, the value is 0 15 10 ? * . Default Value* N/A
scheduled_close_time	No	Long	Definition Execution end time of a scheduled task. Constraints When the scheduled task execution policy is PERIODIC or CRON, this parameter is mandatory, that is, the timestamp of the scheduled task rule expiration date. Range Milliseconds-level UTC timestamp. Default Value N/A

**Table 4** ScheduleInstance
Parameter	Mandatory	Type	Description
target_selection	Yes	String	Definition Target instance selection mode. Constraints N/A Range ALL: Select all instances. MANUAL: manual selection. NONE: No instance is specified. Default Value MANUAL
target_resource	No	TargetResource object	Definition Target instance search criteria. Constraints If the target instance selection mode is all instances, this parameter is mandatory. Range For details, see the constraints on the value of TargetResource. Default Value For details, see the constraints on the value of TargetResource.
target_instances	No	String	Definition Instance information. Constraints If the target instance selection mode is manual selection, this parameter is mandatory, indicating the details about the target instance resource. Range The value is a JSON string whose length range is 0 to 100000000. Default Value N/A
order_no	Yes	Integer	Definition Step No. Constraints If a scheduled task is associated with a script, the value is 1. If a scheduled task is associated with a job, the value indicates the step number in the job. Range N/A Default Value N/A
batch_strategy	No	String	Definition Instance batch policy. Constraints If a scheduled task is associated with a job and no resource instance needs to be specified for the current step, the value must be NONE. If all Instances is selected, the value must be AUTO_BATCH. If the resource instance is not empty, the value must be AUTO_BATCH or MANUAL_BATCH. Range AUTO_BATCH: automatic batching MANUAL_BATCH: manual batching NONE: no batching Default Value N/A
sub_target_instances	No	Array of ScheduleInstance objects	Definition Level-2 resource instance information. Constraints If a step of the job associated with the scheduled task contains multiple tasks and the target instance mode is DIFF, this parameter is mandatory, indicating that the resource instance is specified separately for each task. Range Array whose length range is 0 to 100. Default Value N/A

**Table 5** TargetResource
Parameter	Mandatory	Type	Description
type	No	String	Definition Resource selection mode (REGION or APPLICATION), that is, selecting resource instances by region or application. Constraints N/A Range REGION: Select resource instances by region. APPLICATION: Select resource instances by application. Default Value REGION
id	No	String	Definition ID of the region or application. Constraints The value must match the selected region or application. Range N/A Default Value N/A
app_name	No	String	Definition Application name. Hierarchical relationships are separated by periods (.) Constraints When the resource selection mode is APPLICATION, this parameter is mandatory, that is, the name of the selected application. Range N/A Default Value N/A
region_id	No	String	Definition ID of the region with which the application is associated. Constraints When the resource selection mode is APPLICATION, this parameter is mandatory, that is, the ID of the region associated with the selected application. Range N/A Default Value N/A
params	No	Array of ResourceQuery objects	Definition Dynamic query criteria of the resource instance. Constraints N/A Range For details, see the constraints on the value of ResourceQuery. Default Value For details, see the constraints on the value of ResourceQuery.

**Table 6** ResourceQuery
Parameter	Mandatory	Type	Description
key	Yes	String	Definition Attribute name of a resource. Constraints Select the attributes of resources in Application Resource Management, such as ep_id (enterprise project ID) and agent_state (UniAgent status). Range N/A Default Value N/A
value	Yes	String	Definition Parameter value of the resource attribute. Constraints Set the parameter value based on the selected key. Range N/A Default Value N/A

**Table 7** MessageNotification
Parameter	Mandatory	Type	Description
policy	No	String	Definition Notification policy Constraints When notification is enabled, this parameter is mandatory. The corresponding notification policy must be specified. Range START_EXECUTION EXECUTION_FAILED EXECUTION_SUCCEEDED Default Value N/A
notification_endpoint_type	Yes	String	Definition Notification object type. Constraints N/A Range USER: individual. ONCALL: shift. Default Value ONCALL
schedule_scene_id	No	String	Definition ID of the shift scenario. Constraints When the notification object type is on-call, this parameter is mandatory. That is, you need to specify the shift scenario ID. If no, create a scenario ID by referring toCreating a Shift Scenario. Range N/A Default Value N/A
schedule_role_id	No	String	Definition ID of the shift role. Constraints When the notification object type is on-call, this parameter is mandatory. That is, you need to specify the shift role ID. Ensure that the selected role ID exists in the selected shift scenario. Range N/A Default Value N/A
recipients	No	String	Definition Notification recipient ID. Constraints When the notification object type is individual, you need to specify the ID of the sender. Ensure that the selected notification recipient ID exists inPersonnel Management. Range N/A Default Value N/A
protocol	No	String	Definition Describes the notification slot. Constraints Ensure that the current channel has been subscribed to. For details, see user subscription inPersonnel Management. Range DEFAULT NONE: no notification. SMS EMAIL DingTalk LARK CALLNOTIFY WECHAT Default Value DEFAULT: Select any notification method you have subscribed to. If you have not subscribed to any notification method, you cannot receive notifications.

Response Parameters

Status code: 200

**Table 8** Response body parameters
Parameter	Type	Description
data	String	Definition Interface response data. Range N/A

Status code: 400

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Definition Result code. Range N/A
error_msg	String	Definition Error description. Range N/A

Example Requests

Create a scheduled task that is executed only once, associate the task type with script, and enable notification and manual review.

POST https://{Endpoint}/v1/schedule/task

{
  "name" : "test",
  "version_no" : "1.0.0",
  "enterprise_project_id" : "0",
  "task_type" : "SCRIPT",
  "associated_task_type" : "CUSTOMIZATION",
  "associated_task_id" : "SC****",
  "associated_task_enterprise_project_id" : "0",
  "associated_task_name" : "test-scripts",
  "input_param" : {
    "timeout" : 300,
    "execute_user" : "root",
    "success_rate" : 100,
    "project_id" : "****",
    "script_params" : "[]"
  },
  "target_instances" : [ {
    "target_selection" : "MANUAL",
    "target_instances" : "{\"batches\":[{\"batchIndex\":1,\"rotationStrategy\":\"CONTINUE\",\"targetInstances\":[{\"resourceId\":\"****\",\"regionId\":\"***\",\"provider\":\"ECS\",\"type\":\"CLOUDSERVERS\",\"agentSn\":\"****\",\"agentStatus\":\"ONLINE\",\"nodeId\":\"\",\"enterpriseProjectId\":\"0\",\"properties\":{\"hostName\":\"****\",\"fixedIp\":\"****\",\"floatingIp\":\"****\",\"regionId\":\"***\",\"zoneId\":\"***\",\"projectId\":\"****\"}}]}],\"policy\":\"none\",\"all_rotation\":\"ALL_CONTINUE\"}",
    "order_no" : 0,
    "batch_strategy" : "NONE"
  } ],
  "runbook_instance_mode" : "SAME",
  "agency_name" : "ServiceAgencyForCOC",
  "trigger_time" : {
    "time_zone" : "Asia/Shanghai",
    "policy" : "ONCE",
    "single_scheduled_time" : 1746072075000
  },
  "risk_level" : "LOW",
  "enable_approve" : true,
  "reviewer_user_name" : "****",
  "reviewer_notification" : {
    "notification_endpoint_type" : "USER",
    "protocol" : "DEFAULT",
    "recipients" : "****"
  },
  "enable_message_notification" : true,
  "message_notification" : {
    "policy" : "EXECUTION_FAILED,START_EXECUTION",
    "notification_endpoint_type" : "USER",
    "protocol" : "DEFAULT",
    "recipients" : "****"
  }
}

Example Responses

Status code: 200

Request result is returned.

{
  "data" : "ST****"
}

Status Codes

Status Code	Description
200	Request result is returned.
400	Incorrect request body is returned.

Error Codes

See Error Codes.

Creating a Scheduled O&M Task