Modifying a Scheduled Task_Scheduled O&M_API_API Reference

Function

This API is used to modify a scheduled O&M task.

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:update	Write	schedule *	g:EnterpriseProjectId	-	-
instance	coc:ApplicationCode coc:ApplicationGroupCode g:EnterpriseProjectId
document	coc:DocumentRiskLevel g:EnterpriseProjectId

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

coc:schedule:update

Write

schedule *

g:EnterpriseProjectId

-

instance

coc:ApplicationCode
coc:ApplicationGroupCode
g:EnterpriseProjectId

document

coc:DocumentRiskLevel
g:EnterpriseProjectId

URI

PUT /v1/schedule/task/{task_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
task_id	Yes	String	Definition ID of a scheduled task. Constraints An existing task that is disabled. Range A string of 26 characters starting with ST. Default Value N/A

Request Parameters

**Table 2** 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](tag:hws_hk). 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 3** 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 4** 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 5** 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 6** 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 7** 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 8** 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 9** Response body parameters
Parameter	Type	Description
id	String	Definition ID of a scheduled task. Range A string of 26 characters starting with ST.
enterprise_project_id	String	Definition ID of the enterprise project associated with a scheduled task. Range Select a project ID that is available inEnterprise Management.
name	String	Definition Scheduled task name. Range The value can contain 3 to 100 characters, including letters, digits, hyphens (-), and underscores (_).
agency_name	String	Definition Name of the agency associated with a scheduled task. Range Agency created in IAM](tag:hws_hk)
trigger_time	TriggerTime object	Definition Execution policy of a scheduled task. Range For details, see the constraints on the value of TriggerTime.
version_no	String	Definition Version number. Range The value contains 1 to 50 characters.
task_type	Object	Definition Type (script or job) of the task associated with the scheduled task. Range SCRIPT: script RUNBOOK: job
associated_task_id	String	Definition ID (script or job ID) of the task associated with the scheduled task. Range ID of a task that exists in script management or job management.
associated_task_name	String	Definition Name (script or job name) of the task associated with the scheduled task. Range Name of a task that exists in script or job management.
associated_task_name_en	String	Definition Name (script or job name) of the associated task. Range Name of a task that exists in script or job management.
associated_task_type	String	Definition Attribute (public or custom) of the task associated with a scheduled task. Range CUSTOMIZATION: custom script or job COMMUNAL: public script or job
runbook_instance_mode	String	Definition Target instance mode of a scheduled task. 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.
risk_level	String	Definition Risk level of a scheduled task. Range HIGH MEDIUM LOW
input_param	String	Definition Execution parameters of the scheduled task. Range 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.
enable_approve	Boolean	Definition Whether to enable manual review upon data input for a scheduled task. Range A boolean value.
reviewer_notification	MessageNotification object	Definition Reviewer notification information. Range For details, see the constraints on the value of MessageNotification.
created_user_name	String	Definition Nickname of the creator of a scheduled task. Range N/A
reviewer_user_name	String	Definition Nickname of the reviewer of a scheduled task. Range N/A
approve_status	Object	Definition Review status of a scheduled task. Range PASSED: normal PENDING: to be approved REJECTED: rejected
approve_comments	String	Definition Review comment of a scheduled task. Range N/A
target_instances	String	Definition Target node of a scheduled task. The value is a JSON string. Range N/A
enable_message_notification	Boolean	Definition Whether to enable notification. Range N/A
message_notification	MessageNotification object	Definition Notification format of a scheduled task. Range For details, see the constraints on the value of MessageNotification.

**Table 10** TriggerTime
Parameter	Type	Description
time_zone	String	Definition Time zone. Constraints N/A Range An existing time zone Default Value Asia/Shanghai (GMT+8)
policy	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	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	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	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	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	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 11** MessageNotification
Parameter	Type	Description
policy	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	String	Definition Notification object type. Constraints N/A Range USER: individual. ONCALL: shift. Default Value ONCALL
schedule_scene_id	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	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	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	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.

Status code: 400

**Table 12** 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

Change the risk level of the scheduled task to low, execution policy to one-time execution, associated task type to script, and disable manual review and notification.

