Document navigation

Script Library

CreateGuestVmScript

API Request

URLs

POST zstack/v1/scripts

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "name": "script1",
    "description": "this is a script",
    "scriptContent": "ZWNobyBoZWxsb3dvcmxkCg\u003d\u003d",
    "renderParams": "[{\"key\":\"key\",\"value\":\"value\",\"description\":\"description\"}]",
    "platform": "Linux",
    "scriptType": "Shell",
    "scriptTimeout": 30
  },
  "systemTags": [],
  "userTags": []
}

In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"script1","description":"this is a script","scriptContent":"ZWNobyBoZWxsb3dvcmxkCg==","renderParams":"[{\"key\":\"key\",\"value\":\"value\",\"description\":\"description\"}]","platform":"Linux","scriptType":"Shell","scriptTimeout":30}}' http://localhost:8080/zstack/v1/scripts

Request Parameters

Name Type Location Description Valid Values Starting Version
name String body (contained in the params structure) The resource name. 5.2.0
description String body (contained in the params structure) Optional. Optional. The detailed description of the resource. 5.2.0
scriptContent String body (contained in the params structure) The script content. 5.2.0
renderParams String body (contained in the params structure) Optional. The custom parameters. 5.2.0
platform String body (contained in the params structure) The platform.
  • Windows
  • Linux
5.2.0
scriptType String body (contained in the params structure) The script type.
  • Shell
  • Python
  • Perl
  • Bat
  • Powershell
5.2.0
scriptTimeout int body (contained in the params structure) Optional. The timeout period. 5.2.0
resourceUuid String body (contained in the params structure) Optional. The resource UUID. 5.2.0
tagUuids List body (contained in the params structure) Optional. The tag UUID list. 5.2.0
systemTags List body Optional. The system tags. 5.2.0
userTags List body Optional. The user tags. 5.2.0

API Response

Sample Response

