Elastic Compute Service
Elastic Compute Service
Document
- Documentation
Elastic Compute ServiceElastic Compute ServiceAPI ReferenceCloud assistantCreateCommand - Creates custom commands
Copy page
Download PDFCloud assistant
CreateCommand - Creates custom commands
Copy pageDownload PDFCreateCommand - Creates custom commands
Call the CreateCommand operation to create a custom command.
Usage notes
You can configure the custom parameters in the command via the ParameterDefinitions.N.xxx parameters. The usage rules are as follows:
- Argument - N: indicates the serial number of the custom parameter. Valid range: 1-60.
- Separate multiple custom parameters with &.
Debugging
API Explorer
You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.
Request parameters
Only the request parameters specific to this operation and some common parameters are listed below. For more information, refer to Common parameters.
Action string required Sample value: CreateCommand
The action that you want to perform. Value: CreateCommand.
Version string required Sample value: 2020-04-01
The version of the API. Valid value: 2020-04-01.
Tags.N.Value string[] Optional Sample value: Tags.1.Value=v1&Tags.2.Value=v2
The value of the user tag.
- Argument - N: specifies the serial number of the tag value. Valid range: 1–20.
- Separate multiple key values with ampersands (&).
Naming rules:
- Only language characters, digits, spaces, and English symbols of " _", ".", ":", "/", "=", "+", "-", and "@" are allowed.
- It can be empty. Length limit: 0–256 characters.
tip
To pass in this parameter, pass in Tags.N.Key first.
ProjectName string Optional Sample value: default
The associated project. Each instance can only belong to one project.
Tags.N.Key string[] Optional Sample value: Tags.1.Key=k1&Tags.2.Key=k2
The key of the user tag.
- Argument - N: specifies the serial number of the tag key. Valid range: 1–20.
- Separate multiple keys with ampersands (&).
Naming rules:
- It cannot start with volc: or sys: in any case form.
- Only language characters, digits, spaces, and English symbols of "_", ".", ":", "/", "=", "+", "-", and "@" are allowed.
- It must be 1 to 128 characters in length.
tip
Keys of the same resource must be unique.
Name string required Sample value: updateAgent
The command name. Naming rules are as follows:
- Character length: 1–32.
- Special characters can be used.
Description string Optional Sample value: This is a new command.
The command description. Default value: empty string.
- Character length: 0–256.
- Special characters can be used.
Type string required Sample value: Shell
The command type. Value:
- Shell: Indicates creating a Shell script that runs in a Linux instance.
- Python: Indicates creating a Python script.
- Bat: Indicates creating a Bat script.
- PowerShell: Indicates creating a PowerShell script.
EnableParameter boolean Optional Sample value: false
Indicates whether the created command enables the custom parameter feature. Value:
- false (default): Disables the custom parameter feature.
- True: Enables the custom parameter feature.
ParameterDefinitions.N.Name string[] Optional Sample value: ParameterDefinitions.1.Name=dir
The parameter name, which needs to be defined in the script based on {{Param}}. Naming rules:
- A parameter name can not exceed 64 bytes in length.
- Follow Shell variable naming conventions: Use lowercase letters, uppercase letters, digits, underscores, and hyphens. Cannot begin with a digit. No spaces are allowed in the middle. Underscores can be used.
ParameterDefinitions.N.Type string[] Optional Sample value: ParameterDefinitions.1.Type=String
The custom parameter type. Value:
- String: Indicates that the custom parameter is of the String (string) type.
- Digit: Indicates that the custom parameter is of the Digit (numeric type) type.
ParameterDefinitions.N.Required boolean[] Optional Sample value: ParameterDefinitions.1.Required=true
Indicates whether the parameter is required. Value:
- true: Required.
- false: Not required.
ParameterDefinitions.N.DefaultValue string[] Optional Sample value: ParameterDefinitions.1.DefaultValue=ecs
The default value of the custom parameter.
ParameterDefinitions.N.MinLength integer[] Optional Sample value: ParameterDefinitions.1.MinLength=1
The minimum length of the custom parameter value (string).
- Value range of MinLength: 1~1000.
- When Type=String, the parameter is required, and when Required is set to true, the default value is 1.
- The parameter value needs to be smaller than the value of MaxLength.
ParameterDefinitions.N.MaxLength integer[] Optional Sample value: ParameterDefinitions.1.MaxLength=98
The maximum length of the custom parameter value (string).
- Value range of MaxLength: 1~1000.
- When Type=String, the parameter is required, and when Required is set to true, the default value is 1000.
- The parameter value needs to exceed the value of MinLength.
ParameterDefinitions.N.MinValue string[] Optional Sample value: ParameterDefinitions.1.MinValue=1
The minimum value (number) of the custom parameter.
- Value range of MinValue: -1000000~1000000.
- When Type=Digit, the parameter is required, and when Required is set to true, the default value is -1000000.
- The parameter value cannot exceed the value of MaxValue
ParameterDefinitions.N.MaxValue string[] Optional Sample value: ParameterDefinitions.1.MaxValue=100
The maximum value (number) of the custom parameter.
- Value range of MaxValue: -1000000~1000000.
- When Type=Digit, the parameter is required, and when Required is set to true, the default value is 1000000.
- The parameter value cannot exceed the value of MinValue.
ParameterDefinitions.N.DecimalPrecision integer[] Optional Sample value: ParameterDefinitions.1.DecimalPrecision=4
The number of decimal places allowed for the custom parameter value (number).
- Value range of DecimalPrecision: 0~10.
- When Type=Digit, the parameter is required, and when Required is set to true, the default value is 0.
CommandContent string required Sample value: IyEvYmluL2Jhc2gKZWNobyAib3BlcmF0aW9uIHN1Y2Nlc3MhIg==
The command content.
- Provide the corresponding command content based on the ContentEncoding parameter.
- Before coding, make sure that the first line of the script specifies the script interpreter. The rules are as follows:
- Shell script: The first line needs to be #!/bin/bash.
- Python script: The first line needs to be #!/usr/bin/python.
- The size of the command content must not exceed 16 KB.
- When EnableParameter=true, the command content supports custom parameters. Rules are as follows:
- Define the custom parameter and enclose it in {{}}.
- Spaces and line breaks before and after the parameter name within {{}} are ignored.
WorkingDir string Optional Sample value: /home
The directory where the created command runs on the ECS instance. For Linux instances, the default value is /home.
Username string Optional Sample value: root
The user name when the command is executed.
Timeout integer Optional Sample value: 60
The maximum timeout duration for the created command running on the ECS instance. Unit: seconds.
- Value range: 30~86400.
- Default value: 60.
ContentEncoding string Optional Sample value: Base64
Specifies whether the command content is Base64 encoded. Value:
- Base64 (default): The command content is Base64 encoded.
- PlainText: The command content is not Base64 encoded.
Response parameters
Only the response parameters specific to this operation are listed below. For more information, refer to the response structure.
CommandId string Sample value: cmd-ycgpkuavyrm0tq****
The custom command ID.
Sample request
GET /?Action=CreateCommand&Version=2020-04-01&Name=demo&Description=123&Type=Shell&EnableParameter=true&ParameterDefinitions.1.Name=a&ParameterDefinitions.1.Description=desc&ParameterDefinitions.1.Required=true&ParameterDefinitions.1.Required=true&ParameterDefinitions.1.DefaultValue=123&ParameterDefinitions.1.Type=String&ParameterDefinitions.1.MaxLength=1000&ParameterDefinitions.1.MinLength=1&CommandContent=IyEvYmluL2Jhc2gKZWNobyB7e2F9fQ==&WorkingDir=/home&Username=root&Timeout=60
Host: ecs.cn-beijing.volcengineapi.com
Region: cn-beijing
Service: ecs
Sample response
{
"ResponseMetadata":{
"RequestId":"2023082515303301022514515207C4****",
"Action":"CreateCommand",
"Version":"2020-04-01",
"Service":"ecs",
"Region":"cn-beijing"
},
"Result":{
"CommandId":"cmd-shhrh****"
}
}
Error codes
The table below lists the business-related error codes of the operation. For more information, refer to Common error codes.
Last updated: 2026.06.18 17:48:26
All rights reserved © Beijing Volcano Engine Technology Co., Ltd2024
