Document navigation

Volume Operations

CreateDataVolume

API Request

URLs

POST zstack/v1/volumes/data

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "name": "test-volume",
    "description": "test-data-volume",
    "diskOfferingUuid": "d8732f8e173543ef85a0c2066559ef94",
    "primaryStorageUuid": "ad21b7c7f4ca4d86b348a415347ab1b5",
    "resourceUuid": "e3c9ebe5b5144dd4ba791c5f2959726a"
  },
  "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":"test-volume","description":"test-data-volume","diskOfferingUuid":"d88594833a393e119c6fc5a8aa2ad08f","primaryStorageUuid":"5fe18eef72483c9cbde984a3176fab78","resourceUuid":"52f6075e4d6839fc8a40f569fb7d991e"}}' \
http://localhost:8080/zstack/v1/volumes/data

Request Parameters

Name Type Location Description Optional Value Starting Version
name String body (contained in the params structure) The volume name. 0.6
description String body (contained in the params structure) Optional. The detailed description of the volume. 0.6
diskOfferingUuid String body (contained in the params structure) The disk offering UUID. 0.6
primaryStorageUuid String body (contained in the params structure) Optional. The primary storage UUID. 0.6
resourceUuid String body (contained in the params structure) Optional. The resource UUID. 0.6
tagUuids List body (contained in the params structure) Optional. The tag UUID list. 3.4.0
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6
  • When you create a data volume in ZStack Cloud, you can specify the volume provisioning strategy by adding the volumeProvisioningStrategy option to SystemTags. The SystemTag is passed by using the dataVolumeSystemTags parameter.

    • Format of the volumeProvisioningStrategy option: volumeProvisioningStrategy::ThinProvisioning, volumeProvisioningStrategy::ThickProvisioning

    • Example: volumeProvisioningStrategy::ThinProvisioning, volumeProvisioningStrategy::ThickProvisioning

    • When you create a data volume in ZStack Cloud, you can specify a path for the volume to integrate with a 3rd-party storage paltform. You can set the value of the systemTags parameters to required::installUrl.

      • Format: required::installUrl::{%s}
      • Example: required::installUrl::zbs://poolname

API Response

Sample Response

