Command Interface
Updated at：2025-10-20
Create command
API description
Create command, supporting Save, Execute Only or Execute and Save
Request structure
Plain Text
1POST /v1/ca/actionRequest headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| execution | String | Yes | RequestBody | Execution action. Enumeration options: SAVE (Save Only), RUN (Execute Only), SAVE_AND_RUN (Save and Execute). |
| action | Action | Yes | RequestBody | Details of executed action |
| parameters | Map | No | RequestBody | Parameter values during command execution, required only when the command includes parameters and needs execution |
| targetSelectorType | String | No | RequestBody | Instance selector type, required only when the execution action is Execute or Save and Execute. Default value is INSTANCES_LIST. Options include: INSTANCES_LIST (instance list), ALL_INSTANCES (all instances), TAG_INSTANCES (instance tag selection), INSTANCES_IMPORT (instance list import). |
| targets | List<Target> | No | Query | Instance ID List, required only when targetSelectorType is INSTANCES_LIST |
| targetSelector | TargetSelector | No | Query | Instance selector |
Response headers
No special headers beyond common headers.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| actionId | String | Command ID |
| actionType | String | Action type. Enumeration options: COMMAND (script command), FILE_UPLOAD (file upload). |
| actionName | String | Command name |
| commandType | String | Script type. Enumeration options: SHELL, POWERSHELL. |
| version | int | Command version number. Starts at 0 and increments by 1 with each modification. |
| runId | String | Execution ID, responded only during command execution |
Request example
JSON
1POST /v1/ca/action
2{
3 "execution": "RUN",
4 "action": {
5 "type": "COMMAND",
6 "description": "this is a test",
7 "timeoutSecond": 300,
8 "command": {
9 "type": "SHELL",
10 "content": "ls",
11 "scope": "INDIVIDUAL",
12 "enableParameter": false,
13 "user": "root",
14 "workDir": "/home"
15 }
16 },
17 "targets": [
18 {
19 "instanceType": "BCC",
20 "instanceId": "i-p9L8X***"
21 }
22 ]
23}Response example
JSON
1{
2 "requestId": "83e831f9-8f27-4c1c-bde4-fdfb********",
3 "code": "success",
4 "result": {
5 "actionId": "c-cVtZHfVRD8******",
6 "actionType": "COMMAND",
7 "commandType": "SHELL",
8 "version": 0,
9 "runId": "r-h5fTUn2sab******"
10 }
11}Delete command
API description
Delete saved commands
Request structure
Plain Text
1DELETE /v1/ca/action/{id}Request headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| id | String | Yes | Path | Command ID |
Response headers
No special headers beyond common headers.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| requestId | String | Request ID |
| code | String | Response state, where successful execution is indicated by success. |
Request example
JSON
1DELETE /v1/ca/action/c-cVtZHfVRD8******Response example
JSON
1{
2 "requestId": "b7d01b02-40ea-4ed2-9969-925790******",
3 "code": "success",
4}Query command details
API description
Query saved commands or public commands
Request structure
Plain Text
1GET /v1/ca/actionRequest headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| id | String | Yes | Query | Command ID |
Response headers
No special headers beyond common headers.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| requestId | String | Request ID |
| code | String | Response state, where successful execution is indicated by success. |
| result | Action | Command details |
Request example
JSON
1GET /v1/ca/action?id=c-cVtZHfVRD8******Response example
JSON
1{
2 "requestId" : "8f713916-d41b-472a-a06b-8a80cb******",
3 "code": "success",
4 "result": {
5 "id": "a-CwkIRFAaoUCx",
6 "name": "test_command",
7 "description": "Install and upgrade HAS-Agent to the latest version",
8 "timeoutSecond": 300,
9 "type": "COMMAND",
10 "command": {
11 "type": "SHELL",
12 "content": "",
13 "enableParameter": false,
14 "parameters": [
15 {
16 "name": "Parameter name",
17 "desc" : "desc"
18 }
19 ],
20 "user": "work",
21 "workDir": "/home/work/"
22 },
23 "createdTimestamp": 1659534994121,
24 "updatedTimestamp": 1659534994121
25 }
26}Modify my command
API description
Modify my command
Request structure
Plain Text
1PUT /v1/ca/actionRequest headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| action | UpdateActionRequest | Yes | RequestBody | Details of executed action |
UpdateActionRequest
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| ref | String | Yes | RequestBody | Command ID to be modified |
| name | String | Yes | RequestBody | Modified command name |
| description | String | Yes | RequestBody | Modified command description |
| timeoutSecond | int | Yes | RequestBody | Modified command timeout duration (seconds) |
| command | Command | Yes | RequestBody | Modified command |
Response headers
No special headers beyond common headers.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| requestId | String | Request ID |
| code | String | Response state, where successful execution is indicated by success. |
Request example
JSON
1PUT /v1/ca/action
2{
3 "action": {
4 "ref": "c-WgEtWtD3sV******",
5 "name": "cmd_2024_03_21_16_41_32",
6 "description": "this is a test",
7 "timeoutSecond": 60,
8 "command": {
9 "type": "SHELL",
10 "scope": "INDIVIDUAL",
11 "enableParameter": true,
12 "parameters": [
13 {
14 "name": "param1",
15 "desc": "this is a text"
16 }
17 ],
18 "user": "root",
19 "workDir": "/home",
20 "content": "{{param1}}"
21 }
22 }
23}Response example
JSON
1{
2 "requestId": "be82abc6-eb4c-4a51-9f52-f59b97******",
3 "code": "success"
4}Query command list
API description
Query my command list or public command list
Request structure
Plain Text
1POST /v1/ca/action/listRequest headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| action | ActionFilter | Yes | RequestBody | Command filter |
| pageNo | int | Yes | RequestBody | Page No. |
| pageSize | int | Yes | RequestBody | Page size |
| sort | String | No | RequestBody | Sorting field, option: createTime (command creation time) |
| ascending | bool | No | RequestBody | Is it in ascending order? It is false by default. |
ActionFilter
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| command | CommandFilter | Yes | RequestBody | Details of executed action |
CommandFilter
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| scope | String | Yes | RequestBody | Filter by command visibility scope. Enumeration options: INDIVIDUAL (personal commands), GLOBAL (public commands). |
| type | String | No | RequestBody | Filter by command type. Enumeration options: SHELL, POWERSHELL. |
| name | String | No | RequestBody | Filter by command name. |
Response headers
No special headers beyond common headers.
Response parameters
The result in the common response body is as follows:
| Parameter name | Types | Description |
|---|---|---|
| pageNo | int | Page No. |
| pageSize | int | Page size |
| totalCount | int | Total |
| data | List<Action> | Command list |
Request example
JSON
1POST /v1/ca/action/list
2{
3 "action": {
4 "type": "COMMAND",
5 "command": {
6 "scope": "INDIVIDUAL",
7 "name": "test"
8 }
9 },
10 "sort": "createTime",
11 "ascending": false,
12 "pageNo": 1,
13 "pageSize": 10
14}Response example
JSON
1{
2 "requestId": "ca1316b5-3fab-4c91-aeac-ad51fd******",
3 "code": "success",
4 "result": {
5 "pageNo": 1,
6 "pageSize": 10,
7 "totalCount": 1,
8 "data": [
9 {
10 "id": "c-4CtIumYWlo******",
11 "type": "COMMAND",
12 "name": "cmd_test_test",
13 "timeoutSecond": 30,
14 "command": {
15 "type": "SHELL",
16 "content": "ls",
17 "scope": "INDIVIDUAL",
18 "enableParameter": false,
19 "workDir": "/home",
20 "user": "root"
21 },
22 "createdTimestamp": 1694672762000,
23 "updatedTimestamp": 1694672762000
24 }
25 ]
26 }
27}Execution command
API description
Execute my commands or public commands created
Request structure
Plain Text
1POST /v1/ca/actionRunRequest headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Required or not | Parameter location | Description |
|---|---|---|---|---|
| action | Action | Yes | RequestBody | Command to be executed, only the ID needs to be filled in |
| parameters | Map | No | RequestBody | Parameter values during command execution, required only when the command includes parameters |
| targetSelectorType | String | No | RequestBody | Instance selector type. Default value is INSTANCES_LIST. Options: INSTANCES_LIST (instance list), ALL_INSTANCES (all instances), TAG_INSTANCES (instance tag selection), INSTANCES_IMPORT (instance list import). |
| targets | List<Target> | No | Query | Instance ID List, required only when targetSelectorType is INSTANCES_LIST |
| targetSelector | TargetSelector | No | Query | Instance selector |
Response headers
No special headers beyond common headers.
Response parameters
The result in the common response body is as follows:
| Parameter name | Types | Description |
|---|---|---|
| actionId | String | Command ID |
| runId | String | Execution ID |
Request example
JSON
1POST /v1/ca/actionRun
2{
3 "action": {
4 "ref": "c-WgEtWtD3sV******"
5 },
6 "parameters": {
7 "param1": "pwd"
8 },
9 "targetSelectorType": "INSTANCES_LIST",
10 "targets": [
11 {
12 "instanceType": "BCC",
13 "instanceId": "i-EVLpS***"
14 }
15 ]
16}Response example
JSON
1{
2 "requestId": "87c25fbd-21c9-4082-904a-0d8c85******",
3 "code": "success",
4 "result": {
5 "runId": "r-2InH1HsWXU******",
6 "actionId": "c-WgEtWtD3sV******"
7 }
8}Appendix
Action
| Parameter name | Types | Description |
|---|---|---|
| id | String | Command ID, only available for saved commands |
| type | String | Action type. Enumeration options: COMMAND (command), FILE_UPLOAD (file upload). |
| name | String | Command name, only available for saved commands |
| description | String | Action description |
| timeoutSecond | int | Action timeout duration (seconds) |
| command | Command | Command details |
| fileUpload | FileUpload | Details of file uploading |
| createdTimestamp | long | Command creation time, given as a Unix timestamp (in milliseconds). |
| updateTimestamp | long | Last modification time of the command, represented as a Unix timestamp (in milliseconds). |
Command
| Parameter name | Types | Description |
|---|---|---|
| type | String | Script type. Enumeration options: SHELL, POWERSHELL. |
| scope | String | Command visibility scope. GLOBAL signifies public commands, while INDIVIDUAL signifies personal commands. |
| content | long | Command script content |
| enableParameter | bool | Does the command include parameters? |
| parameters | List<Parameter> | Command parameter list |
| user | String | Execution user of the command on the virtual machine |
| workDir | int | Execution route of the command on the virtual machine |
| execParams | Map<String, String> | Actual parameter values during command execution |
FileUpload
| Parameter name | Types | Description |
|---|---|---|
| os | String | Operating system. Enumeration options: LINUX, WINDOWS. |
| filename | String | File name |
| filepath | String | Target path |
| bosBucketName | String | BOS bucket name |
| bosFilePath | String | BOS file path |
| bosEtag | String | Unique identifier of file |
| overwrite | bool | Whether to overwrite files with the same name in the target path. |
| user | String | User, required only for Linux file uploading |
| group | String | Group, only required for Linux file uploads |
| mode | String | File permission, only required for Linux file uploading |
Parameter
| Parameter name | Types | Description |
|---|---|---|
| name | String | Parameter name |
| desc | String | Parameter description |
TargetSelector
| Parameter name | Types | Description |
|---|---|---|
| instanceType | String | Instance type. Possible values: BCC, BBC |
| tags | List<Tag> | Instance tag list |
| importInstances | TargetImport | Instance tag list |
Tag
| Parameter name | Types | Description |
|---|---|---|
| tagKey | String | Tag key |
| tagValue | String | Tag value |
TargetImport
| Parameter name | Types | Description |
|---|---|---|
| keywordType | String | Instance list import type. Possible values: instanceId (import using instance ID), internalIp (import using the instance's internal IP) |
| instances | List |
Instance inventory |
Target
| Parameter name | Types | Description |
|---|---|---|
| instanceType | String | Instance type. Possible values: BCC, BBC |
| instanceId | List |
List of instance IDs |