Help Center/ Workspace/ API Reference/ Workspace APIs/ Order/ Batch Changing Orders of Yearly/Monthly Desktops

Updated on 2026-02-10 GMT+08:00

View PDF

Batch Changing Orders of Yearly/Monthly Desktops

Function

Changes yearly/monthly desktop orders in batches.

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
workspace:orders:change	Write	-	workspace:ChangeOrderType	-	ims:images:list bss:order:update

URI

POST /v2/{project_id}/periodic/change/batch-order

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
type	No	String	Order placement type. ADD_VOLUME: Add a disk. EXTEND_VOLUME: expands the disk capacity. RESIZE: Modify specifications. CHANGE_IMAGE: switches images. ADD_SUB_RESOURCES: purchasing desktop collaboration resources DELETE_SUB_RESOURCES: unsubscribes from desktop collaboration resources.
agency_urn	No	String	URN of the agency authorized to billing services. This parameter is mandatory when you use the RAM shared key to create a yearly/monthly desktop, add a yearly/monthly disk, or rebuild the system.
add_volume_param	No	EstimateAddVolumeRequestBody object	Request body for querying the price for adding a disk or switching an image in a yearly/monthly desktop pool.
extend_volume_param	No	EstimateExtendVolumeRequestBody object	Request body for querying the price for expanding disk capacity in a yearly/monthly desktop pool.
resize_param	No	CreateResizeOrderRequestBody object	Request body for querying the price for changing the specifications of a yearly/monthly subscription.
change_image_param	No	CreateChangeImageOrderRequestBody object	Request body for querying the price for recomposing the system disk of a yearly/monthly subscription.
add_sub_resources_param	No	EstimateAddSubResourcesRequestBody object	Request body for querying the price for adding supplementary resources to a yearly/monthly subscription.
delete_sub_resources_param	No	CreateDeleteSubResourcesOrderRequestBody object	Request body for querying the price for deleting supplementary resources of a yearly/monthly subscription.

**Table 3** EstimateAddVolumeRequestBody
Parameter	Mandatory	Type	Description
desktop_pool_id	No	String	Desktop pool ID. If both desktop_pool_id and desktop_ids are set, the value of desktop_ids is used. The two parameters cannot be empty at the same time.
desktop_ids	No	Array of strings	IDs of yearly/monthly desktops. Common desktop IDs and pooled desktop IDs cannot coexist.
promotion_plan_id	No	String	Promotion plan ID.
handle_type	No	String	Processing type. ONLY_FOR_EXPAND: only added desktops FOR_EXPAND_AND_IDLE: added and idle desktops FOR_EXPAND_AND_ALL: added and existing desktops
desktop_pool_disk_id	No	String	ID of the disk to be added to the desktop pool. This parameter is mandatory when disks are inconsistent.
volume_type	Yes	String	Type of the newly added disk.
volume_size	Yes	Integer	Size of the newly added disk.
iops	No	Integer	Number of read/write operations performed by an EVS disk per second.
throughput	No	Integer	Amount of data read from and written to an EVS disk per second.
kms_id	No	String	ID of the key that is transferred when the disk is encrypted.

**Table 4** EstimateExtendVolumeRequestBody
Parameter	Mandatory	Type	Description
desktop_pool_id	No	String	Desktop pool ID. If both desktop_pool_id and desktop_ids are set, the value of desktop_ids is used. The two parameters cannot be empty at the same time.
desktop_ids	No	Array of strings	IDs of yearly/monthly desktops. Common desktop IDs and pooled desktop IDs cannot coexist.
promotion_plan_id	No	String	Promotion plan ID.
handle_type	No	String	Processing type. ONLY_FOR_EXPAND: only added desktops FOR_EXPAND_AND_IDLE: added and idle desktops FOR_EXPAND_AND_ALL: added and existing desktops
desktop_pool_disk_id	Yes	String	ID of the disk to be expanded in the desktop pool.
new_size	Yes	Integer	New disk size. The size must be larger than that specified in the current desktop pool template in an entire-pool operation.

**Table 5** CreateResizeOrderRequestBody
Parameter	Mandatory	Type	Description
desktop_pool_id	No	String	Desktop pool ID. If both desktop_pool_id and desktop_ids are set, the value of desktop_ids is used. The two parameters cannot be empty at the same time.
desktop_ids	No	Array of strings	IDs of yearly/monthly desktops. Common desktop IDs and pooled desktop IDs cannot coexist.
promotion_plan_id	No	String	Promotion plan ID.
handle_type	No	String	Processing type. ONLY_FOR_EXPAND: only added desktops FOR_EXPAND_AND_IDLE: added and idle desktops FOR_EXPAND_AND_ALL: added and existing desktops
product_id	Yes	String	Product ID of the target specifications.
mode	No	String	Whether specifications can be modified when the desktop is started. The value is fixed to STOP_DESKTOP. If the desktop has been started, the desktop will be stopped before the specifications are modified.