{
  "inventory": {
    "uuid": "a90f02b86916371a87bb5f2716dbfc0c",
    "name": "script1",
    "description": "this is a script",
    "scriptContent": "echo helloworld",
    "renderParams": "[{\"key\":\"key\",\"value\":\"value\",\"description\":\"description\"}]",
    "platform": "Linux",
    "scriptType": "Shell",
    "scriptTimeout": 30,
    "createDate": "Sep 23, 2024 11:53:59 AM",
    "lastOpDate": "Sep 23, 2024 11:53:59 AM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 5.2.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error 5.2.0
inventory GuestVmScriptInventory See inventory 5.2.0

#error

Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 5.2.0
description String The brief description of the error. 5.2.0
details String The details about the error. 5.2.0
elaboration String The reserved field. Default value: null. 5.2.0
opaque LinkedHashMap The reserved field. Default value: null. 5.2.0
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 5.2.0

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 5.2.0
name String The resource name. 5.2.0
description String Optional. The detailed description of the resource. 5.2.0
scriptContent String The script content. 5.2.0
renderParams String The custom parameters. 5.2.0
platform String The platform 5.2.0
scriptType String The script type. 5.2.0
scriptTimeout Integer The timeout period. 5.2.0
createDate Timestamp The creation time. 5.2.0
lastOpDate Timestamp The last operation time. 5.2.0

SDK Sample

Java SDK

CreateGuestVmScriptAction action = new CreateGuestVmScriptAction();
action.name = "script1";
action.description = "this is a script";
action.scriptContent = "ZWNobyBoZWxsb3dvcmxkCg==";
action.renderParams = "[{"key":"key","value":"value","description":"description"}]";
action.platform = "Linux";
action.scriptType = "Shell";
action.scriptTimeout = 30;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateGuestVmScriptAction.Result res = action.call();

Python SDK

action = CreateGuestVmScriptAction()
action.name = "script1"
action.description = "this is a script"
action.scriptContent = "ZWNobyBoZWxsb3dvcmxkCg=="
action.renderParams = "[{"key":"key","value":"value","description":"description"}]"
action.platform = "Linux"
action.scriptType = "Shell"
action.scriptTimeout = 30
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

DeleteGuestVmScript

API Request

URLs

DELETE zstack/v1/scripts/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/scripts/ed1ef717239e37c29163dcad7576b8d4

Request Parameters

Name Type Location Description Valid Values Starting Version
uuid String url The resource UUID. 5.2.0
deleteMode String body The deletion mode.
  • Permissive
  • Enforcing,Permissive
5.2.0
systemTags List body Optional. The system tags. 5.2.0
userTags List body Optional. The user tags. 5.2.0

API Response

When the API succeeded, an empty JSON structure {} is returned. When the API failed, the returned JSON structure includes an error field. For example,

{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK Sample

Java SDK

DeleteGuestVmScriptAction action = new DeleteGuestVmScriptAction();
action.uuid = "ed1ef717239e37c29163dcad7576b8d4";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteGuestVmScriptAction.Result res = action.call();

Python SDK

action = DeleteGuestVmScriptAction()
action.uuid = "ed1ef717239e37c29163dcad7576b8d4"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

UpdateGuestVmScript

API Request

URLs

PUT zstack/v1/scripts/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "updateGuestVmScript": {
    "name": "test-script",
    "description": "desc",
    "scriptContent": "ls -lh",
    "renderParams": "",
    "platform": "Linux",
    "scriptType": "Shell",
    "scriptTimeout": 60
  },
  "systemTags": [],
  "userTags": []
}

In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateGuestVmScript":{"name":"test-script","description":"desc","scriptContent":"ls -lh","renderParams":"","platform":"Linux","scriptType":"Shell","scriptTimeout":60}}' http://localhost:8080/zstack/v1/scripts/110b774720573fd6aec8ec70b669ffb8/actions

Request Parameters

Name Type Location Description Valid Values Starting Version
uuid String url The resource UUID. 5.2.0
name String body (contained in the updateGuestVmScript structure) Optional. The resource name. 5.2.0
description String body (contained in the updateGuestVmScript structure) Optional. Optional. The detailed description of the resource. 5.2.0
scriptContent String body (contained in the updateGuestVmScript structure) Optional. The script content. 5.2.0
renderParams String body (contained in the updateGuestVmScript structure) Optional. The custom parameters. 5.2.0
platform String body (contained in the updateGuestVmScript structure) Optional. The platform.
  • Windows
  • Linux
5.2.0
scriptType String body (contained in the updateGuestVmScript structure) Optional. The script type.
  • Shell
  • Python
  • Perl
  • Bat
  • Powershell
5.2.0
scriptTimeout Integer body (contained in the updateGuestVmScript structure) Optional. The timeout period. 5.2.0
systemTags List body Optional. The system tags. 5.2.0
userTags List body Optional. The user tags. 5.2.0

API Response

When the API succeeded, an empty JSON structure {} is returned. When the API failed, the returned JSON structure includes an error field. For example,

{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK Sample

Java SDK

UpdateGuestVmScriptAction action = new UpdateGuestVmScriptAction();
action.uuid = "110b774720573fd6aec8ec70b669ffb8";
action.name = "test-script";
action.description = "desc";
action.scriptContent = "ls -lh";
action.renderParams = "";
action.platform = "Linux";
action.scriptType = "Shell";
action.scriptTimeout = 60;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateGuestVmScriptAction.Result res = action.call();

Python SDK

action = UpdateGuestVmScriptAction()
action.uuid = "110b774720573fd6aec8ec70b669ffb8"
action.name = "test-script"
action.description = "desc"
action.scriptContent = "ls -lh"
action.renderParams = ""
action.platform = "Linux"
action.scriptType = "Shell"
action.scriptTimeout = 60
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

ExecuteGuestVmScript

API Request

URLs

PUT zstack/v1/scripts/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "executeGuestVmScript": {
    "vmInstanceUuids": [
      "c9cc2aa748383595b144d9d12ff3abb2"
    ],
    "scriptTimeout": 60
  },
  "systemTags": [],
  "userTags": []
}

In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"executeGuestVmScript":{"vmInstanceUuids":["c9cc2aa748383595b144d9d12ff3abb2"],"scriptTimeout":60}}' http://localhost:8080/zstack/v1/scripts/f9f25df251013694bbbf68bb42b1bde1/actions

Request Parameters

Name Type Location Description Valid Values Starting Version
uuid String url The resource UUID. 5.2.0
vmInstanceUuids List body (contained in the executeGuestVmScript structure) The VM instance UUID. 5.2.0
scriptTimeout Integer body (contained in the executeGuestVmScript structure) Optional. The timeout period. 5.2.0
logPath String body (contained in the executeGuestVmScript structure) Optional. The log path. 5.2.0
systemTags List body (contained in the executeGuestVmScript structure) Optional. The system tags. 5.2.0
userTags List body Optional. The user tags. 5.2.0

API Response

Sample Response

{
  "inventory": {
    "uuid": "e5dc4c630a7138a692e45ad372c5ba17",
    "scriptUuid": "da3f23e42960342b81c8d7f4cbceeb69",
    "recordName": "202308111633_script1",
    "scriptTimeout": 30,
    "status": "Running",
    "executor": "admin",
    "executionCount": 20,
    "version": 1,
    "startTime": "Sep 23, 2024 11:50:03 AM",
    "endTime": "Sep 23, 2024 11:50:03 AM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 5.2.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error 5.2.0
inventory SchedulerTriggerInventory See inventory 5.2.0

#error

Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 5.2.0
description String The brief description of the error. 5.2.0
details String The details about the error. 5.2.0
elaboration String The reserved field. Default value: null. 5.2.0
opaque LinkedHashMap The reserved field. Default value: null. 5.2.0
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 5.2.0

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 5.2.0
scriptUuid String The script UUID. 5.2.0
recordName String The execution record name. 5.2.0
scriptTimeout Integer The timeout period. 5.2.0
status String The execution status. 5.2.0
executor String The executor. 5.2.0
executionCount Integer The execution times. 5.2.0
version Integer The version. 5.2.0
scriptContent String The script content. 5.2.0
startTime Timestamp The start time. 5.2.0
endTime Timestamp The end time. 5.2.0

SDK Sample

Java SDK

ExecuteGuestVmScriptAction action = new ExecuteGuestVmScriptAction();
action.uuid = "f9f25df251013694bbbf68bb42b1bde1";
action.vmInstanceUuids = asList("c9cc2aa748383595b144d9d12ff3abb2");
action.scriptTimeout = 60;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ExecuteGuestVmScriptAction.Result res = action.call();

Python SDK

ExecuteGuestVmScriptAction action = new ExecuteGuestVmScriptAction();
action.uuid = "f9f25df251013694bbbf68bb42b1bde1";
action.vmInstanceUuids = asList("c9cc2aa748383595b144d9d12ff3abb2");
action.scriptTimeout = 60;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ExecuteGuestVmScriptAction.Result res = action.call();

QueryGuestVmScript

API Request

URLs

GET zstack/v1/scripts
GET zstack/v1/scripts/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/scripts?q=uuid={uuid}&q=name='script1'&q=platform='Linux'&q=scriptType='Shell'
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/scripts/a37904a75a75326c87f5db7fe4bac326

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QueryGuestVmScript, and pressing the Tab key.

API Response

Sample Response

{
  "inventories": [
    {
      "name": "script1",
      "description": "this is a script",
      "scriptContent": "ZWNobyBoZWxsb3dvcmxkCg\u003d\u003d",
      "renderParams": "[{\"key\":\"key\",\"value\":\"value\",\"description\":\"description\"}]",
      "platform": "Linux",
      "scriptType": "Shell",
      "scriptTimeout": 30
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 5.2.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error 5.2.0
inventory SchedulerTriggerInventory See inventories 5.2.0

#error

Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 5.2.0
description String The brief description of the error. 5.2.0
details String The details about the error. 5.2.0
elaboration String The reserved field. Default value: null. 5.2.0
opaque LinkedHashMap The reserved field. Default value: null. 5.2.0
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 5.2.0

#inventories

Name Type Description Starting Version
uuid String The resource UUID. 5.2.0
name String The resource name. 5.2.0
description String Optional. The detailed description of the resource. 5.2.0
scriptContent String The script content. 5.2.0
renderParams String The custom parameters. 5.2.0
platform String The platform. 5.2.0
scriptType String The script type. 5.2.0
scriptTimeout Integer The timeout period. 5.2.0
createDate Timestamp The creation time. 5.2.0
lastOpDate Timestamp The last operation time. 5.2.0

SDK Sample

Java SDK

QueryGuestVmScriptAction action = new QueryGuestVmScriptAction();
action.conditions = asList("uuid={uuid}","name='script1'","platform='Linux'","scriptType='Shell'");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryGuestVmScriptAction.Result res = action.call();

Python SDK

action = QueryGuestVmScriptAction()
action.conditions = ["uuid={uuid}","name='script1'","platform='Linux'","scriptType='Shell'"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

QueryGuestVmScriptExecutedRecord

API Request

URLs

GET zstack/v1/scripts/records
GET zstack/v1/scripts/records/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/scripts/records?q=uuid={uuid}&q=scriptUuid={uuid}&q=platform='Linux'&q=scriptType='Shell'&q=executedVmNum=2&q=executedUser='admin'
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/scripts/records/a26b5051d35633b89903fbef2cf01c8a

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QueryGuestVmScriptExecutedRecord, and pressing the Tab key.

API Response

Sample Response

{
  "inventories": [
    {
      "uuid": "459a1b622be53d6ebc830c0682b8016b",
      "scriptUuid": "692066c11aa83d11a5af28ada4fb7057",
      "recordName": "202308111633_script1",
      "scriptTimeout": 30,
      "executor": "admin",
      "executionCount": 20,
      "startTime": "Sep 23, 2024 11:51:30 AM",
      "endTime": "Sep 23, 2024 11:51:30 AM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 5.2.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error 5.2.0
inventories List See inventories 5.2.0

#error

Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 5.2.0
description String The brief description of the error. 5.2.0
details String The details about the error. 5.2.0
elaboration String The reserved field. Default value: null. 5.2.0
opaque LinkedHashMap The reserved field. Default value: null. 5.2.0
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 5.2.0

#inventories

Name Type Description Starting Version
uuid String The resource UUID. 5.2.0
scriptUuid String The script UUID. 5.2.0
recordName String The execution record name. 5.2.0
scriptTimeout Integer The timeout period. 5.2.0
status String The execution status. 5.2.0
executor String The execution. 5.2.0
executionCount Integer The execution times. 5.2.0
version Integer The version. 5.2.0
scriptContent String The script content. 5.2.0
startTime Timestamp The start time. 5.2.0
endTime Timestamp The end time. 5.2.0

SDK Sample

Java SDK

QueryGuestVmScriptExecutedRecordAction action = new QueryGuestVmScriptExecutedRecordAction();
action.conditions = asList("uuid={uuid}","scriptUuid={uuid}","platform='Linux'","scriptType='Shell'","executedVmNum=2","executedUser='admin'");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryGuestVmScriptExecutedRecordAction.Result res = action.call();

Python SDK

action = QueryGuestVmScriptExecutedRecordAction()
action.conditions = ["uuid={uuid}","scriptUuid={uuid}","platform='Linux'","scriptType='Shell'","executedVmNum=2","executedUser='admin'"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

QueryGuestVmScriptExecutedRecordDetail

API Request

URLs

GET zstack/v1/scripts/records/details

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/scripts/records/details?q=recordUuid={ExecuteRecordUuid}&q=vmInstanceUuid={vmInstanceUuid}

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QueryGuestVmScriptExecutedRecordDetail, and pressing the Tab key.

API Response

Sample Response

{
  "inventories": [
    {
      "recordUuid": "ab90a0142aef36fd97c3c759bc7e459d",
      "vmInstanceUuid": "4708f0f6f76e39e882886241761d0c27",
      "status": "Completed",
      "stdout": "helloworld",
      "errCause": "",
      "stderr": "1/0 is not a goodScript",
      "startTime": "Sep 23, 2024 11:53:03 AM",
      "endTime": "Sep 23, 2024 11:53:03 AM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 5.2.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error 5.2.0
inventories List See inventories 5.2.0

#error

Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 5.2.0
description String The brief description of the error. 5.2.0
details String The details about the error. 5.2.0
elaboration String The reserved field. Default value: null. 5.2.0
opaque LinkedHashMap The reserved field. Default value: null. 5.2.0
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 5.2.0

#inventories

Name Type Description Starting Version
recordUuid String The execution record UUID. 5.2.0
vmInstanceUuid String The VM instance UUID. 5.2.0
vmName String The VM instance name. 5.2.0
status String The execution status. 5.2.0
exitCode Integer The exist code. 5.2.0
stdout String The standard output. 5.2.0
errCause String The error cause. 5.2.0
stderr String The error output. 5.2.0
startTime Timestamp The start time. 5.2.0
endTime Timestamp The end time. 5.2.0

SDK Sample

Java SDK

QueryGuestVmScriptExecutedRecordDetailAction action = new QueryGuestVmScriptExecutedRecordDetailAction();
action.conditions = asList("recordUuid={ExecuteRecordUuid}","vmInstanceUuid={vmInstanceUuid}");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryGuestVmScriptExecutedRecordDetailAction.Result res = action.call();

Python SDK

action = QueryGuestVmScriptExecutedRecordDetailAction()
action.conditions = ["recordUuid={ExecuteRecordUuid}","vmInstanceUuid={vmInstanceUuid}"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()