Help Center/ Cloud Eye/ API Reference/ API V3/ Agent maintenance tasks/ Creating Agent maintenance Tasks in Batches

Updated on 2025-10-30 GMT+08:00

View PDF

Creating Agent maintenance Tasks in Batches

Function

This API is used to create Agent maintenance tasks in batches.

Constraints

Currently, this API is not supported in the LA-Buenos Aires1 and LA-Lima1 regions.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

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
ces:agent:createAgentInvocations	Write	-	-	ces:taskInvocation:post	-

URI

POST /v3/{project_id}/agent-invocations/batch-create

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: Tenant ID. It is used to specify the project that an asset belongs to. You can query the assets of a project by project ID. You can obtain the project ID from the API or console. For details, see Obtaining a Project ID. Range: 1 to 64 characters Constraints N/A Range 1 to 64 characters Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	No	String	Definition MIME type of the request body. Constraints N/A Range 1 to 64 characters Default Value application/json; charset=UTF-8
X-Auth-Token	No	String	Specifies the user token. It is a response to the API for obtaining a user token. This API is the only one that does not require authentication. The value of X-Subject-Token in the response header is the token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
instance_ids	No	Array of strings	Definition Server ID list. (This parameter is mandatory when the task type is INSTALL or UPDATE.) Range The array length ranges from 1 to 100.
invocation_type	Yes	String	Task type. The options are INSTALL, UPDATE, ROLLBACK, RETRY, SET_REMOTE_INSTALLER, and REMOTE_INSTALL.
invocation_target	No	String	Definition Task object. The value can only be telescope. Range telescope: server monitoring plug-in
invocation_ids	No	Array of strings	Definition Task ID list. This parameter is mandatory when the task type is ROLLBACK or RETRY. Range The array length ranges from 1 to 100.
version_type	No	String	Definition Version that the Agent will be upgraded to. Range BASIC_VERSION: basic version ADVANCE_VERSION: enhanced version
origin	No	String	Definition Source for calling the Agent task APIs. Range CES: Cloud Eye console APICOM_BMS: BMS ADMIN_SERVER: O&M platform
version	No	String	Definition Version number. Range [0,64]
remote_install_meta	No	Array of RemoteInstallHostInfo objects	Definition Information about the server for remotely installing the Agent when a remote installation task is created. Range [0,100]

**Table 4** RemoteInstallHostInfo
Parameter	Mandatory	Type	Description
instance_name	No	String	Definition Name of the server for remotely installing the Agent. Range [1,128]
remote_ip	No	String	Definition IP address of the server for remotely installing the Agent. Range The value allows 1 to 15 characters and can only contain digits and dots (.).
user_name	No	String	Definition Username for logging in to the server for remotely installing the Agent. Range [1,16]
port	No	String	Definition Port for logging in to the server for remotely installing the Agent. Range [1,5]
password	No	String	Definition Password for logging in to the server for remotely installing the Agent. Range [1,3000]
remote_use_pem	No	Boolean	Whether a key pair is used to connect to the server for remotely installing the Agent. If the value is false, a password is used.

Response Parameters

Status code: 201

**Table 5** Response body parameters
Parameter	Type	Description
invocations	Array of BatchCreateInvocationInfo objects	Definition Information list of the created task. Range [0,100]

**Table 6** BatchCreateInvocationInfo
Parameter	Type	Description
instance_id	String	Definition Server ID. Range The value allows 1 to 64 characters and can only contain letters, digits, and hyphens (-).
invocation_id	String	Definition Task ID. Range The value allows 1 to 64 characters and can only contain letters, digits, and hyphens (-).
ret_status	String	Definition Task result. The value can be successful or error. Range successful: succeeded error: failed
error_code	String	Definition Error code. Range The value starts with "invocationmgr." and is followed by four digits.
error_msg	String	Definition Error message. Range [1,128]

Status code: 400

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Specifies the error code.
error_msg	String	Specifies the error message.

Status code: 401

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Specifies the error code.
error_msg	String	Specifies the error message.

Status code: 403

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Specifies the error code.
error_msg	String	Specifies the error message.

Status code: 500

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Specifies the error code.
error_msg	String	Specifies the error message.

Example Requests

{
  "instance_ids" : [ "instancexxx001", "instancexxx002" ],
  "invocation_type" : "INSTALL",
  "invocation_target" : "telescope"
}

Example Responses

Status code: 201

Created

[ {
  "instance_id" : "instancexxx001",
  "ret_status" : "successful"
}, {
  "instance_id" : "instancexxx002",
  "ret_status" : "error",
  "error_msg" : "do not meet the installation conditions"
} ]