PUT https://{Endpoint}/v1/schedule/task/ST****

{
  "name" : "scheduled_task_name",
  "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" : "script_name",
  "input_param" : {
    "success_rate" : "100",
    "timeout" : "300",
    "execute_user" : "root",
    "project_id" : "****",
    "script_params" : "[{\"paramName\":\"parm\",\"paramValue\":\"****\",\"paramOrder\":1}]"
  },
  "target_instances" : [ {
    "target_selection" : "MANUAL",
    "target_instances" : "{\"batches\":[{\"batchIndex\":1,\"rotationStrategy\":\"CONTINUE\",\"targetInstances\":[{\"resourceId\":\"****\",\"regionId\":\"***\",\"provider\":\"HCSS\",\"type\":\"L-INSTANCE\",\"agentSn\":\"****\",\"agentStatus\":\"ONLINE\",\"nodeId\":\"\",\"enterpriseProjectId\":\"0\",\"properties\":{\"hostName\":\"****\",\"fixedIp\":\"\",\"regionId\":\"***\",\"projectId\":\"****\"}}]}],\"policy\":\"none\",\"all_rotation\":\"ALL_CONTINUE\"}",
    "order_no" : 0,
    "batch_strategy" : "NONE"
  } ],
  "runbook_instance_mode" : "SAME",
  "trigger_time" : {
    "time_zone" : "Asia/Shanghai",
    "policy" : "ONCE",
    "single_scheduled_time" : 1746866130000
  },
  "risk_level" : "LOW",
  "enable_approve" : false,
  "enable_message_notification" : false
}

Example Responses

Status code: 200

Request result is returned.

{
  "approve_status" : "PASSED",
  "associated_task_id" : "SC****",
  "associated_task_name" : "script_name",
  "associated_task_type" : "CUSTOMIZATION",
  "created_user_name" : "****",
  "enable_approve" : false,
  "enable_message_notification" : false,
  "enterprise_project_id" : "0",
  "id" : "****",
  "input_param" : "{\"success_rate\":\"100\",\"timeout\":\"300\",\"execute_user\":\"root\",\"project_id\":\"****\",\"script_params\":\"[{\\\"paramName\\\":\\\"parm\\\",\\\"paramValue\\\":\\\"****\\\",\\\"paramOrder\\\":1}]\"}",
  "name" : "11111",
  "risk_level" : "LOW",
  "runbook_instance_mode" : "SAME",
  "target_instances" : "[{\"id\":\"****\",\"schedule_id\":\"ST****\",\"target_selection\":\"MANUAL\",\"target_instances\":\"{\\\"batches\\\":[{\\\"batchIndex\\\":1,\\\"rotationStrategy\\\":\\\"CONTINUE\\\",\\\"targetInstances\\\":[{\\\"resourceId\\\":\\\"****\\\",\\\"regionId\\\":\\\"***\\\",\\\"provider\\\":\\\"HCSS\\\",\\\"type\\\":\\\"L-INSTANCE\\\",\\\"agentSn\\\":\\\"****\\\",\\\"agentStatus\\\":\\\"ONLINE\\\",\\\"nodeId\\\":\\\"\\\",\\\"enterpriseProjectId\\\":\\\"0\\\",\\\"properties\\\":{\\\"hostName\\\":\\\"****\\\",\\\"fixedIp\\\":\\\"\\\",\\\"regionId\\\":\\\"***\\\",\\\"projectId\\\":\\\"****\\\"}}]}],\\\"policy\\\":\\\"none\\\",\\\"all_rotation\\\":\\\"ALL_CONTINUE\\\"}\",\"order_no\":0}]",
  "task_type" : "SCRIPT",
  "trigger_time" : {
    "policy" : "ONCE",
    "single_scheduled_time" : 1746866130000,
    "time_zone" : "Asia/Shanghai"
  },
  "version_no" : "1.0.0"
}

Status Codes

Status Code	Description
200	Request result is returned.
400	The server failed to process the request is returned.

Error Codes

See Error Codes.

Modifying a Scheduled Task