DocsKnowledge BaseAPI Explorer
Documentation›ZCF›ZStack Cloud›Explore more›API ReferenceZCF
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": []
}
Note: 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. 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 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 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
CreateGuestVmScriptAction 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"
CreateGuestVmScriptAction.Result 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返回

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
DeleteGuestVmScriptAction action = DeleteGuestVmScriptAction()
action.uuid = "ed1ef717239e37c29163dcad7576b8d4"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeleteGuestVmScriptAction.Result 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": []
}
Note: 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. 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
UpdateGuestVmScriptAction 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"
UpdateGuestVmScriptAction.Result 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": []
}
Note: 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 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 Sample

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 类型 描述 起始版本
success boolean 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 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
QueryGuestVmScriptAction action = QueryGuestVmScriptAction()
action.conditions = ["uuid={uuid}","name='script1'","platform='Linux'","scriptType='Shell'"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryGuestVmScriptAction.Result 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 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
QueryGuestVmScriptExecutedRecordAction action = QueryGuestVmScriptExecutedRecordAction()
action.conditions = ["uuid={uuid}","scriptUuid={uuid}","platform='Linux'","scriptType='Shell'","executedVmNum=2","executedUser='admin'"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryGuestVmScriptExecutedRecordAction.Result res = action.call()

QueryGuestVmScriptExecutedRecordDetail

API Request

URLs
GET zstack/v1/scripts/records/details
Headers
Authorization: OAuth the-session-uuid

Curl示例

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 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
QueryGuestVmScriptExecutedRecordDetailAction action = QueryGuestVmScriptExecutedRecordDetailAction()
action.conditions = ["recordUuid={ExecuteRecordUuid}","vmInstanceUuid={vmInstanceUuid}"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryGuestVmScriptExecutedRecordDetailAction.Result res = action.call()
PreviousContinuous Data Protection (CDP)NextXML Hook
API Reference | 5.4.12 | ZStack Cloud · ZCF | ZStack Resource Center