**Table 6** CreateChangeImageOrderRequestBody
Parameter	Mandatory	Type	Description
desktop_pool_id	No	String	Desktop pool ID. If both desktop_pool_id and desktop_ids are set, the value of desktop_ids is used. The two parameters cannot be empty at the same time.
desktop_ids	No	Array of strings	Desktop ID.
promotion_plan_id	No	String	Promotion plan ID.
handle_type	No	String	Processing type. ONLY_FOR_EXPAND: only added desktops FOR_EXPAND_AND_IDLE: added and idle desktops FOR_EXPAND_AND_ALL: added and existing desktops
image_spec_code	No	String	specCode of the KooGallery image. This parameter will be disabled soon. If both image_spec_code and image_id are set, the value of image_id is used. The two parameters cannot be empty at the same time.
image_id	No	String	KooGallery image ID. image_id is recommended.
image_type	No	String	Image type. This parameter is only required for system disk rebuilding or image replacement. private: private image gold: public image.
delay_time	No	Integer	Time reserved for users to save data during immediate recomposing (unit: minute).
message	No	String	Message sent to a user when a system disk recomposing task is delivered.
encrypt_type	No	String	Encryption type. KEEP: original encryption state retained UNENCRYPTED: not encrypted ENCRYPTED: encrypted (kms_id needs to be uploaded at the same time)
kms_id	No	String	Key ID. This parameter is mandatory when encrypt_type is set to ENCRYPTED.

**Table 7** EstimateAddSubResourcesRequestBody
Parameter	Mandatory	Type	Description
desktop_pool_id	No	String	Desktop pool ID. If both desktop_pool_id and desktop_ids are set, the value of desktop_ids is used. The two parameters cannot be empty at the same time.
desktop_ids	No	Array of strings	IDs of yearly/monthly desktops. Common desktop IDs and pooled desktop IDs cannot coexist.
promotion_plan_id	No	String	Promotion plan ID.
handle_type	No	String	Processing type. ONLY_FOR_EXPAND: only added desktops FOR_EXPAND_AND_IDLE: added and idle desktops FOR_EXPAND_AND_ALL: added and existing desktops
sub_resource_sku	Yes	String	Add an appendant resource SKU code.

**Table 8** CreateDeleteSubResourcesOrderRequestBody
Parameter	Mandatory	Type	Description
desktop_pool_id	No	String	Desktop pool ID. If both desktop_pool_id and desktop_ids are set, the value of desktop_ids is used. The two parameters cannot be empty at the same time.
desktop_ids	No	Array of strings	IDs of yearly/monthly desktops. Common desktop IDs and pooled desktop IDs cannot coexist.
promotion_plan_id	No	String	Promotion plan ID.
handle_type	No	String	Processing type. ONLY_FOR_EXPAND: only added desktops FOR_EXPAND_AND_IDLE: added and idle desktops FOR_EXPAND_AND_ALL: added and existing desktops
sub_resource_type	Yes	String	Type of the appendant resource to be deleted: DESKTOP_SHARER (desktop collaboration resource)

Response Parameters

Status code: 200

**Table 9** Response body parameters
Parameter	Type	Description
orders	Array of OrderV5 objects	Result of generating orders in batches.

**Table 10** OrderV5
Parameter	Type	Description
order_id	String	Order ID.
order_status	Integer	Order status. The value can be 0 (initialized), 1 (to be reviewed), 2 (to be refunded), 3 (being processed), 4 (canceled), 5 (completed), 6 (to be paid); 7 (being compensated), 8 (to be approved), 9 (to be confirmed), 10 (to be shipped), 11 (to be received), 12 (to be picked up), 13 (being replaced), or 14 (to be received by the seller).
result	String	Result. The value can be SUCCESS or FAIL.
result_code	String	If result is set to FAIL, this parameter is mandatory, indicating the failure cause of the order.
result_msg	String	Failure information, which is used together with result_code.

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 409

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 500

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Example Requests

{
  "type" : "ADD_VOLUME",
  "add_volume_param" : {
    "desktop_pool_id" : "b046ac8e-0994-4c09-a8a8-bd989d218120",
    "volume_type" : "SAS",
    "volume_size" : 10
  }
}

Example Responses

Status code: 200

Response body for placing orders on yearly/monthly desktops in batches.

{
  "orders" : [ {
    "order_id" : "CS25052414519W9OP",
    "order_status" : 6
  } ]
}

Status Codes

Status Code	Description
200	Response body for placing orders on yearly/monthly desktops in batches.
400	The request cannot be understood by the server due to malformed syntax.
409	Operation conflict.
500	Internal server error.