{
  "inventory": {
    "uuid": "b9d6460b286441099fa9cb3fe5bce9ec",
    "name": "test-volume",
    "primaryStorageUuid": "d7d84bb097da41918ee27eeb3b92d4f4",
    "vmInstanceUuid": "8732b8e254ad4db18a5cad5d04315948",
    "diskOfferingUuid": "7e6d828db0b84d8cb62a44e3d4badc7d",
    "rootImageUuid": "8384b89b03914655b888f9b4f864ab07",
    "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-b9d6460b286441099fa9cb3fe5bce9ec/b9d6460b286441099fa9cb3fe5bce9ec.qcow2",
    "type": "Root",
    "format": "qcow2",
    "size": 1.073741824E11,
    "actualSize": 2.147483648E10,
    "deviceId": 0.0,
    "state": "Enabled",
    "status": "Ready",
    "createDate": "May 11, 2017 1:22:51 PM",
    "lastOpDate": "May 11, 2017 1:22:51 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

CreateDataVolumeAction action = new CreateDataVolumeAction();
action.name = "test-volume";
action.description = "test-data-volume";
action.diskOfferingUuid = "cec2445214fd4e5bb10671b453d25677";
action.primaryStorageUuid = "be3baf0aa09f45ab9ae19c7b6d177ca2";
action.resourceUuid = "f2ebba352d8b43feb434f926f1635ae4";
action.sessionId = "054df264a21d40bbbdf4f292c4993842";
CreateDataVolumeAction.Result res = action.call();

Python SDK

action = CreateDataVolumeAction()
action.name = "test-volume"
action.description = "test-data-volume"
action.diskOfferingUuid = "d9ede14fbc6547808208d40658d1dbbd"
action.primaryStorageUuid = "f6f7257560cd4278b2202157b45d8687"
action.resourceUuid = "3344b25d00ae40c4bfab494d724cb95c"
action.sessionId = "755a549dc19e400ea3b22710c5370c75"
res = action.call()

DeleteDataVolume

API Request

URLs

DELETE zstack/v1/volumes/{uuid}?deleteMode={deleteMode}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 92d7ee354b4e4ed19aea6a7ebb172096" \
-X DELETE http://localhost:8080/zstack/v1/volumes/3102474ff9514720b79ff3719ab6c8e5?deleteMode=Permissive

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
deleteMode String body Optional. The delete mode. Options: Permissive | Enforcing. Default mode: Permissive. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

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

DeleteDataVolumeAction action = new DeleteDataVolumeAction();
action.uuid = "0c9ca7222d914c628d60f5f38b8a5e1e";
action.deleteMode = "Permissive";
action.sessionId = "6b164d54219d4ef8a287fb4937333d54";
DeleteDataVolumeAction.Result res = action.call();

Python SDK

action = DeleteDataVolumeAction()
action.uuid = "ba73b65a66ce433790526c3ee146db3b"
action.deleteMode = "Permissive"
action.sessionId = "fce147bb4ab540448ad4f1798e90f3f9"
res = action.call()

ExpungeDataVolume

API Request

URLs

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

Headers

Authorization: OAuth the-session-uuid

Body

{
  "expungeDataVolume": {},
  "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 '{"expungeDataVolume":{}}' \
http://localhost:8080/zstack/v1/volumes/6dd47cca96f238c899aacd61867db520/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

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

ExpungeDataVolumeAction action = new ExpungeDataVolumeAction();
action.uuid = "347edf4db9e9482a895f7aab3d7f4c26";
action.sessionId = "cc3787426fdd480f8ae6ad656b37b909";
ExpungeDataVolumeAction.Result res = action.call();

Python SDK

action = ExpungeDataVolumeAction()
action.uuid = "2dcb23f228294cab80bcd90e0024dc89"
action.sessionId = "86af19d2bda54fa6bee0204b8e33d4de"
res = action.call()

RecoverDataVolume

API Request

URLs

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

Headers

Authorization: OAuth the-session-uuid

Body

{
  "recoverDataVolume": {},
  "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 '{"recoverDataVolume":{}}' \
http://localhost:8080/zstack/v1/volumes/9f5090fc93ff33e283e0ff3c99fad1e2/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
  "inventory": {
    "uuid": "70820c8ead5144ebaf603b88e63a4d17",
    "name": "test-volume",
    "primaryStorageUuid": "abdb1c3460094359baa202c481633470",
    "vmInstanceUuid": "2f0d6191cc5d452cbbe83284f750c8dd",
    "diskOfferingUuid": "e3526a708a2845f49f2d09404bf0b67d",
    "rootImageUuid": "283433d3b0654d16a63f1add9abad3e6",
    "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-70820c8ead5144ebaf603b88e63a4d17/70820c8ead5144ebaf603b88e63a4d17.qcow2",
    "type": "Root",
    "format": "qcow2",
    "size": 1.073741824E11,
    "actualSize": 2.147483648E10,
    "deviceId": 0.0,
    "state": "Enabled",
    "status": "Ready",
    "createDate": "May 11, 2017 1:22:48 PM",
    "lastOpDate": "May 11, 2017 1:22:48 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

RecoverDataVolumeAction action = new RecoverDataVolumeAction();
action.uuid = "16bc12c40c2242189a9c80a0e908dc21";
action.sessionId = "e444803b7dd047238dca620217929bff";
RecoverDataVolumeAction.Result res = action.call();

Python SDK

action = RecoverDataVolumeAction()
action.uuid = "d5bd95c8ce764a72b77510f17a2eb3a4"
action.sessionId = "ba4360074009447184682979d1c0fd26"
res = action.call()

ChangeVolumeState

API Request

URLs

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

Headers

Authorization: OAuth the-session-uuid

Body

{
  "changeVolumeState": {
    "stateEvent": "enable"
  },
  "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 '{"changeVolumeState":{"stateEvent":"enable"}}' \
http://localhost:8080/zstack/v1/volumes/97fa26ec14d9328c9cfada75e3c0307b/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
stateEvent String body (contained in the changeVolumeState structure) Whether to enable or disable the volume.
  • enable
  • disable
0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
  "inventory": {
    "uuid": "0404b47365d14328b69be6ba29f79e74",
    "name": "test-volume",
    "primaryStorageUuid": "b86a9e49bf0e4c96b13b416de45031b1",
    "vmInstanceUuid": "00e88729e2f64212a7ae19c135de879d",
    "diskOfferingUuid": "9042780280534984ad298f8c6613e162",
    "rootImageUuid": "de9c09f4f3f7409e98ac0dbb6cae76a2",
    "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-0404b47365d14328b69be6ba29f79e74/0404b47365d14328b69be6ba29f79e74.qcow2",
    "type": "Root",
    "format": "qcow2",
    "size": 1.073741824E11,
    "actualSize": 2.147483648E10,
    "deviceId": 0.0,
    "state": "Enabled",
    "status": "Ready",
    "createDate": "Jun 7, 2017 9:21:21 PM",
    "lastOpDate": "Jun 7, 2017 9:21:21 PM"
  }
}
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

ChangeVolumeStateAction action = new ChangeVolumeStateAction();
action.uuid = "67553476ee8643f49ac88304822acd7f";
action.stateEvent = "enable";
action.sessionId = "dc32c1bb220843efb1e3b27b9ca95695";
ChangeVolumeStateAction.Result res = action.call();

Python SDK

action = ChangeVolumeStateAction()
action.uuid = "d18b8dc1ba91461f995e6904bd6a7fc4"
action.stateEvent = "enable"
action.sessionId = "72301e2f3cf94e57adf10f56a08d1d12"
res = action.call()

CreateDataVolumeFromVolumeTemplate

API Request

URLs

POST zstack/v1/volumes/data/from/data-volume-templates/{imageUuid}

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "name": "data-volume-1",
    "description": "dataVolume-from-volume-template",
    "primaryStorageUuid": "faf07bfbec0944499d566345f0de383e",
    "hostUuid": "c0411ea2b3d949fab31239d200a83faf"
  },
  "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":"data-volume-1","description":"dataVolume-from-volume-template","primaryStorageUuid":"849de664b4db321f8eeef65a1aa757c7","hostUuid":"0de619ae30373e97acc7bb4b42ca87a1"}}' \
http://localhost:8080/zstack/v1/volumes/data/from/data-volume-templates/285f4a49e7403d2dad9545b42c33b837

Request Parameters

Name Type Location Description Optional Value Starting Version
imageUuid String url The image UUID. 0.6
name String body (contained in the params structure) The volume name. 0.6
description String body (contained in the params structure) Optional. The detailed description of the volume. 0.6
primaryStorageUuid String body (contained in the params structure) The primary storage UUID. 0.6
hostUuid String body (contained in the params structure) Optional. The host UUID. 0.6
resourceUuid String body (contained in the params structure) Optional. The resource UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6
  • When you create a volume from an image in ZStack Cloud, you can create a shared volume by adding the shareable option to SystemTags. The SystemTag is passed by using the shareable parameter. Note that you will create a shared volume if you add this SystemTag. If you do not add this SystemTag, you will create a normal volume.

API Response

Sample Response

{
  "inventory": {
    "uuid": "289aaa0f33004cb6adba798bf9c8273b",
    "name": "test-volume",
    "primaryStorageUuid": "5697632ba45c46408044aefbab433945",
    "vmInstanceUuid": "c0dcccf2ca8945e1b96b446f7bdba30f",
    "diskOfferingUuid": "5909df7b2c3f4751b0491f53533c505f",
    "rootImageUuid": "a8c3608b85a0450d99b9b5339ee4dcec",
    "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-289aaa0f33004cb6adba798bf9c8273b/289aaa0f33004cb6adba798bf9c8273b.qcow2",
    "type": "Root",
    "format": "qcow2",
    "size": 1.073741824E11,
    "actualSize": 2.147483648E10,
    "deviceId": 0.0,
    "state": "Enabled",
    "status": "Ready",
    "createDate": "Jun 7, 2017 9:21:14 PM",
    "lastOpDate": "Jun 7, 2017 9:21:14 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

CreateDataVolumeFromVolumeTemplateAction action = new CreateDataVolumeFromVolumeTemplateAction();
action.imageUuid = "f0f991b7883b49869e03b0e9d42a5ce9";
action.name = "data-volume-1";
action.description = "dataVolume-from-volume-template";
action.primaryStorageUuid = "0b325fbe797f413290c6015f49160caf";
action.hostUuid = "2c23c98e197745359455268a6414f6cc";
action.sessionId = "351589a73b6247ee817acfc89609a396";
CreateDataVolumeFromVolumeTemplateAction.Result res = action.call();

Python SDK

action = CreateDataVolumeFromVolumeTemplateAction()
action.imageUuid = "eeea8f11bf174bf39ffb341c96e93765"
action.name = "data-volume-1"
action.description = "dataVolume-from-volume-template"
action.primaryStorageUuid = "f1bf0bc060474a9484a822a7b9ea3bec"
action.hostUuid = "883173c367ba42e49434429012376f36"
action.sessionId = "7c098bc9e7e24c1ca81ff90d355b2fca"
res = action.call()

CreateDataVolumeFromVolumeSnapshot

API Request

URLs

POST zstack/v1/volumes/data/from/volume-snapshots/{volumeSnapshotUuid}

Headers

Authorization: OAuth the-session-uuid

Body

{
"params": {
"name": "DataVolume-1",
"description": "dataVolume-from-snapshot",
"primaryStorageUuid": "4102177b842946a4adf6ba0008710ed6"
  },
"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":"DataVolume-1","description":"dataVolume-from-snapshot","primaryStorageUuid":"b2237f228a343d0cb8b20b5b64663314"}}' \
http://localhost:8080/zstack/v1/volumes/data/from/volume-snapshots/192da9c7d6493a5d9a35d2df2dcc82b0

Request Parameters

Name Type Location Description Optional Value Starting Version
name String body (contained in the params structure) The volume name. 0.6
description String body (contained in the params structure) Optional. The detailed description of the volume. 0.6
volumeSnapshotUuid String url The volume snapshot UUID. 0.6
primaryStorageUuid String body (contained in the params structure) Optional. The primary storage UUID. 0.6
resourceUuid String body (contained in the params structure) Optional. The resource UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
"inventory": {
"uuid": "0f7ad281abd34b4d94df149756daa45d",
"name": "test-volume",
"primaryStorageUuid": "e39d9b37365141f8a126e53555a57f2d",
"vmInstanceUuid": "b03e00f24ef842cb9c31fd0f8ab3f38b",
"diskOfferingUuid": "cc97edd1f7aa4cc39656e73490863b4d",
"rootImageUuid": "d15926cb82a54a26b098e19a982f2f6b",
"installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-0f7ad281abd34b4d94df149756daa45d/0f7ad281abd34b4d94df149756daa45d.qcow2",
"type": "Root",
"format": "qcow2",
"size": 1.073741824E11,
"actualSize": 2.147483648E10,
"deviceId": 0.0,
"state": "Enabled",
"status": "Ready",
"createDate": "Jun 7, 2017 9:21:17 PM",
"lastOpDate": "Jun 7, 2017 9:21:17 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

CreateDataVolumeFromVolumeSnapshotAction action = new CreateDataVolumeFromVolumeSnapshotAction();
action.name = "DataVolume-1";
action.description = "dataVolume-from-snapshot";
action.volumeSnapshotUuid = "179e11d25aea49ce81ba612108451a8f";
action.primaryStorageUuid = "4d39340d1a9d4bd7a834493af50020ab";
action.sessionId = "d28727a6c2fc44fe9673c4b67da615b5";
CreateDataVolumeFromVolumeSnapshotAction.Result res = action.call();

Python SDK

action = CreateDataVolumeFromVolumeSnapshotAction()
action.name = "DataVolume-1"
action.description = "dataVolume-from-snapshot"
action.volumeSnapshotUuid = "79200ff743314dd1b1e46bdf9b26f72f"
action.primaryStorageUuid = "920b891ae2b84a53a802a0ddc37a7d0c"
action.sessionId = "c4c003ce6d664a0db244e5587b6ec7d2"
res = action.call()

QueryVolume

API Request

URLs

GET zstack/v1/volumes
GET zstack/v1/volumes/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 37d226de07584043ab547642e4a9d14c" \
-X GET http://localhost:8080/zstack/v1/volumes
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 97dc2b0fd5264c6bb2ff9e693791d492" \
-X GET http://localhost:8080/zstack/v1/volumes/ca621f583bac4b979348fce553525146

Queryable Fields

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

API Response

Sample Response

{
  "inventories": [
    {
      "uuid": "b289ce8ac3874e88b4d4ce5cc4fc4c6e",
      "name": "test-volume",
      "primaryStorageUuid": "8749501379364105ba214227fc79578f",
      "vmInstanceUuid": "4cf370ed63bb43f99d88755b87f722c1",
      "diskOfferingUuid": "9e4d1d1a0e1a483da86eac0ab99c96ce",
      "rootImageUuid": "0116e6093d80474693ddac2e670122e4",
      "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-b289ce8ac3874e88b4d4ce5cc4fc4c6e/b289ce8ac3874e88b4d4ce5cc4fc4c6e.qcow2",
      "type": "Root",
      "format": "qcow2",
      "size": 1.073741824E11,
      "actualSize": 2.147483648E10,
      "deviceId": 0.0,
      "state": "Enabled",
      "status": "Ready",
      "createDate": "Jun 7, 2017 9:20:25 PM",
      "lastOpDate": "Jun 7, 2017 9:20:25 PM"
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventories

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

QueryVolumeAction action = new QueryVolumeAction();
action.conditions = asList();
action.sessionId = "a6c77f7c77dd425e98f3089363725c06";
QueryVolumeAction.Result res = action.call();

Python SDK

action = QueryVolumeAction()
action.conditions = []
action.sessionId = "8e464fe1562b4fcc80b02596f455e6a8"
res = action.call()

GetVolumeFormat

API Request

URLs

GET zstack/v1/volumes/formats

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 91c86306f8fd45ba9af34c549baa8052" \
-X GET http://localhost:8080/zstack/v1/volumes/formats

Request Parameters

Name Type Location Description Optional Value Starting Version
systemTags List query Optional. The system tags. 0.6
userTags List query Optional. The user tags. 0.6

API Response

Sample Response

{
  "formats": [
    {
      "format": "iso",
      "masterHypervisorType": "KVM",
      "supportingHypervisorTypes": [
        "ESX",
        "KVM"
      ]
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
formats List See formats. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#formats

Name Type Description Starting Version
format String The volume format. 0.6
masterHypervisorType String The default hypervisor type. 0.6
supportingHypervisorTypes List The list of supported hypervisor types. 0.6

SDK Sample

Java SDK

GetVolumeFormatAction action = new GetVolumeFormatAction();
action.sessionId = "6fda4c2362614bec9ec42a2eb8f4a4b0";
GetVolumeFormatAction.Result res = action.call();

Python SDK

action = GetVolumeFormatAction()
action.sessionId = "a5cd7896806e4717a609899d22a90594"
res = action.call()

GetVolumeCapabilities

API Request

URLs

GET zstack/v1/volumes/{uuid}/capabilities

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 202bde8c03d94942b052da20b48a2301" \
-X GET http://localhost:8080/zstack/v1/volumes/96646576bd1c44ac845810374ca41c58/capabilities

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
systemTags List query Optional. The system tags. 0.6
userTags List query Optional. The user tags. 0.6

API Response

Sample Response

{
"capabilities": {
"MigrationToOtherPrimaryStorage": true,
"MigrationInCurrentPrimaryStorage": true
  }
}
Name Type Description Starting Version
capabilities Map The capabilities supported by the volume. 0.6
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

SDK Sample

Java SDK

GetVolumeCapabilitiesAction action = new GetVolumeCapabilitiesAction();
action.uuid = "23c96138a1874aeebcd082be9b21f905";
action.sessionId = "b8980f940bad4558947437d211262e2f";
GetVolumeCapabilitiesAction.Result res = action.call();

Python SDK

action = GetVolumeCapabilitiesAction()
action.uuid = "b645da1aa3ed4771b0860d01144929b6"
action.sessionId = "277436d4a8f54942a496ca64b2d7f3f0"
res = action.call()

SyncVolumeSize

API Request

URLs

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

Headers

Authorization: OAuth the-session-uuid

Body

{
"syncVolumeSize": {},
"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 '{"syncVolumeSize":{}}' \
http://localhost:8080/zstack/v1/volumes/017a6c821b3433c594285712cd7e69f4/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
"inventory": {
"uuid": "d0cd0413d1b241fca524322b56f4687d",
"name": "test-volume",
"primaryStorageUuid": "8dea01cf7afb4d7bb89ea432fc15258e",
"vmInstanceUuid": "f93fa5fea43f42449409c35914c47732",
"diskOfferingUuid": "a2915a283c744389a6bae0d42b203e18",
"rootImageUuid": "da66399cb83048b0b87fa113ddcd3755",
"installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-d0cd0413d1b241fca524322b56f4687d/d0cd0413d1b241fca524322b56f4687d.qcow2",
"type": "Root",
"format": "qcow2",
"size": 1.073741824E11,
"actualSize": 2.147483648E10,
"deviceId": 0.0,
"state": "Enabled",
"status": "Ready",
"createDate": "Jun 7, 2017 9:21:08 PM",
"lastOpDate": "Jun 7, 2017 9:21:08 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

SyncVolumeSizeAction action = new SyncVolumeSizeAction();
action.uuid = "793ac8595fbc44618934ccf474c9c82b";
action.sessionId = "eab6cd1a880749ae818f6402c0c72af5";
SyncVolumeSizeAction.Result res = action.call();

Python SDK

action = SyncVolumeSizeAction()
action.uuid = "e269f644c3324709a2254d84a6f86457"
action.sessionId = "48363f37efe6484abfff927059cedae3"
res = action.call()

BatchSyncVolumeSize

API Request

URLs

POST zstack/v1/volumes/batch-sync-volumes

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST http://localhost:8080/zstack/v1/volumes/batch-sync-volumes

Request Parameters

Name Type Location Description Valid Value Starting Version
clusterUuid String body The cluster UUID. 4.5.3
systemTags (可选) List body The system tag. 4.5.3
userTags (可选) List body The user tag. 4.5.3

API Response

Sample Response

{
    “failCount”: 3,
    "successCount": 3
}
Name Type Description Starting Version
failCount int The failure count. 4.5.3
successCount int The success count. 4.5.3
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error 4.5.3

#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. 4.5.3
description String The brief description of the error. 4.5.3
details String The details about the error. 4.5.3
elaboration String The reserved field. Default value: null. 4.5.3
opaque LinkedHashMap The reserved field. Default value: null. 4.5.3
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 4.5.3

SDK Sample

Java SDK

BatchSyncVolumeSizeAction action = new BatchSyncVolumeSizeAction();
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
action.clusterUuid = "5hs8kc3m867kg4x46k8l04dv461vps9e";
BatchSyncVolumeSizeAction.Result res = action.call();

Python SDK

action = BatchSyncVolumeSizeAction()
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
action.clusterUuid = "5hs8kc3m867kg4x46k8l04dv461vps9e"
res = action.call()

ResizeRootVolume

API Request

URLs

PUT zstack/v1/volumes/resize/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "resizeRootVolume": {
    "size": 1.0E7
  },
  "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 '{"resizeRootVolume":{"size":1.0E7}}' \
http://localhost:8080/zstack/v1/volumes/resize/16a052d270983392bd2824c06a44253f/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 2.2
size long body (contained in the resizeRootVolume structure) The new size. 2.2
systemTags List body Optional. The system tags. 2.2
userTags List body Optional. The user tags. 2.2

API Response

Sample Response

{
  "inventory": {
    "uuid": "f6ace13363934d2d9a2dc29c53a83bc4",
    "name": "test-volume",
    "primaryStorageUuid": "a849a9d7cf864b95a4a1223db572a73c",
    "vmInstanceUuid": "d05fda61030645c293688fd2e67b6881",
    "diskOfferingUuid": "f31553ca15f4495cbd7f3954426f9f1f",
    "rootImageUuid": "5ef070a672ea48e583c8f4fd6441a58c",
    "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-f6ace13363934d2d9a2dc29c53a83bc4/f6ace13363934d2d9a2dc29c53a83bc4.qcow2",
    "type": "Root",
    "format": "qcow2",
    "size": 1.073741824E11,
    "actualSize": 2.147483648E10,
    "deviceId": 0.0,
    "state": "Enabled",
    "status": "Ready",
    "createDate": "Sep 22, 2017 12:24:45 PM",
    "lastOpDate": "Sep 22, 2017 12:24:45 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 2.2
inventory VolumeInventory See inventory. 2.2

#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. 2.2
description String The brief description of the error. 2.2
details String The details about the error. 2.2
elaboration String The reserved field. Default value: null. 2.2
opaque LinkedHashMap The reserved field. Default value: null. 2.2
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 2.2

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 2.2
name String The resource name. 2.2
description String The detailed description of the resource. 2.2
primaryStorageUuid String The primary storage UUID. 2.2
vmInstanceUuid String The VM instance UUID. 2.2
diskOfferingUuid String The disk offering UUID. 2.2
rootImageUuid String The root image UUID. 2.2
installPath String The installation path. 2.2
type String The resource type. 2.2
format String The format. 2.2
size Long The size. 2.2
actualSize Long The actual size. 2.2
deviceId Integer The device ID. 2.2
state String The resource state. 2.2
status String The resource status. 2.2
createDate Timestamp The creation date. 2.2
lastOpDate Timestamp The last operation date. 2.2
isShareable Boolean Whether the resource is shareable. 2.2

SDK Sample

Java SDK

ResizeRootVolumeAction action = new ResizeRootVolumeAction();
action.uuid = "d39ece16a6e74d1582541f256a6bc6fe";
action.size = 1.0E7;
action.sessionId = "cae45c7f96264807afaf6337ee40c236";
ResizeRootVolumeAction.Result res = action.call();

Python SDK

action = ResizeRootVolumeAction()
action.uuid = "9101b352108041baad9acfadcd38aa22"
action.size = 1.0E7
action.sessionId = "dfa1c04aa43f48118cae6ccaabd8bc5c"
res = action.call()

ResizeDataVolume

API Request

URLs

PUT zstack/v1/volumes/data/resize/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "resizeDataVolume": {
    "size": 1.0E7
  },
  "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 '{"resizeDataVolume":{"size":1.0E7}}' \
http://localhost:8080/zstack/v1/volumes/data/resize/6c2a13e8d7fa3ef99091bc6a445d4e9c/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 2.2
size long body (contained in the resizeDataVolume structure) The new size. 2.2
systemTags List body Optional. The system tags. 2.2
userTags List body Optional. The user tags. 2.2

API Response

Sample Response

{
  "inventory": {
    "uuid": "f17a01d17e4d39bdb17d227a1df97e3a",
    "name": "test-volume",
    "primaryStorageUuid": "83245aa16d02322785f84450d1a05441",
    "vmInstanceUuid": "14ca01538ffa3ab49aad3dd60c4c41b4",
    "diskOfferingUuid": "9dd65df23d453f25855a2c2b2f9f778b",
    "rootImageUuid": "825ca3ebcb053abf843ed8b2731ec4b9",
    "installPath": "/Cloud_ps/dataVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-f17a01d17e4d39bdb17d227a1df97e3a/f17a01d17e4d39bdb17d227a1df97e3a.qcow2",
    "type": "Root",
    "format": "qcow2",
    "size": 1.073741824E11,
    "actualSize": 2.147483648E10,
    "deviceId": 0.0,
    "state": "Enabled",
    "status": "Ready",
    "createDate": "Nov 20, 2017 1:50:58 PM",
    "lastOpDate": "Nov 20, 2017 1:50:58 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 2.2
inventory VolumeInventory See inventory. 2.2

#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. 2.2
description String The brief description of the error. 2.2
details String The details about the error. 2.2
elaboration String The reserved field. Default value: null. 2.2
opaque LinkedHashMap The reserved field. Default value: null. 2.2
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 2.2

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 2.2
name String The resource name. 2.2
description String The detailed description of the resource. 2.2
primaryStorageUuid String The primary storage UUID. 2.2
vmInstanceUuid String The VM instance UUID. 2.2
diskOfferingUuid String The disk offering UUID. 2.2
rootImageUuid String The root image UUID. 2.2
installPath String The installation path. 2.2
type String The resource type. 2.2
format String The format. 2.2
size Long The size. 2.2
actualSize Long The actual size. 2.2
deviceId Integer The device ID. 2.2
state String The resource state. 2.2
status String The resource status. 2.2
createDate Timestamp The creation date. 2.2
lastOpDate Timestamp The last operation date. 2.2
isShareable Boolean Whether the resource is shareable. 2.2

SDK Sample

Java SDK

ResizeDataVolumeAction action = new ResizeDataVolumeAction();
action.uuid = "6c2a13e8d7fa3ef99091bc6a445d4e9c";
action.size = 1.0E7;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ResizeDataVolumeAction.Result res = action.call();

Python SDK

action = ResizeDataVolumeAction()
action.uuid = "6c2a13e8d7fa3ef99091bc6a445d4e9c"
action.size = 1.0E7
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

UpdateVolume

API Request

URLs

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

Headers

Authorization: OAuth the-session-uuid

Body

{
"updateVolume": {
"name": "volume-1",
"description": "data-volume"
  },
"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 '{"updateVolume":{"name":"volume-1","description":"data-volume"}}' \
http://localhost:8080/zstack/v1/volumes/f1eddfdb19ad3a0881b0be863901ff09/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
name String body (contained in the updateVolume structure) Optional. The volume name. 0.6
description String body (contained in the updateVolume structure) Optional. The detailed description of the volume. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
"inventory": {
"uuid": "31ae1f16a1774ead98a84432e08e438c",
"name": "test-volume",
"primaryStorageUuid": "dafbef4c002b4bf49ac63a2e0cf8c616",
"vmInstanceUuid": "417e81050f424bf88b515c2bbc3e9d24",
"diskOfferingUuid": "80b0f3edaa2f4c0284240d16aebf8da4",
"rootImageUuid": "edb9e2aa51c5489db12a7073daa6c878",
"installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-31ae1f16a1774ead98a84432e08e438c/31ae1f16a1774ead98a84432e08e438c.qcow2",
"type": "Root",
"format": "qcow2",
"size": 1.073741824E11,
"actualSize": 2.147483648E10,
"deviceId": 0.0,
"state": "Enabled",
"status": "Ready",
"createDate": "Jun 7, 2017 9:20:28 PM",
"lastOpDate": "Jun 7, 2017 9:20:28 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

UpdateVolumeAction action = new UpdateVolumeAction();
action.uuid = "cebcb28540d9474ebf0be79fc9c7efe4";
action.name = "volume-1";
action.description = "data-volume";
action.sessionId = "e5e68d56602441d187139189dce441f7";
UpdateVolumeAction.Result res = action.call();

Python SDK

action = UpdateVolumeAction()
action.uuid = "d429120df78e4b7290fd4f50adfa2f2e"
action.name = "volume-1"
action.description = "data-volume"
action.sessionId = "31a278c3b4024dc48b952196c0ae34a0"
res = action.call()

SetVolumeQoS

API Request

URLs

POST zstack/v1/volumes/{uuid}/QoS

Headers

Authorization: OAuth the-session-uuid

Body

{
  "setVolumeQos": {
    "totalBandwidth": 10000.0,
    "totalIOPS": 1000.0
  },
  "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 '{"setVolumeQos":{"totalBandwidth":10000.0,"totalIOPS":1000.0}}' http://localhost:8080/zstack/v1/volumes/384f99ce0b7a307685856b23f75c5167/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
volumeBandwidth Long body (contained in the params structure) The volume bandwidth. 0.6
mode String body (contained in the setVolumeQos structure) Optional. The mode.
  • total
  • read
  • write
3.1.0
readBandwidth Long body (contained in the setVolumeQos structure) 4.4.0
writeBandwidth Long body (contained in the setVolumeQos structure) 4.4.0
totalBandwidth Long body (contained in the setVolumeQos structure) 4.4.0
readIOPS Long body (contained in the setVolumeQos structure) 4.4.0
writeIOPS Long body (contained in the setVolumeQos structure) 4.4.0
totalIOPS Long body (contained in the setVolumeQos structure) Optional. 4.4.0
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6
  • ZStack Cloud allows you to set the QoS read bandwidth for a volume by adding the volumeReadBandwidth option to SystemTags.

    • Format of the volumeReadBandwidth option: volumeReadBandwidth::xxx. Here, xxx is the read bandwidth.
    • Example: volumeReadBandwidth::20971520
  • ZStack Cloud allows you to set the QoS write bandwidth for a volume by adding the volumeWriteBandwidth option to SystemTags.

    • Format of the volumeWriteBandwidth option: volumeWriteBandwidth::xxx. Here, xxx is the write bandwidth.
    • Example: vvolumeWriteBandwidth::20971520

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

SetVolumeQoSAction action = new SetVolumeQoSAction();
action.uuid = "ac4fdd09c5884f58a5b38b805b5ddb78";
action.mode = "total";
action.volumeBandwidth = 10000.0;
action.sessionId = "aeec637635af476b94356f4f8fe714be";
SetVolumeQoSAction.Result res = action.call();

Python SDK

action = SetVolumeQoSAction()
action.uuid = "26d462d809b54d52b2814bbf1302f305"
action.mode = "total"
action.volumeBandwidth = 10000.0
action.sessionId = "eb791fa4bdfb4be28ff279651cde78f9"
res = action.call()

GetVolumeQoS

API Request

URLs

GET zstack/v1/volumes/{uuid}/qos

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/volumes/66adb238cf70369089b3da287e6633bb/qos

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
forceSync Boolean body Optional. Whether to synchronize the data on the host. 3.3.0
systemTags List query Optional. 0.6
userTags List query Optional. 0.6
  • ZStack Cloud allows you to obtain the QoS read bandwidth of a volume by adding the volumeReadBandwidth option to SystemTags.

    • Format of the volumeReadBandwidth option: volumeReadBandwidth::xxx. Here, xxx is the read bandwidth.
    • Example: volumeReadBandwidth::20971520
  • ZStack Cloud allows you to obtain the QoS write bandwidth of a volume by adding the volumeWriteBandwidth option to SystemTags.

    • Format of the volumeWriteBandwidth option: volumeWriteBandwidth::xxx. Here, xxx is the write bandwidth.
    • Example: vvolumeWriteBandwidth::20971520

API Response

Sample Response

{
  "volumeUuid": "1dc9ff4cedae33eb84651468db5734ae",
  "volumeBandwidth": 100000.0,
  "volumeBandwidthRead": -1.0,
  "volumeBandwidthWrite": -1.0,
  "iopsTotal": -1.0,
  "iopsRead": 10000.0,
  "iopsWrite": 10000.0,
  "volumeBandwidthUpthreshold": 200000.0,
  "volumeBandwidthReadUpthreshold": -1.0,
  "volumeBandwidthWriteUpthreshold": -1.0,
  "iopsTotalUpthreshold": -1.0,
  "iopsReadUpthreshold": 20000.0,
  "iopsWriteUpthreshold": 15000.0
}
Name Type Description Starting Version
volumeUuid String The volume UUID. 3.10
volumeBandwidth long The volume bandwidth. Default value: -1. 0.6
volumeBandwidthRead long The volume read bandwidth. Default value: -1. 3.10
volumeBandwidthWrite long The volume write bandwidth. Default value: -1. 3.10
volumeBandwidthUpthreshold long The volume bandwidth. Default value: -1. 3.10
volumeBandwidthReadUpthreshold long The maximum volume read bandwidth. Default value: -1. 3.10
volumeBandwidthWriteUpthreshold long The maximum volume write bandwidth. Default value: -1. 3.10
iopsTotalUpthreshold long The volume IOPS. Default value: -1. This value indicates that the volume IOPS is unlimited. 4.4.0
iopsReadUpthreshold long The read IOPS of a volume. Default value: -1. This value indicates that the read IOPS is unlimited. 4.4.0
iopsWriteUpthreshold long The write IOPS of a volume. Default value: -1. This value indicates that the write IOPS is unlimited. 4.4.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

SDK Sample

Java SDK

GetVolumeQosAction action = new GetVolumeQosAction();
action.uuid = "66adb238cf70369089b3da287e6633bb";
action.forceSync = false;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetVolumeQosAction.Result res = action.call();

Python SDK

action = GetVolumeQosAction()
action.uuid = "66adb238cf70369089b3da287e6633bb"
action.forceSync = false
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

DeleteVolumeQos

API Request

URLs

DELETE zstack/v1/volumes/{uuid}/qos

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/volumes/f468b0dd61c538b0bbe85327f7deadcd/qos?

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
mode String body Optional. The mode.
  • total
  • read
  • write
  • all
  • overwrite
4.4.0
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6
  • ZStack Cloud allows you to delete the QoS read bandwidth of a volume by adding the volumeReadBandwidth option to SystemTags.

    • Format of the volumeReadBandwidth option: volumeReadBandwidth::xxx. Here, xxx is the read bandwidth.
    • Example: volumeReadBandwidth::20971520
  • ZStack Cloud allows you to delete the QoS read bandwidth of a volume by adding the volumeWriteBandwidth option to SystemTags.

    • Format of the volumeWriteBandwidth option: volumeWriteBandwidth::xxx. Here, xxx is the write bandwidth.
    • Example: vvolumeWriteBandwidth::20971520

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

DeleteVolumeQosAction action = new DeleteVolumeQosAction();
action.uuid = "f468b0dd61c538b0bbe85327f7deadcd";
action.mode = "total";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteVolumeQosAction.Result res = action.call();

Python SDK

action = DeleteVolumeQosAction()
action.uuid = "f468b0dd61c538b0bbe85327f7deadcd"
action.mode = "total"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

GetVolumeIoThreadPin

API Request

URLs

GET zstack/v1/volumes/{uuid}/io-thread-pin

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/volumes/93150452524b3b548cc597c8405fda21/io-thread-pin

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 4.7.0
systemTags List query Optional. The system tags. 4.7.0
userTags List query Optional. The user tags. 4.7.0

API Response

Sample Response

{
  "volumeUuid": "a8ba696310303ccebb08e128759ecbf8",
  "pin": "3-6",
  "ioThreadId": "1"
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.7.0
volumeUuid String The volume UUID. 4.7.0
ioThreadId String The IO thread id. 4.7.0
pin String The CPU pinning range. 4.7.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.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. 4.7.0
description String The brief description of the error. 4.7.0
details String The details about the error. 4.7.0
elaboration String The reserved field. Default value: null. 4.7.0
opaque LinkedHashMap The reserved field. Default value: null. 4.7.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. 4.7.0

SDK Sample

Java SDK

GetVolumeIoThreadPinAction action = new GetVolumeIoThreadPinAction();
action.uuid = "93150452524b3b548cc597c8405fda21";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetVolumeIoThreadPinAction.Result res = action.call();

Python SDK

action = GetVolumeIoThreadPinAction()
action.uuid = "93150452524b3b548cc597c8405fda21"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

SetVolumeIoThreadPin

API Request

URLs

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

Headers

Authorization: OAuth the-session-uuid

Body

{
  "setVolumeIoThreadPin": {
    "vmUuid": "f225b0e5d5ea3c7bbc3a99fd8fc8315e",
    "pin": "3-6",
    "ioThreadId": 1
  },
  "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 '{"setVolumeIoThreadPin":{"vmUuid":"f225b0e5d5ea3c7bbc3a99fd8fc8315e","pin":"3-6","ioThreadId":1}}' http://localhost:8080/zstack/v1/volumes/30603ac1c77f3e8b9358cd57dec56a54/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 4.7.0
vmUuid String body (contained in the setVolumeIoThreadPin structure) The VM instance UUID. 4.7.0
pin String body (contained in the setVolumeIoThreadPin structure) The CPU pinning range. 4.7.0
ioThreadId int body (contained in the setVolumeIoThreadPin structure) The IO thread id. 4.7.0
systemTags List body Optional. The system tags. 4.7.0
userTags List body Optional. The user tags. 4.7.0

API Response

Sample Response

{
  "volumeUuid": "1a4f1e7372283246bd5400dc452d2937",
  "pin": "3-6",
  "ioThreadId": 1
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.7.0
volumeUuid String The volume UUID. 4.7.0
ioThreadId Integer The IO thread id. 4.7.0
pin String The CPU pinning range. 4.7.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.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. 4.7.0
description String The brief description of the error. 4.7.0
details String The details about the error. 4.7.0
elaboration String The reserved field. Default value: null. 4.7.0
opaque LinkedHashMap The reserved field. Default value: null. 4.7.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. 4.7.0

SDK Sample

Java SDK

SetVolumeIoThreadPinAction action = new SetVolumeIoThreadPinAction();
action.uuid = "30603ac1c77f3e8b9358cd57dec56a54";
action.vmUuid = "f225b0e5d5ea3c7bbc3a99fd8fc8315e";
action.pin = "3-6";
action.ioThreadId = 1;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
SetVolumeIoThreadPinAction.Result res = action.call();

Python SDK

action = SetVolumeIoThreadPinAction()
action.uuid = "30603ac1c77f3e8b9358cd57dec56a54"
action.vmUuid = "f225b0e5d5ea3c7bbc3a99fd8fc8315e"
action.pin = "3-6"
action.ioThreadId = 1
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

GetDataVolumeAttachableVm

API Request

URLs

GET zstack/v1/volumes/{volumeUuid}/candidate-vm-instances

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 2da4ab715edf474ea45825d21c7ce711" \
-X GET http://localhost:8080/zstack/v1/volumes/2b419a8547074e098d0da9ee92935344/candidate-vm-instances

Request Parameters

Name Type Location Description Optional Value Starting Version
volumeUuid String url The volume UUID. 0.6
systemTags List query Optional. The system tags. 0.6
userTags List query Optional. The user tags. 0.6

API Response

Sample Response

{
"inventories": [
    {
"uuid": "237e1c010bed43288f2f158cd3b1e218",
"name": "Test-VM",
"description": "web server VM",
"zoneUuid": "4537a02725fd49adb8815887fe95e38d",
"clusterUuid": "fe33a5b88c054e94b13a8914086e50f3",
"imageUuid": "5bed7e1839c44b4289f0eab2af35681d",
"hostUuid": "0242f2a240564fd5bdf84bf651740129",
"lastHostUuid": "649a873867a247b1bed6b96b61b2e19a",
"instanceOfferingUuid": "1edf7842c7f34e00b48d3899d14a1ff2",
"rootVolumeUuid": "2adc2350eb16479aa7b9dfdb9bc82d6a",
"platform": "Linux",
"defaultL3NetworkUuid": "7119ed6d54ca4624aa8e362d07b03a35",
"type": "UserVm",
"hypervisorType": "KVM",
"memorySize": 8.589934592E9,
"cpuNum": 1.0,
"allocatorStrategy": "LastHostPreferredAllocatorStrategy",
"createDate": "Jun 7, 2017 9:20:15 PM",
"lastOpDate": "Jun 7, 2017 9:20:15 PM",
"state": "Running",
"vmNics": [
        {
"uuid": "f967eee9618c4ee3a8cda348b333ba21",
"vmInstanceUuid": "237e1c010bed43288f2f158cd3b1e218",
"usedIpUuid": "ead7ed9822e64f18b2f926cb71e0b9da",
"l3NetworkUuid": "7119ed6d54ca4624aa8e362d07b03a35",
"ip": "192.168.1.10",
"mac": "00:0c:29:bd:99:fc",
"netmask": "255.255.255.0",
"gateway": "192.168.1.1",
"deviceId": 0.0,
"createDate": "Jun 7, 2017 9:20:15 PM",
"lastOpDate": "Jun 7, 2017 9:20:15 PM"
        }
      ],
"allVolumes": [
        {
"uuid": "2adc2350eb16479aa7b9dfdb9bc82d6a",
"name": "Root-Volume-For-VM-237e1c010bed43288f2f158cd3b1e218",
"primaryStorageUuid": "bdffc9aef10d48e4b028d26b09df2e35",
"vmInstanceUuid": "237e1c010bed43288f2f158cd3b1e218",
"diskOfferingUuid": "0319566f3f7647dbb3a8e642b05f4bfe",
"rootImageUuid": "5bed7e1839c44b4289f0eab2af35681d",
"installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-2adc2350eb16479aa7b9dfdb9bc82d6a/2adc2350eb16479aa7b9dfdb9bc82d6a.qcow2",
"type": "Root",
"format": "qcow2",
"size": 1.073741824E11,
"actualSize": 2.147483648E10,
"deviceId": 0.0,
"state": "Enabled",
"status": "Ready",
"createDate": "Jun 7, 2017 9:20:15 PM",
"lastOpDate": "Jun 7, 2017 9:20:15 PM"
        }
      ]
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventories

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
zoneUuid String The zone UUID. 0.6
clusterUuid String The cluster UUID. 0.6
imageUuid String The image UUID. 0.6
hostUuid String The host UUID. 0.6
lastHostUuid String The last host UUID. 0.6
instanceOfferingUuid String The instance offering UUID. 0.6
rootVolumeUuid String The root volume UUID. 0.6
platform String The platform. 0.6
defaultL3NetworkUuid String The default L3 network UUID. 0.6
type String The resource type. 0.6
hypervisorType String The hypervisor type. 0.6
memorySize Long The memory size. 0.6
cpuNum Integer The number of CPUs. 0.6
cpuSpeed Long The CPU speed. 0.6
allocatorStrategy String The allocator strategy. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
state String The resource state. 0.6
vmNics List See vmNics. 0.6
allVolumes List See allVolumes. 0.6

#vmNics

Name Type Description Starting Version
uuid String The resource UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
l3NetworkUuid String The L3 network UUID. 0.6
ip String The IP address. 0.6
mac String The MAC address. 0.6
netmask String The netmask. 0.6
gateway String The gateway IP address. 0.6
metaData String The metadata. 0.6
deviceId Integer The device ID. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

#allVolumes

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

GetDataVolumeAttachableVmAction action = new GetDataVolumeAttachableVmAction();
action.volumeUuid = "df8f99ea16c54b7f945cbf3bc3968708";
action.sessionId = "a6bd56927c384d639f6ed058226a6a87";
GetDataVolumeAttachableVmAction.Result res = action.call();

Python SDK

action = GetDataVolumeAttachableVmAction()
action.volumeUuid = "212352bd2dc64bb6b42d052ba7b55c8f"
action.sessionId = "bc975e8c54764903857ddf7e22a8fa88"
res = action.call()

AttachDataVolumeToVm

API Request

URLs

POST zstack/v1/volumes/{volumeUuid}/vm-instances/{vmInstanceUuid}

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {},
  "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":{}}' http://localhost:8080/zstack/v1/volumes/6fdcff5868fe376a98359eba8b3d0efe/vm-instances/f6abc3b26ffe337ba61dd7298fb0b9df

Request Parameters

Name Type Location Description Optional Value Starting Version
vmInstanceUuid String url The VM instance UUID. 0.6
volumeUuid String url The volume UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
"inventory": {
"uuid": "4c118c4e51e54f839e6e0af9e17527f2",
"name": "test-volume",
"primaryStorageUuid": "9cd9e87803864fa1ae6cf4001fb5d4c8",
"vmInstanceUuid": "8a6f516d0da04addb062c903dd000830",
"diskOfferingUuid": "bdb5f71d810c49a08ff0e91f81936009",
"rootImageUuid": "a12e3048aab340c1b2c6bad2e4187a3a",
"installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-4c118c4e51e54f839e6e0af9e17527f2/4c118c4e51e54f839e6e0af9e17527f2.qcow2",
"type": "Root",
"format": "qcow2",
"size": 107374182400,
"actualSize": 21474836480,
"deviceId": 0,
"state": "Enabled",
"status": "Ready",
"createDate": "Jun 7, 2017 9:20:35 PM",
"lastOpDate": "Jun 7, 2017 9:20:35 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.7.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6
volumeQos String The volume QoS. 4.7.0
lastDetachDate Timestamp The last detach date. 4.7.0
lastVmInstanceUuid String The last VM instance UUID. 4.7.0

SDK Sample

Java SDK

AttachDataVolumeToVmAction action = new AttachDataVolumeToVmAction();
action.vmInstanceUuid = "255dc5614937406c9a988d9c1786b210";
action.volumeUuid = "1e54148b369b4edeb40fa355d96418f0";
action.sessionId = "f705bc797bc34ebd80690e8f154103d1";
AttachDataVolumeToVmAction.Result res = action.call();

Python SDK

action = AttachDataVolumeToVmAction()
action.vmInstanceUuid = "ebbc8ec209e54fc3a9872316b4d70bc6"
action.volumeUuid = "9451c035198c4e91818a0f47d6fc47c5"
action.sessionId = "4f838000320d44daa355120a7adef512"
res = action.call()

DetachDataVolumeFromVm

API Request

URLs

DELETE zstack/v1/volumes/{uuid}/vm-instances?vmUuid={vmUuid}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 7e5632146864445d8429d29e51dec0cb" \
-X DELETE http://localhost:8080/zstack/v1/volumes/7beae849715345d7aa8793d1c2942279/vm-instances?vmUuid=88d866d0c5ec303cb55cf4d4077f1987

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The volume UUID. 0.6
vmUuid String body Optional. The VM instance UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
"inventory": {
"uuid": "eeb5dcf6332e44cb81c190df7e6a68e9",
"name": "test-volume",
"primaryStorageUuid": "3d51fd1b41a5461ea1fcc7cc216e4db8",
"vmInstanceUuid": "e64ebdc324d445d5aad979fc62eb0a0d",
"diskOfferingUuid": "1391925279d7436cb6efd5c39c5144d1",
"rootImageUuid": "44794b5fec4a4061b533560fbaf458e2",
"installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-eeb5dcf6332e44cb81c190df7e6a68e9/eeb5dcf6332e44cb81c190df7e6a68e9.qcow2",
"type": "Root",
"format": "qcow2",
"size": 1.073741824E11,
"actualSize": 2.147483648E10,
"deviceId": 0.0,
"state": "Enabled",
"status": "Ready",
"createDate": "Jun 7, 2017 9:20:31 PM",
"lastOpDate": "Jun 7, 2017 9:20:31 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
diskOfferingUuid String The disk offering UUID. 0.6
rootImageUuid String The root image UUID. 0.6
installPath String The installation path. 0.6
type String The resource type. 0.6
format String The format. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
deviceId Integer The device ID. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
isShareable Boolean Whether the resource is shareable. 0.6

SDK Sample

Java SDK

DetachDataVolumeFromVmAction action = new DetachDataVolumeFromVmAction();
action.uuid = "a25328c5d8664e9bbfb4056561ff273b";
action.vmUuid = "a50e728336b8455e9802785ee6d81959";
action.sessionId = "b7ff5722af3e42f5ab4d0c77b8664f6c";
DetachDataVolumeFromVmAction.Result res = action.call();

Python SDK

action = DetachDataVolumeFromVmAction()
action.uuid = "b23d5a96ba19477dacae2429f9f181ef"
action.vmUuid = "58ab89b6a8e64a649fc38831ceaa95c8"
action.sessionId = "e97c2484efd84e0ba9f2f50a01a41d1a"
res = action.call()

AttachDataVolumeToHost

API Request

URLs

POST zstack/v1/volumes/{volumeUuid}/hosts/{hostUuid}

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "mountPath": "/test/mount/path"
  },
  "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":{"mountPath":"/test/mount/path"}}' http://localhost:8080/zstack/v1/volumes/95bd25d20dff3591a83f45280d05a67d/hosts/c7310b853b1d3e97b09e52c32bd2e9c6

Request Parameters

Name Type Location Description Valid Value Starting Version
volumeUuid String url The volume UUID. 4.5.0
hostUuid String url The host UUID. 4.5.0
mountPath String body The mount path on the host. 4.5.0
systemTags List body Optional. The system tags. 4.5.0
userTags List body Optional. The user tags. 4.5.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

AttachDataVolumeToHostAction action = new AttachDataVolumeToHostAction();
action.volumeUuid = "95bd25d20dff3591a83f45280d05a67d";
action.hostUuid = "c7310b853b1d3e97b09e52c32bd2e9c6";
action.mountPath = "/test/mount/path";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AttachDataVolumeToHostAction.Result res = action.call();

Python SDK

action = AttachDataVolumeToHostAction()
action.volumeUuid = "95bd25d20dff3591a83f45280d05a67d"
action.hostUuid = "c7310b853b1d3e97b09e52c32bd2e9c6"
action.mountPath = "/test/mount/path"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

DetachDataVolumeFromHost

API Request

URLs

DELETE zstack/v1/volumes/{volumeUuid}/hosts

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/volumes/961e87cd9adc335eb4227d98cb835e3c/hosts

Request Parameters

Name Type Location Description Valid Value Starting Version
volumeUuid String url The volume UUID. 4.5.0
hostUuid String body Optional. The host UUID. 4.5.0
systemTags List body Optional. The system tags. 4.5.0
userTags List body Optional. The user tags. 4.5.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

DetachDataVolumeFromHostAction action = new DetachDataVolumeFromHostAction();
action.volumeUuid = "961e87cd9adc335eb4227d98cb835e3c";
action.hostUuid = "aab7fb71a8eb3082b11f0fe1eb6fd181";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DetachDataVolumeFromHostAction.Result res = action.call();

Python SDK

action = DetachDataVolumeFromHostAction()
action.volumeUuid = "961e87cd9adc335eb4227d98cb835e3c"
action.hostUuid = "aab7fb71a8eb3082b11f0fe1eb6fd181"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

CreateVolumeSnapshot

API Request

URLs

POST zstack/v1/volumes/{volumeUuid}/volume-snapshots

Headers

Authorization: OAuth the-session-uuid

Body

{
"params": {
"name": "snapshot-volume",
"description": "a snapshot for volume"
  },
"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":"snapshot-volume","description":"a snapshot for volume"}}' \
http://localhost:8080/zstack/v1/volumes/96971a1cd12f3ebdba54578846992057/volume-snapshots

Request Parameters

Name Type Location Description Optional Value Starting Version
volumeUuid String url The volume UUID. 0.6
name String body (contained in the params structure) The snapshot name. 0.6
description String body (contained in the params structure) Optional. The detailed description of the snapshot. 0.6
resourceUuid String body (contained in the params structure) Optional. The resource UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
"inventory": {
"uuid": "ec8f396d8a5d48ce8bd949d469c0be62",
"name": "Snapshot-1",
"description": "create-snapshot-from-volume",
"type": "Hypervisor",
"volumeUuid": "e60a0fb0b75743c1b0fcb017e31db043",
"treeUuid": "b5cf59580ef443c4b7106cf755e6c572",
"parentUuid": "cc0e37297d76486186f0dd2b61ddf4e2",
"primaryStorageUuid": "82280d3f2f01482bbcdfee03599bcad5",
"primaryStorageInstallPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-e60a0fb0b75743c1b0fcb017e31db043/snapshots/ec8f396d8a5d48ce8bd949d469c0be62.qcow2",
"volumeType": "Root",
"format": "qcow2",
"latest": true,
"size": 1.073741824E9,
"state": "Enabled",
"status": "Ready",
"createDate": "Jun 7, 2017 9:20:17 PM",
"lastOpDate": "Jun 7, 2017 9:20:17 PM"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeSnapshotInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
type String The resource type. 0.6
volumeUuid String The volume UUID. 0.6
treeUuid String The tree UUID. 0.6
parentUuid String The parent UUID. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
primaryStorageInstallPath String The primary storage install path. 0.6
volumeType String The volume type. 0.6
format String The format. 0.6
latest Boolean The latest. 0.6
size Long The size. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
backupStorageRefs List See backupStorageRefs. 0.6

#backupStorageRefs

Name Type Description Starting Version
volumeSnapshotUuid String The volume snapshot UUID. 0.6
backupStorageUuid String The backup storage UUID. 0.6
installPath String The installation path. 0.6

SDK Sample

Java SDK

CreateVolumeSnapshotAction action = new CreateVolumeSnapshotAction();
action.volumeUuid = "093310638cef494088eac315cf1ff1b1";
action.name = "snapshot-volume";
action.description = "a snapshot for volume";
action.sessionId = "6020beb6826b4bb5a980965b435b2998";
CreateVolumeSnapshotAction.Result res = action.call();

Python SDK

action = CreateVolumeSnapshotAction()
action.volumeUuid = "5321658e475a4a8d9e41eef1186a079b"
action.name = "snapshot-volume"
action.description = "a snapshot for volume"
action.sessionId = "aad13372afb149918537613c50c3f49b"
res = action.call()

QueryVolumeSnapshot

API Request

URLs

GET zstack/v1/volume-snapshots
GET zstack/v1/volume-snapshots/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 7f983595cc744a14bb0fc9bfdd712e39" \
-X GET http://localhost:8080/zstack/v1/volume-snapshots?q=uuid=a3da945723d44971afded91bf3ebfd4d
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 90e4d7e2760e4f1893b78be27095bb9e" \
-X GET http://localhost:8080/zstack/v1/volume-snapshots/d8713ee3864442de8afc6cd614f51921

Queryable Fields

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

API Response

Sample Response

{
"inventories": [
    {
"uuid": "492ebccdeb804e308361b08e4f0e9a7a",
"name": "My Snapshot 2",
"primaryStorageUuid": "/Cloud_ps/rootVolumes/acct-e77f16d460ea46e18262547b56972273/vol-13c66bb52d0949398e520183b917f813/snapshots/2fa6979af5c6479fa98f37d316f44b5f.qcow2",
"volumeType": "Root",
"format": "qcow2",
"latest": false,
"size": 1310720.0,
"state": "Enabled",
"status": "Ready"
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventories

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
type String The resource type. 0.6
volumeUuid String The volume UUID. 0.6
treeUuid String The tree UUID. 0.6
parentUuid String The parent UUID. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
primaryStorageInstallPath String The primary storage install path. 0.6
volumeType String The volume type. 0.6
format String The format. 0.6
latest Boolean The latest. 0.6
size Long The size. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
backupStorageRefs List See backupStorageRefs. 0.6

#backupStorageRefs

Name Type Description Starting Version
volumeSnapshotUuid String The volume snapshot UUID. 0.6
backupStorageUuid String The backup storage UUID. 0.6
installPath String The installation path. 0.6

SDK Sample

Java SDK

QueryVolumeSnapshotAction action = new QueryVolumeSnapshotAction();
action.conditions = asList("uuid=d8722eb3601448dcbbd9f4b5a93ceb0e");
action.sessionId = "007c535099cc4f2eaab878d021a9d89a";
QueryVolumeSnapshotAction.Result res = action.call();

Python SDK

action = QueryVolumeSnapshotAction()
action.conditions = ["uuid=b64521c0da3a462da02687c4bee1a646"]
action.sessionId = "ecd0d0d0ccbc4be9a2c42a7d7b05d924"
res = action.call()

QueryVolumeSnapshotTree

API Request

URLs

GET zstack/v1/volume-snapshots/trees
GET zstack/v1/volume-snapshots/trees/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 6765993e28b6428fa5715c69c93962b2" \
-X GET http://localhost:8080/zstack/v1/volume-snapshots/trees?q=uuid=5ef4209325014bee8b2609e5f2fa3857
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 31697ae56f274658a261b666089f3891" \
-X GET http://localhost:8080/zstack/v1/volume-snapshots/trees/60a48ac22a474922bd4e18f4a16cff6d

Queryable Fields

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

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

QueryVolumeSnapshotTreeAction action = new QueryVolumeSnapshotTreeAction();
action.conditions = asList("uuid=f8b757fa8d354157aa83712be91c391c");
action.sessionId = "5a9d257d977543efb617d3a4619e9e10";
QueryVolumeSnapshotTreeAction.Result res = action.call();

Python SDK

action = QueryVolumeSnapshotTreeAction()
action.conditions = ["uuid=e7a8480f474e42aeabb8e9a5c74b2c3b"]
action.sessionId = "43ac6f171e87458096fda52a497a21b2"
res = action.call()

UpdateVolumeSnapshot

API Request

URLs

PUT zstack/v1/volume-snapshots/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
"updateVolumeSnapshot": {
"name": "My Snapshot"
  },
"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 '{"updateVolumeSnapshot":{"name":"My Snapshot"}}' \
http://localhost:8080/zstack/v1/volume-snapshots/df56acfb356130869fc80dbf80cf3172/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The snapshot UUID. 0.6
name String body (contained in the updateVolumeSnapshot structure) Optional. The new name of the snapshot. 0.6
description String body (contained in the updateVolumeSnapshot structure) Optional. The detailed description of the snapshot. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response

{
"inventory": {
"uuid": "a50e9be4b0eb492aa1cbb767e38ee45e",
"name": "My Snapshot 2",
"primaryStorageUuid": "/Cloud_ps/rootVolumes/acct-e77f16d460ea46e18262547b56972273/vol-13c66bb52d0949398e520183b917f813/snapshots/2fa6979af5c6479fa98f37d316f44b5f.qcow2",
"volumeType": "Root",
"format": "qcow2",
"latest": false,
"size": 1310720.0,
"state": "Enabled",
"status": "Ready"
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory VolumeSnapshotInventory See inventory. 0.6

#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. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
type String The resource type. 0.6
volumeUuid String The volume UUID. 0.6
treeUuid String The tree UUID. 0.6
parentUuid String The parent UUID. 0.6
primaryStorageUuid String The primary storage UUID. 0.6
primaryStorageInstallPath String The primary storage install path. 0.6
volumeType String The volume type. 0.6
format String The format. 0.6
latest Boolean The latest. 0.6
size Long The size. 0.6
state String The resource state. 0.6
status String The resource status. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
backupStorageRefs List See backupStorageRefs. 0.6

#backupStorageRefs

Name Type Description Starting Version
volumeSnapshotUuid String The volume snapshot UUID. 0.6
backupStorageUuid String The backup storage UUID. 0.6
installPath String The installation path. 0.6

SDK Sample

Java SDK

UpdateVolumeSnapshotAction action = new UpdateVolumeSnapshotAction();
action.uuid = "b4eadb8d20cc41e8a575c82553ec912c";
action.name = "My Snapshot";
action.sessionId = "94fb0621bb4647bb989864c845c6c22e";
UpdateVolumeSnapshotAction.Result res = action.call();

Python SDK

action = UpdateVolumeSnapshotAction()
action.uuid = "e6ded156a6f440889b258d0738c517b4"
action.name = "My Snapshot"
action.sessionId = "36d4adc78a9d4c73b141095efa8c78bc"
res = action.call()

DeleteVolumeSnapshot

API Request

URLs

DELETE zstack/v1/volume-snapshots/{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/volume-snapshots/0e9ba69c3d0e3bf4b20dd7988b353505

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 0.6
deleteMode String body Optional. The delete mode. Options: Permissive | Enforcing. Default mode: Permissive. 0.6
direction String body Optional. The data merge direction. Pull: Merge forward; Commit: Merge backward; Auto: Automatically select the optimal merge direction. 5.4.0
scope String body Optional. The data merge mode. Single: Merge only a single snapshot; Chain: Merge the entire snapshot chain; Auto: Automatically determine the best possible merge scope. 5.4.0
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

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

DeleteVolumeSnapshotAction action = new DeleteVolumeSnapshotAction();
action.uuid = "0e9ba69c3d0e3bf4b20dd7988b353505";
action.direction = "auto";
action.scope = "chain";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteVolumeSnapshotAction.Result res = action.call();

Python SDK

action = DeleteVolumeSnapshotAction()
action.uuid = "0e9ba69c3d0e3bf4b20dd7988b353505"
action.direction = "auto"
action.scope = "chain"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

RevertVolumeFromSnapshot

API Request

URLs

PUT zstack/v1/volume-snapshots/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
"revertVolumeFromSnapshot": {},
"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 '{"revertVolumeFromSnapshot":{}}' \
http://localhost:8080/zstack/v1/volume-snapshots/eba17ed729a03a76afb168cf41373daf/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The snapshot UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

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

RevertVolumeFromSnapshotAction action = new RevertVolumeFromSnapshotAction();
action.uuid = "34a3c300041249d098187c2120ab0097";
action.sessionId = "a5e0822600934b84ba8bb8fa0af5bce0";
RevertVolumeFromSnapshotAction.Result res = action.call();                                                                                                           

Python SDK

action = RevertVolumeFromSnapshotAction()
action.uuid = "f3728a6d5e324c41a98b12c067db105b"
action.sessionId = "63799306e40e486c94d31dc2fcbbee6a"
res = action.call()

GetVolumeSnapshotSize

API Request

URLs

PUT zstack/v1/volume-snapshots/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "getVolumeSnapshotSize": {},
  "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 '{"getVolumeSnapshotSize":{}}' http://localhost:8080/zstack/v1/volume-snapshots/3bd9e0b3e39a3abe8d39ccbe9031c723/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The snapshot UUID. 3.5.0
systemTags List body Optional. The system tags. 3.5.0
userTags List body Optional. The user tags. 3.5.0

API Response

Sample Response

{
  "size": 1.073741824E11,
  "actualSize": 5.36870912E10
}
Name Type Description Starting Version
size Long The snapshot size. 3.5.0
actualSize Long The actual size of the snapshot. 3.5.0
success boolean Whether the operation succeeded. 3.5.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 3.5.0
error ErrorCode See error. 3.5.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. 3.5.0
description String The brief description of the error. 3.5.0
details String The details about the error. 3.5.0
elaboration String The reserved field. Default value: null. 3.5.0
opaque LinkedHashMap The reserved field. Default value: null. 3.5.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. 3.5.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. 3.5.0
description String The brief description of the error. 3.5.0
details String The details about the error. 3.5.0
elaboration String The reserved field. Default value: null. 3.5.0
opaque LinkedHashMap The reserved field. Default value: null. 3.5.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. 3.5.0

SDK Sample

Java SDK

GetVolumeSnapshotSizeAction action = new GetVolumeSnapshotSizeAction();
action.uuid = "3bd9e0b3e39a3abe8d39ccbe9031c723";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetVolumeSnapshotSizeAction.Result res = action.call();

Python SDK

action = GetVolumeSnapshotSizeAction()
action.uuid = "3bd9e0b3e39a3abe8d39ccbe9031c723"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

ShrinkVolumeSnapshot

API Request

URLs

PUT zstack/v1/volume-snapshots/shrink/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "shrinkVolumeSnapshot": {},
  "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 '{"shrinkVolumeSnapshot":{}}' http://localhost:8080/zstack/v1/volume-snapshots/shrink/1ab2f9f306dd3ab4adbaf78491be0911/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 3.10.0
systemTags List body Optional. The system tags. 3.10.0
userTags List body Optional. The user tags. 3.10.0

API Response

Sample Response

{
  "shrinkResult": {
    "oldSize": 2.147483648E9,
    "size": 1.073741824E9,
    "deltaSize": 1.073741824E9
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 3.10.0
shrinkResult ShrinkResult See shrinkResult. 3.10.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. 3.10.0
description String The brief description of the error. 3.10.0
details String The details about the error. 3.10.0
elaboration String The reserved field. Default value: null. 3.10.0
opaque LinkedHashMap The reserved field. Default value: null. 3.10.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. 3.10.0

#shrinkResult

Name Type Description Starting Version
oldSize long The old size. 3.10.0
size long The size. 3.10.0
deltaSize long The delta size. 3.10.0

SDK Sample

Java SDK

ShrinkVolumeSnapshotAction action = new ShrinkVolumeSnapshotAction();
action.uuid = "1ab2f9f306dd3ab4adbaf78491be0911";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ShrinkVolumeSnapshotAction.Result res = action.call();

Python SDK

action = ShrinkVolumeSnapshotAction()
action.uuid = "1ab2f9f306dd3ab4adbaf78491be0911"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

FlattenVolume

API Request

URLs

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

Headers

Authorization: OAuth the-session-uuid

Body

{
  "flattenVolume": {
    "dryRun": false
  },
  "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 '{"flattenVolume":{"dryRun":false}}' http://localhost:8080/zstack/v1/volumes/df7876b9124d3fcb92528cf774fa6de1/actions

Request Parameters

Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 3.10.0
dryRun boolean body (contained in the flattenVolume structure) Optional. Trial. Predicate the data usage. 4.7.0
systemTags List body Optional. The system tags. 3.10.0
userTags List body Optional. The user tags. 3.10.0

API Response

Sample Response

{
  "inventory": {
    "uuid": "13ff90c5fcd43587915817a65cc87af3",
    "name": "test-volume",
    "primaryStorageUuid": "55db0399efaf35479125967b5bd6e8c7",
    "vmInstanceUuid": "c3f9c1907206307a896db9a94a35c29d",
    "diskOfferingUuid": "d4d9b3afe4993bfbba991b4414295a65",
    "rootImageUuid": "7bcdd79e0ed1347f9a2d4ea043bb9f37",
    "installPath": "/zstack_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-13ff90c5fcd43587915817a65cc87af3/13ff90c5fcd43587915817a65cc87af3.qcow2",
    "type": "Root",
    "format": "qcow2",
    "size": 107374182400,
    "actualSize": 21474836480,
    "deviceId": 0,
    "state": "Enabled",
    "status": "Ready",
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.7.0
inventory VolumeInventory See inventory. 4.7.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.0

#inventory

Name Type Description Starting Version
uuid String The resource UUID. 4.7.0
name String The resource name. 4.7.0
description String The resource description. 4.7.0
primaryStorageUuid String The primary storage UUID. 4.7.0
vmInstanceUuid String The VM instance UUID. 4.7.0
diskOfferingUuid String The disk offering UUID. 4.7.0
rootImageUuid String The root image UUID. 4.7.0
installPath String The installation path. 4.7.0
type String The resource type. 4.7.0
format String The format. 4.7.0
size Long The size. 4.7.0
actualSize Long The actual size. 4.7.0
deviceId Integer The device ID. 4.7.0
state String The resource state. 4.7.0
status String The resource status. 4.7.0
createDate Timestamp The creation date. 4.7.0
lastOpDate Timestamp The last operation date. 4.7.0
isShareable Boolean Whether the resource is shareable. 4.7.0
volumeQos String The volume QoS. 4.7.0
lastDetachDate Timestamp The last detach date. 4.7.0
lastVmInstanceUuid String The last VM instance UUID. 4.7.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. 4.7.0
description String The brief description of the error. 4.7.0
details String The details about the error. 4.7.0
elaboration String The reserved field. Default value: null. 4.7.0
opaque LinkedHashMap The reserved field. Default value: null. 4.7.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. 4.7.0

SDK Sample

Java SDK

FlattenVolumeAction action = new FlattenVolumeAction();
action.uuid = "df7876b9124d3fcb92528cf774fa6de1";
action.dryRun = false;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
FlattenVolumeAction.Result res = action.call();

Python SDK

action = FlattenVolumeAction()
action.uuid = "df7876b9124d3fcb92528cf774fa6de1"
action.dryRun = false
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()