DocsKnowledge BaseAPI Explorer
Documentation›ZVF›ZStack ZSphere›API ReferenceZVF

Image Related Interfaces

AddImage

Add an image to the image storage.

API Request

URLs
POST zstack/v1/images
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "name": "TinyLinux",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "architecture": "x86_64",
    "system": false,
    "format": "qcow2",
    "platform": "Linux",
    "backupStorageUuids": [
      "b8fc9c1c027438c28d36af24eca06595"
    ],
    "virtio": false
  },
  "systemTags": [],
  "userTags": []
}
Note: In the example above, userTags field can be omitted. It is listed to indicate that the body can contain this field.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d'{"params":{"name":"TinyLinux","url":"http://192.168.1.20/share/images/tinylinux.qcow2","mediaType":"RootVolumeTemplate","architecture":"x86_64","system":false,"format":"qcow2","platform":"Linux","backupStorageUuids":["b8fc9c1c027438c28d36af24eca06595"],"virtio":false}}' http://localhost:8080/zstack/v1/images
Parameter List
Name Type Location Description Allowed Values Starting Version
name String body (contained in params structure) Image name 0.6
description (Optional) String body (contained in params structure) Detailed description of the image 0.6
url String body (contained in params structure) URL address of the image to be added 0.6
mediaType (Optional) String body (contained in params structure) Type of the image
  • RootVolumeTemplate
  • ISO
  • DataVolumeTemplate
 0.6
guestOsType (Optional) String body (contained in params structure) Guest OS type corresponding to the image 0.6
system (Optional) boolean body (contained in params structure) Whether it is a system image 0.6
format (Optional) String body (contained in params structure) Format of the image, for example: raw 4.0.0
platform (Optional) String body (contained in params structure) Platform of the image
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
 0.6
backupStorageUuids List body (contained in params structure) List of image storage UUIDs where the image will be added 0.6
type (Optional) String body (contained in params structure) Internal use field 0.6
resourceUuid (Optional) String body (contained in params structure) Resource UUID. If specified, the image will use this value as its UUID. 0.6
architecture (Optional) String body (contained in params structure) Optional. The architecture.
  • x86_64
  • aarch64
  • mips64el
 4.0.0
tagUuids (Optional) List body (contained in params structure) List of tag UUIDs 4.0.0
systemTags List body System tags 0.6
userTags (Optional) List body User tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "1eb26d06364036b7860d2b7dbb462b8c",
    "name": "TinyLinux",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "architecture": "x86_64",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "1eb26d06364036b7860d2b7dbb462b8c",
        "backupStorageUuid": "902dcc8d1015318fb4903df890765c4d",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
#error
Name Type Description Starting Version
code String Error code number, globally unique identifier, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String Boot state of the image 4.0.0
status String Ready state of the image 4.0.0
size Long Image size 4.0.0
actualSize Long Actual image size 4.0.0
md5Sum String MD5 value of the image 4.0.0
url String URL address of the image 4.0.0
mediaType String Type of the image 4.0.0
guestOsType String Guest OS type corresponding to the image 4.0.0
type String Internal use field 4.0.0
platform String Platform of the image 4.0.0
format String Format of the image, for example: raw 4.0.0
system Boolean Indicates whether it is a system image 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image storage UUID 0.6
installPath String Install path on the image storage 4.0.0
exportUrl String Export URL of the image 4.0.0
exportMd5Sum String Export MD5 value of the image 4.0.0
status String Image ready state 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6

SDK Examples

Java SDK
AddImageAction action = new AddImageAction();
action.name = "TinyLinux";
action.url = "http://192.168.1.20/share/images/tinylinux.qcow2";
action.mediaType = "RootVolumeTemplate";
action.architecture = "x86_64";
action.system = false;
action.format = "qcow2";
action.platform = "Linux";
action.backupStorageUuids = asList("b8fc9c1c027438c28d36af24eca06595");
action.virtio = false;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AddImageAction.Result res = action.call();
Python SDK
AddImageAction action = AddImageAction()
action.name = "TinyLinux"
action.url = "http://192.168.1.20/share/images/tinylinux.qcow2"
action.mediaType = "RootVolumeTemplate"
action.architecture = "x86_64"
action.system = false
action.format = "qcow2"
action.platform = "Linux"
action.backupStorageUuids = [b8fc9c1c027438c28d36af24eca06595]
action.virtio = false
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
AddImageAction.Result res = action.call()

DeleteImage

API Request

URLs
DELETE zstack/v1/images/{uuid}?backupStorageUuids={backupStorageUuids}&deleteMode={deleteMode}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "backupStorageUuids": [
      "2499cd48fc33450a8737efff67ccb920"
    ],
    "deleteMode": "Permissive"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the example above, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth fb8be86094544022ad3e3abd0027b420" \
-X DELETE http://localhost:8080/zstack/v1/images/f92e888c970c4f739d91e59f6dd94b1e?backupStorageUuids=b5a48099da3e3423a8e41bf25b073ce0&deleteMode=Permissive
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the image, uniquely identifies the sub-resource 0.6
backupStorageUuids (Optional) List body List of image storage UUIDs 0.6
deleteMode (Optional) String body Delete mode (Permissive or Enforcing, default is Permissive) 0.6
systemTags (Optional) List body System tags 0.6
userTags (Optional) List body User tags 0.6

API Response

This API returns an empty JSON structure {} on success. On error, the returned JSON structure contains 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 Examples

Java SDK
DeleteImageAction action = new DeleteImageAction();
action.uuid = "22850dff70934ffdaa839a950cb5a470";
action.backupStorageUuids = asList("32974c8955cd4ed79d13458e41490883");
action.deleteMode = "Permissive";
action.sessionId = "517a458b87ca49cf80bf26e6000bc611";
DeleteImageAction.Result res = action.call();
Python SDK
DeleteImageAction action = DeleteImageAction()
action.uuid = "5bbd892e048b48b283e5d2f49a6a4e94"
action.backupStorageUuids = [fd127191bf504e3daf5292800c1ea2d8]
action.deleteMode = "Permissive"
action.sessionId = "cf5cf2689379496aaa4449fd14dc8330"
DeleteImageAction.Result res = action.call()

ExpungeImage

API Request

URLs
PUT zstack/v1/images/{imageUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "expungeImage": {
    "backupStorageUuids": [
      "ef3843bdde80427e9c8c0d4f05aa5cde"
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: In the example above, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"expungeImage":{"backupStorageUuids":["3be136c8d8b8323bb94b8464aae4b0a7"]}}' \
http://localhost:8080/zstack/v1/images/4dcddfadcd113b5f89f181c4f4a080c7/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String body (contained in params structure) Resource UUID, uniquely identifies the resource 0.6
imageUuid String url Image UUID 0.6
backupStorageUuids (Optional) List body (contained in params structure) List of image storage UUIDs 0.6
systemTags (Optional) List body System tags 0.6
userTags (Optional) List body User tags 0.6

API Response

This API returns an empty JSON structure {} on success. On error, the returned JSON structure contains 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 Examples

Java SDK
ExpungeImageAction action = new ExpungeImageAction();
action.imageUuid = "ddb63556ae714ee78bf468d5067beedd";
action.backupStorageUuids = asList("6f21a1307fb24117a25ed907c00a3e47");
action.sessionId = "b12c879167d3459a844b6ac1f8ff3b74";
ExpungeImageAction.Result res = action.call();
Python SDK
ExpungeImageAction action = ExpungeImageAction()
action.imageUuid = "59fcc3775336469facfd93c5c16bdb2d"
action.backupStorageUuids = [2dfcf2dfadb14022ac09172a82fb3aac]
action.sessionId = "11fe68c420514cb0a8d8e1d1c5755d11"
ExpungeImageAction.Result res = action.call()

QueryImage

API Request

URLs
GET zstack/v1/images
GET zstack/v1/images/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth ecf1dc42b51d4c7c8f814bd10ac0ba79" \
-X GET http://localhost:8080/zstack/v1/images?q=uuid=0538611eb03a48e0bbcfd08e528f0aa1
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 69e2477d74ae4b53a19b21ee6e88f9da" \
-X GET http://localhost:8080/zstack/v1/images/21897673f8274d319c4aeba92e8e4c73

Queryable Fields

Run the CLI command tool, enter QueryImage and press Tab to view all queryable fields and resource names that support cross-table queries.

API Response

Response Example
{
    "inventories": [
        {
            "actualSize": 7995392,
            "backupStorageRefs": [
                {
                    "backupStorageUuid": "bbc730b63081460198c1c7cb63025255",
                    "createDate": "Mar 10, 2018 2:35:09 PM",
                    "imageUuid": "2402b660b6f1582bb65246597b2f47f2",
                    "installPath": "zstore://2402b660b6f1582bb65246597b2f47f2/2ab567b512cc696f2207cf0e3260baa4982e1c02",
                    "lastOpDate": "Mar 10, 2018 2:35:09 PM",
                    "status": "Ready"
                }
            ],
            "createDate": "Mar 10, 2018 2:35:09 PM",
            "description": "",
            "format": "qcow2",
            "lastOpDate": "Mar 10, 2018 2:35:10 PM",
            "md5Sum": "f0fde821df71aaec63063bef1fb0a46a231e5a3fbb37ed5671eabee7563eb3f8",
            "mediaType": "RootVolumeTemplate",
            "name": "Image-1",
            "platform": "Linux",
            "size": 12682240,
            "state": "Enabled",
            "status": "Ready",
            "system": false,
            "type": "zstack",
            "url": "file:///opt/zstack-dvd/zstack-image-1.4.qcow2",
            "uuid": "2402b660b6f1582bb65246597b2f47f2"
        }
    ],
    "success": true
}

SDK Examples

Java SDK
QueryImageAction action = new QueryImageAction();
action.conditions = asList("uuid=02928c0d94a847b0b785bc9830f931c6");
action.sessionId = "512102357b3e44c7a1704240176c8661";
QueryImageAction.Result res = action.call();
Python SDK
QueryImageAction action = QueryImageAction()
action.conditions = ["uuid=4d4b95071b09499e9e15a206714d1586"]
action.sessionId = "893c8fe44f5b4b799b095c54ee7ae075"
QueryImageAction.Result res = action.call()

RecoverImage

Recover an Image that has been deleted (but not completely removed).

API Request

URLs
PUT zstack/v1/images/{imageUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "recoverImage": {
    "backupStorageUuids": [
      "b63989ade2194ce8b8f1823083395681"
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 5ab0e924388a44d7aa96b9e7df9d8df3" \
-X PUT -d '{"recoverImage":{"backupStorageUuids":["29849ef8f0fe3abeb8fff5e6d947d002"]}}' \
http://localhost:8080/zstack/v1/images/e55bb56eee93338cad8d7d1048a6b0c3/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
imageUuid String url Image UUID 0.6
backupStorageUuids (Optional) List body (contained in params structure) Image Storage UUID List 0.6
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "c019173f2b5742868058049be43033a1",
    "name": "TinyLinux",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "c019173f2b5742868058049be43033a1",
        "backupStorageUuid": "609d29fb59ee414f90cedbc3a71038c6",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String Image boot state 0.6
status String Image ready state 0.6
size Long Image size 0.6
actualSize Long Image actual capacity 0.6
md5Sum String Image md5 value 0.6
url String Image URL address 0.6
mediaType String Image type 0.6
guestOsType String Guest Operating System type corresponding to the Image 0.6
type String Internal use field 0.6
platform String Image system platform 0.6
format String Image format, for example: raw 0.6
system Boolean Indicates whether it is a system Image 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String Installation path on the Image Storage 0.6
exportUrl String Export Image URL 0.6
exportMd5Sum String Export Image md5 value 0.6
status String Image ready state 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6

SDK Examples

Java SDK
RecoverImageAction action = new RecoverImageAction();
action.imageUuid = "3220b5ea2ae24883a4eb847634e3e349";
action.backupStorageUuids = asList("ad4dcd853b894362bfd18c06779ed758");
action.sessionId = "66ba41da8526424d9ab70ed0072b8d22";
RecoverImageAction.Result res = action.call();
Python SDK
RecoverImageAction action = RecoverImageAction()
action.imageUuid = "7f8bb365b8d3413ab5d09f6d381552c3"
action.backupStorageUuids = [14d99a1ade5a431ea254902c808d7319]
action.sessionId = "044d56deddd849a092ff02ae54386cf1"
RecoverImageAction.Result res = action.call()

ChangeImageState

API Request

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "changeImageState": {
    "stateEvent": "disable"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"changeImageState":{"stateEvent":"disable"}}' \
http://localhost:8080/zstack/v1/images/5a4e7e1f1a653505925da09d0a64936b/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Image UUID, uniquely identifies the Image 0.6
stateEvent String body (contained in params structure) Image state
  • enable
  • disable
 0.6
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "e4891e6ef3a64ea08ce91ab379a5c856",
    "name": "TinyLinux",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "e4891e6ef3a64ea08ce91ab379a5c856",
        "backupStorageUuid": "8bf8f2f17e7c4cca8d684ae5d89eee9e",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String The resource state. 0.6
status String The resource status. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
md5Sum String The MD5 sum. 0.6
url String The URL. 0.6
mediaType String The media type. 0.6
guestOsType String The guest OS type. 0.6
type String The resource type. 0.6
platform String The platform. 0.6
format String The format. 0.6
system Boolean The system. 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String The installation path. 0.6
exportUrl String The export URL. 0.6
exportMd5Sum String The export MD5 sum. 0.6
status String The resource status. 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6

SDK Examples

Java SDK
ChangeImageStateAction action = new ChangeImageStateAction();
action.uuid = "d6d3cf3feace41ae9fe519fcfdf337e1";
action.stateEvent = "disable";
action.sessionId = "e510317dfbf64f7c9423652cefba6583";
ChangeImageStateAction.Result res = action.call();
Python SDK
ChangeImageStateAction action = ChangeImageStateAction()
action.uuid = "d33d29f7695a4376a9a37a094f89d9f2"
action.stateEvent = "disable"
action.sessionId = "ae3587d0cbf844c2921a97798d4dc37b"
ChangeImageStateAction.Result res = action.call()

UpdateImage

API Request

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateImage": {
    "platform": "Windows",
    "virtio": false
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateImage":{"platform":"Windows","virtio":false}}' http://localhost:8080/zstack/v1/images/38549d5d5a3d3c5caefc18d8a9e0aa13/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Image UUID, uniquely identifies the Image 0.6
name (Optional) String body (contained in params structure) Image name 0.6
description (Optional) String body (contained in params structure) Detailed description of the Image 0.6
guestOsType (Optional) String body (contained in params structure) Guest Operating System type corresponding to the Image 0.6
mediaType (Optional) String body (contained in params structure) Image type
  • RootVolumeTemplate
  • DataVolumeTemplate
  • ISO
 0.6
format (Optional) String body (contained in params structure) Image format
  • raw
  • qcow2
  • iso
 0.6
system (Optional) Boolean body (contained in params structure) Indicates whether it is a system Image 0.6
platform (Optional) String body (contained in params structure) Image system platform
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
 0.6
architecture (Optional) String body (contained in updateImage structure) Optional. The architecture.
  • x86_64
  • aarch64
  • mips64el
 4.0.0
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "fadea0efc22e3e6fa43f537f1af6ee6b",
    "name": "TinyLinux",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Windows",
    "architecture": "x86_64",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "fadea0efc22e3e6fa43f537f1af6ee6b",
        "backupStorageUuid": "b94ff32725d133fea53e8ada5ea7f0fc",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String Image boot state 4.0.0
status String Image ready state 4.0.0
size Long Image size 4.0.0
actualSize Long Image actual capacity 4.0.0
md5Sum String Image md5 value 4.0.0
url String Image URL address 4.0.0
mediaType String Image type 4.0.0
guestOsType String Guest Operating System type corresponding to the Image 4.0.0
type String Internal use field 4.0.0
platform String Image system platform 4.0.0
format String Image format, for example: raw 4.0.0
system Boolean Indicates whether it is a system Image 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String Installation path on the Image Storage 4.0.0
exportUrl String Export Image URL 4.0.0
exportMd5Sum String Export Image md5 value 4.0.0
status String Image ready state 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6

SDK Examples

Java SDK
UpdateImageAction action = new UpdateImageAction();
action.uuid = "38549d5d5a3d3c5caefc18d8a9e0aa13";
action.platform = "Windows";
action.virtio = false;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateImageAction.Result res = action.call();
Python SDK
UpdateImageAction action = UpdateImageAction()
action.uuid = "38549d5d5a3d3c5caefc18d8a9e0aa13"
action.platform = "Windows"
action.virtio = false
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdateImageAction.Result res = action.call()

SyncImageSize

API Request

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "syncImageSize": {},
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 3a29210c52824730884918d670745453" \
-X PUT -d '{"syncImageSize":{}}' \
http://localhost:8080/zstack/v1/images/7d0fb69a716330bba16a3ee557ee0ab2/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Image UUID, uniquely identifies the Image 0.6
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "a5288a2598074daabb0450db1eaf0e69",
    "name": "TinyLinux",
    "size": 2.097152E8,
    "actualSize": 2329057.0,
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "a5288a2598074daabb0450db1eaf0e69",
        "backupStorageUuid": "1a917c0b47c6475a996ed678f230419d",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String The resource state. 0.6
status String The resource status. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
md5Sum String The MD5 sum. 0.6
url String The URL. 0.6
mediaType String The media type. 0.6
guestOsType String The guest OS type. 0.6
type String The resource type. 0.6
platform String The platform. 0.6
format String The format. 0.6
system Boolean The system. 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String The installation path. 0.6
exportUrl String The export URL. 0.6
exportMd5Sum String The export MD5 sum. 0.6
status String The resource status. 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6

SDK Examples

Java SDK
SyncImageSizeAction action = new SyncImageSizeAction();
action.uuid = "46638764dfcb47b2bf916bce60d50f9f";
action.sessionId = "557e2989aa7d4178861c4fcacb85e40c";
SyncImageSizeAction.Result res = action.call();
Python SDK
SyncImageSizeAction action = SyncImageSizeAction()
action.uuid = "0073e30d1fd84cd0b47896e5bb22b205"
action.sessionId = "e6896c8311824d718e330908ec04d9a6"
SyncImageSizeAction.Result res = action.call()

DeleteImagePackage

API Request

URLs
DELETE zstack/v1/image-packages/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/image-packages/e7660c815f483befb15905bf6c776781?
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Resource UUID, uniquely identifies the resource 4.4.6
deleteMode (Optional) String body Delete mode
  • Permissive
  • Enforcing
 4.4.6
systemTags (Optional) List body System Tags 4.4.6
userTags (Optional) List body User Tags 4.4.6

API Response

This API returns an empty JSON object {} on success. On error, the returned JSON contains 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 Examples

Java SDK
DeleteImagePackageAction action = new DeleteImagePackageAction();
action.uuid = "e7660c815f483befb15905bf6c776781";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteImagePackageAction.Result res = action.call();
Python SDK
DeleteImagePackageAction action = DeleteImagePackageAction()
action.uuid = "e7660c815f483befb15905bf6c776781"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeleteImagePackageAction.Result res = action.call()

UpdateImagePackage

API Request

URLs
PUT zstack/v1/image-packages/{uuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateImagePackage": {
    "name": "ova-update",
    "description": "description-update"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/image-packages/eeed157556d2328c9c3aeec71ab75463
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Resource UUID, uniquely identifies the resource 4.4.6
name (Optional) String body (contained in updateImagePackage structure) Resource name 4.4.6
description (Optional) String body (contained in updateImagePackage structure) Detailed description of the resource 4.4.6
systemTags (Optional) List body System Tags 4.4.6
userTags (Optional) List body User Tags 4.4.6

API Response

Response Example
{
  "inventory": {
    "uuid": "ecdea1f236a13e74a5712edabb4cfe9e",
    "name": "ova",
    "description": "description",
    "vmUuid": "21c4183acbf737128aba034313e1f909",
    "backupStorageUuid": "99630920a09138ab93823380286efc57",
    "state": "Exported",
    "exportUrl": "http://bs-host-name/path/to/ova.ova",
    "md5Sum": "sampleMd5Sum",
    "format": "OVA",
    "size": 1.073741824E10,
    "createDate": "May 10, 2022 5:27:16 AM",
    "lastOpDate": "May 10, 2022 5:27:16 AM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.4.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 4.4.6
inventory ImagePackageInventory See inventory 4.4.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 4.4.6
description String Brief description of the error 4.4.6
details String Detailed error information 4.4.6
elaboration String Reserved field, defaults to null 4.4.6
opaque LinkedHashMap Reserved field, defaults to null 4.4.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 4.4.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 4.4.6
name String Resource name 4.4.6
description String Detailed description of the resource 4.4.6
vmUuid String Source VM UUID 4.4.6
backupStorageUuid String Image Storage UUID where the Image Package file is located 4.4.6
exportUrl String Download URL 4.4.6
md5Sum String Image Package file MD5 checksum 4.4.6
format String Image Package file format 4.4.6
size Long Image Package file size 4.4.6
createDate Timestamp Creation time 4.4.6
lastOpDate Timestamp Last modification time 4.4.6
state ImagePackageState See state 4.4.6
#state
Name Type Description Starting Version
Exporting ImagePackageState Exporting 4.4.6
Exported ImagePackageState Exported 4.4.6

SDK Examples

Java SDK
QueryImagePackageAction action = new QueryImagePackageAction();
action.conditions = asList("uuid=5319396fe8f0393d998ac6c0939e780e");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryImagePackageAction.Result res = action.call();
Python SDK
QueryImagePackageAction action = QueryImagePackageAction()
action.conditions = ["uuid=99435bfd7903372289db27c8a2b1038c"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryImagePackageAction.Result res = action.call()

QueryImagePackage

API Request

URLs
GET zstack/v1/image-packages
GET zstack/v1/image-packages/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/image-packages?q=uuid=7cd2f1b456ce3045b78d3c1eb58cc03d
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/image-packages/1c57c91becf431f3b098800fc900c708

Queryable Fields

Run the CLI command tool, enter QueryImagePackage and press Tab to view all queryable fields and resource names that support cross-table queries.

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "e97e03503a5d3bf19a23f91c9a79e009",
      "name": "ova",
      "description": "description",
      "vmUuid": "b3da643979eb3452abbeb978208cb672",
      "backupStorageUuid": "6185f4e18a993ece84a06ec8c469b530",
      "state": "Exported",
      "exportUrl": "http://bs-host-name/path/to/ova.ova",
      "md5Sum": "sampleMd5Sum",
      "format": "OVA",
      "size": 1.073741824E10,
      "createDate": "May 10, 2022 5:26:20 AM",
      "lastOpDate": "May 10, 2022 5:26:20 AM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.4.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 4.4.6
inventories List See inventories 4.4.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 4.4.6
description String Brief description of the error 4.4.6
details String Detailed error information 4.4.6
elaboration String Reserved field, defaults to null 4.4.6
opaque LinkedHashMap Reserved field, defaults to null 4.4.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 4.4.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 4.4.6
name String Resource name 4.4.6
description String Detailed description of the resource 4.4.6
vmUuid String Source VM UUID 4.4.6
backupStorageUuid String Image Storage UUID where the Image Package file is located 4.4.6
exportUrl String Download URL 4.4.6
md5Sum String Image Package file MD5 checksum 4.4.6
format String Image Package file format 4.4.6
size Long Image Package file size 4.4.6
createDate Timestamp Creation time 4.4.6
lastOpDate Timestamp Last modification time 4.4.6
state ImagePackageState See state 4.4.6
#state
Name Type Description Starting Version
Exporting ImagePackageState Exporting 4.4.6
Exported ImagePackageState Exported 4.4.6

SDK Examples

Java SDK
QueryImagePackageAction action = new QueryImagePackageAction();
action.conditions = asList("uuid=5319396fe8f0393d998ac6c0939e780e");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryImagePackageAction.Result res = action.call();
Python SDK
QueryImagePackageAction action = QueryImagePackageAction()
action.conditions = ["uuid=99435bfd7903372289db27c8a2b1038c"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryImagePackageAction.Result res = action.call()

GetCandidateBackupStorageForCreatingImage

Get candidate Image Storage for creating an Image.

API Request

URLs
GET zstack/v1/images/candidate-backup-storage
GET zstack/v1/images/volumes/{volumeUuid}/candidate-backup-storage
GET zstack/v1/images/volume-snapshots/{volumeSnapshotUuid}/candidate-backup-storage
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/images/candidate-backup-storage?volumeUuid=599c51abe51a320d842584f90984a6f4&volumeSnapshotUuid=2deb33e07a90373ea4fa7bd3a0352e0d
curl -H "Content-Type: application/json" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/images/volumes/599c51abe51a320d842584f90984a6f4/candidate-backup-storage?volumeUuid=599c51abe51a320d842584f90984a6f4&volumeSnapshotUuid=2deb33e07a90373ea4fa7bd3a0352e0d
curl -H "Content-Type: application/json" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/images/volume-snapshots/2deb33e07a90373ea4fa7bd3a0352e0d/candidate-backup-storage?volumeUuid=599c51abe51a320d842584f90984a6f4&volumeSnapshotUuid=2deb33e07a90373ea4fa7bd3a0352e0d
Parameter List
Name Type Location Description Allowed Values Starting Version
volumeUuid (Optional) String query Disk UUID. Note: volumeUuid and volumeSnapshotUuid are mutually exclusive 0.6
volumeSnapshotUuid (Optional) String query Disk Snapshot UUID. Note: volumeUuid and volumeSnapshotUuid are mutually exclusive 0.6
systemTags (Optional) List query System Tags 0.6
userTags (Optional) List query User Tags 0.6

API Response

This API returns an empty JSON object {} on success. On error, the returned JSON contains 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 Examples

Java SDK
GetCandidateBackupStorageForCreatingImageAction action = new GetCandidateBackupStorageForCreatingImageAction();
action.volumeUuid = "77e77779b5f94617af0a8b08b4a50129";
action.volumeSnapshotUuid = "4a5220b5b1f044f8826520eb506d0f98";
action.sessionId = "45b0a87571c2476ba2fe6623daaa79cf";
GetCandidateBackupStorageForCreatingImageAction.Result res = action.call();
Python SDK
GetCandidateBackupStorageForCreatingImageAction action = GetCandidateBackupStorageForCreatingImageAction()
action.volumeUuid = "83792660358b4e14b266c5d0920b8b21"
action.volumeSnapshotUuid = "3d562e4325cc42ce8bd3115b48f79ae4"
action.sessionId = "2ba3d333ac284a20adc782766f597330"
GetCandidateBackupStorageForCreatingImageAction.Result res = action.call()

CreateRootVolumeTemplateFromRootVolume

API Request

URLs
POST zstack/v1/images/root-volume-templates/from/volumes/{rootVolumeUuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "name": "My Root Volume Template",
    "backupStorageUuids": [
      "a3cb55d45fb63d1da4911b9d16273a55"
    ],
    "platform": "Linux",
    "system": false
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"My Root Volume Template","backupStorageUuids":["a3cb55d45fb63d1da4911b9d16273a55"],"platform":"Linux","system":false}}' http://localhost:8080/zstack/v1/images/root-volume-templates/from/volumes/3bfc6f9eaf243299b8515382310be47b
Parameter List
Name Type Location Description Allowed Values Starting Version
name String body (contained in params structure) Root Volume Image name 0.6
description (Optional) String body (contained in params structure) Detailed description of the Root Volume Image 0.6
guestOsType (Optional) String body (contained in params structure) Guest Operating System type corresponding to the Root Volume Image 0.6
backupStorageUuids (Optional) List body (contained in params structure) Image Storage UUID List 0.6
rootVolumeUuid String body (contained in params structure) Root Volume UUID 0.6
platform (Optional) String body (contained in params structure) System platform corresponding to the Root Volume Image
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
 0.6
system (Optional) boolean body (contained in params structure) Whether it is a system Root Volume Image 0.6
resourceUuid (Optional) String body (contained in params structure) Root Volume Image UUID. If specified, the Root Volume Image will use this field value as its UUID. 0.6
architecture (Optional) String body (contained in params structure) Optional. The architecture. 4.0.0
tagUuids (Optional) List body (contained in params structure) Tag UUID List 4.0.0
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6
Note:
  • ZStack ZSphere supports copying GuestTools label values from the VM to the Image when creating a Root Volume Image from a Root Volume. When using this Image to create a VM, the GuestTools label values are copied from the Image to the new VM. Add GuestTools option to SystemTags.
    • Option format: GuestTools::TOOLS_VERSION, where TOOLS_VERSION initial value is 1.0.0. This value will change as the tool version advances.
    • Example: GuestTools::1.0.0
    • Additional note: When creating an Image from a VM's Root Volume, copy the GuestTools label values from the VM to the Image.

API Response

Response Example
{
  "inventory": {
    "uuid": "cad3a82224363f1e8592a7fd0bf419f9",
    "name": "My Root Volume Template",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "architecture": "x86_64",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "cad3a82224363f1e8592a7fd0bf419f9",
        "backupStorageUuid": "ac938bdf013b3a94acf679955f69f647",
        "installPath": "ceph://zs-images/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String Image boot state 4.0.0
status String Image ready state 4.0.0
size Long Image size 4.0.0
actualSize Long Image actual capacity 4.0.0
md5Sum String Image md5 value 4.0.0
url String Image URL address 4.0.0
mediaType String Image type 4.0.0
guestOsType String Guest Operating System type corresponding to the Image 4.0.0
type String Internal use field 4.0.0
platform String Image system platform 4.0.0
format String Image format, for example: raw 4.0.0
system Boolean Indicates whether it is a system Image 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String Installation path on the Image Storage 4.0.0
exportUrl String Export Image URL 4.0.0
exportMd5Sum String Export Image md5 value 4.0.0
status String Image ready state 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6

SDK Examples

Java SDK
CreateRootVolumeTemplateFromRootVolumeAction action = new CreateRootVolumeTemplateFromRootVolumeAction();
action.name = "My Root Volume Template";
action.backupStorageUuids = asList("a3cb55d45fb63d1da4911b9d16273a55");
action.rootVolumeUuid = "3bfc6f9eaf243299b8515382310be47b";
action.platform = "Linux";
action.system = false;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateRootVolumeTemplateFromRootVolumeAction.Result res = action.call();
Python SDK
CreateRootVolumeTemplateFromRootVolumeAction action = CreateRootVolumeTemplateFromRootVolumeAction()
action.name = "My Root Volume Template"
action.backupStorageUuids = [a3cb55d45fb63d1da4911b9d16273a55]
action.rootVolumeUuid = "3bfc6f9eaf243299b8515382310be47b"
action.platform = "Linux"
action.system = false
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
CreateRootVolumeTemplateFromRootVolumeAction.Result res = action.call()

CreateRootVolumeTemplateFromVolumeSnapshot

Create a Root Volume Image from a Volume Snapshot.

API Request

URLs
POST zstack/v1/images/root-volume-templates/from/volume-snapshots/{snapshotUuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "name": "My Root Volume Template",
    "backupStorageUuids": [
      "41a9753ebf8031ef83b41ebed095b783"
    ],
    "system": false
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"My Root Volume Template","backupStorageUuids":["41a9753ebf8031ef83b41ebed095b783"],"system":false}}' \
http://localhost:8080/zstack/v1/images/root-volume-templates/from/volume-snapshots/f31fda67d1be32998cef3f3d9a280e1c
Parameter List
Name Type Location Description Allowed Values Starting Version
snapshotUuid String url Snapshot UUID 0.6
name String body (contained in params structure) Root Volume Image name 0.6
description (Optional) String body (contained in params structure) Detailed description of the Root Volume Image 0.6
guestOsType (Optional) String body (contained in params structure) Root Volume Guest Operating System type 0.6
backupStorageUuids List body (contained in params structure) Image Storage UUID List 0.6
platform (Optional) String body (contained in params structure) System platform corresponding to the Root Volume Image
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
 0.6
system (Optional) boolean body (contained in params structure) Whether it is a system Root Volume Image 0.6
resourceUuid (Optional) String body (contained in params structure) Root Volume Image UUID. If specified, the Root Volume Image will use this field value as its UUID. 0.6
architecture (Optional) String body (contained in params structure) Optional. The architecture. 4.0.0
tagUuids (Optional) List body (contained in params structure) Tag UUID List 4.0.0
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "cfe7842a8c1a30a1870965a7d6133760",
    "name": "My Root Volume Template",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "cfe7842a8c1a30a1870965a7d6133760",
        "backupStorageUuid": "f5f16e1618323606a7501b50be251c05",
        "installPath": "ceph://zs-images/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
failures List See failures 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String Image boot state 4.0.0
status String Image ready state 4.0.0
size Long Image size 4.0.0
actualSize Long Image actual capacity 4.0.0
md5Sum String Image md5 value 4.0.0
url String Image URL address 4.0.0
mediaType String Image type 4.0.0
guestOsType String Guest Operating System type corresponding to the Image 4.0.0
type String Internal use field 4.0.0
platform String Image system platform 4.0.0
format String Image format, for example: raw 4.0.0
system Boolean Indicates whether it is a system Image 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String Installation path on the Image Storage 4.0.0
exportUrl String Export Image URL 4.0.0
exportMd5Sum String Export Image md5 value 4.0.0
status String Image ready state 4.0.0
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
#failures
Name Type Description Starting Version
backupStorageUuid String Image Storage UUID 0.6
error ErrorCode See error 0.6

SDK Examples

Java SDK
CreateRootVolumeTemplateFromVolumeSnapshotAction action = new CreateRootVolumeTemplateFromVolumeSnapshotAction();
action.snapshotUuid = "f31fda67d1be32998cef3f3d9a280e1c";
action.name = "My Root Volume Template";
action.backupStorageUuids = asList("41a9753ebf8031ef83b41ebed095b783");
action.system = false;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateRootVolumeTemplateFromVolumeSnapshotAction.Result res = action.call();
Python SDK
CreateRootVolumeTemplateFromVolumeSnapshotAction action = CreateRootVolumeTemplateFromVolumeSnapshotAction()
action.snapshotUuid = "f31fda67d1be32998cef3f3d9a280e1c"
action.name = "My Root Volume Template"
action.backupStorageUuids = [41a9753ebf8031ef83b41ebed095b783]
action.system = false
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
CreateRootVolumeTemplateFromVolumeSnapshotAction.Result res = action.call()

CreateDataVolumeTemplateFromVolume

API Request

URLs
POST zstack/v1/images/data-volume-templates/from/volumes/{volumeUuid}
Hearders
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "name": "My Data Volume Template",
    "backupStorageUuids": [
      "7fd08286addc4b388fac61935892acd7"
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"My Data Volume Template","backupStorageUuids":["08e337886b873e8685991d1c7ba4d1ab"]}}' \
http://localhost:8080/zstack/v1/images/data-volume-templates/from/volumes/4c941eb9faeb3976803fce2f3609a475
Parameter List
Name Type Location Description Allowed Values Starting Version
name String body (contained in params structure) Data Volume Image name 0.6
description (Optional) String body (contained in params structure) Detailed description of the Data Volume Image 0.6
volumeUuid String body (contained in params structure) Source Volume UUID 0.6
backupStorageUuids (Optional) List body (contained in params structure) Image Storage UUID List 0.6
resourceUuid (Optional) String body (contained in params structure) Data Volume Image UUID. If specified, the Data Volume Image will use this field value as its UUID. 0.6
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "7247cf569e2b4104832071822cf845c5",
    "name": "My Data Volume Template",
    "mediaType": "DataVolumeTemplate",
    "platform": "Linux",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "7247cf569e2b4104832071822cf845c5",
        "backupStorageUuid": "1b8ab68b7e224a30aa31f00f1db2b5a6",
        "installPath": "ceph://zs-data-volume/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String The resource state. 0.6
status String The resource status. 0.6
size Long The size. 0.6
actualSize Long The actual size. 0.6
md5Sum String The MD5 sum. 0.6
url String The URL. 0.6
mediaType String The media type. 0.6
guestOsType String The guest OS type. 0.6
type String The resource type. 0.6
platform String The platform. 0.6
format String The format. 0.6
system Boolean The system. 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String The installation path. 0.6
exportUrl String The export URL. 0.6
exportMd5Sum String The export MD5 sum. 0.6
status String The resource status. 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6

SDK Examples

Java SDK
CreateDataVolumeTemplateFromVolumeAction action = new CreateDataVolumeTemplateFromVolumeAction();
action.name = "My Data Volume Template";
action.volumeUuid = "816fb7184ae2498189000d7c0fe66112";
action.backupStorageUuids = asList("26b9d22ef1af4bdb880c3d77a8b1feda");
action.sessionId = "c17620d57db14c9383fbdd2650c80a73";
CreateDataVolumeTemplateFromVolumeAction.Result res = action.call();
Python SDK
CreateDataVolumeTemplateFromVolumeAction action = CreateDataVolumeTemplateFromVolumeAction()
action.name = "My Data Volume Template"
action.volumeUuid = "38b644a29b2d498ebc5b50d1d212d904"
action.backupStorageUuids = [1954c35eb0a844d8bb6a64f9963be0f5]
action.sessionId = "343ff2f080414010adb1a35957f8b700"
CreateDataVolumeTemplateFromVolumeAction.Result res = action.call()

CreateDataVolumeTemplateFromVolumeSnapshot

Create a Data Volume Image from a specified Volume Snapshot.

API Request

URLs
POST zstack/v1/images/data-volume-templates/from/volume-snapshots/{snapshotUuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "name": "My Data Volume Template",
    "backupStorageUuids": [
      "dbf107f8efa531f786f243850499e010"
    ],
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"My Data Volume Template","backupStorageUuids":["dbf107f8efa531f786f243850499e010"]}}' \
http://localhost:8080/zstack/v1/images/data-volume-templates/from/volume-snapshots/58976137bf95309692762077cd7077e3
Parameter List
Name Type Location Description Allowed Values Starting Version
snapshotUuid String url Snapshot UUID 0.6
name String body (contained in params structure) Data Volume Image name 0.6
description (Optional) String body (contained in params structure) Detailed description of the Data Volume Image 0.6
backupStorageUuids List body (contained in params structure) Image Storage UUID List 0.6
resourceUuid (Optional) String body (contained in params structure) Data Volume Image UUID. If specified, the Data Volume Image will use this field value as its UUID 0.6
tagUuids (Optional) List body (contained in params structure) Tag UUID List
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

Response Example
{
  "inventory": {
    "uuid": "314d80c2feb5352c984b3ffd36108c32",
    "name": "My Data Volume Template",
    "mediaType": "DataVolumeTemplate",
    "platform": "Linux",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0.0,
        "imageUuid": "314d80c2feb5352c984b3ffd36108c32",
        "backupStorageUuid": "d861144baadf31e3b1cbbb282242adcf",
        "installPath": "ceph://zs-images/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventory ImageInventory See inventory 0.6
failures List See failures 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
name String Resource name 0.6
description String Detailed description of the resource 0.6
state String Image boot state 0.6
status String Image ready state 0.6
size Long Image size 0.6
actualSize Long Image actual capacity 0.6
md5Sum String Image md5 value 0.6
url String Image URL address 0.6
mediaType String Image type 0.6
guestOsType String Guest Operating System type corresponding to the Image 0.6
type String Internal use field 0.6
platform String Image system platform 0.6
format String Image format, for example: raw 0.6
system Boolean Indicates whether it is a system Image 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
backupStorageRefs List See backupStorageRefs 0.6
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 0.6
backupStorageUuid String Image Storage UUID 0.6
installPath String Installation path on the Image Storage 0.6
exportUrl String Export Image URL 0.6
exportMd5Sum String Export Image md5 value 0.6
status String Image ready state 0.6
createDate Timestamp Creation time 0.6
lastOpDate Timestamp Last modification time 0.6
#failures
Name Type Description Starting Version
backupStorageUuid String Image Storage UUID 0.6
error ErrorCode See error 0.6

SDK Examples

Java SDK
CreateDataVolumeTemplateFromVolumeSnapshotAction action = new CreateDataVolumeTemplateFromVolumeSnapshotAction();
action.snapshotUuid = "58976137bf95309692762077cd7077e3";
action.name = "My Data Volume Template";
action.backupStorageUuids = asList("dbf107f8efa531f786f243850499e010");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateDataVolumeTemplateFromVolumeSnapshotAction.Result res = action.call();
Python SDK
CreateDataVolumeTemplateFromVolumeSnapshotAction action = CreateDataVolumeTemplateFromVolumeSnapshotAction()
action.snapshotUuid = "58976137bf95309692762077cd7077e3"
action.name = "My Data Volume Template"
action.backupStorageUuids = [dbf107f8efa531f786f243850499e010]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
CreateDataVolumeTemplateFromVolumeSnapshotAction.Result res = action.call()

GetImageQga

API Request

URLs
GET zstack/v1/images/{uuid}/qga
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth e74211f026f741c1898d4377ecf58bd1" \
-X GET http://localhost:8080/zstack/v1/images/34a5bf0cc1014286bd944771c77e1c07/qga
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Resource UUID, uniquely identifies the resource 0.6
systemTags (Optional) List query Optional. The system tags. 0.6
userTags (Optional) List query Optional. The user tags. 0.6

API Response

Response Example
{
  "enable": false
}
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 0.6
enable boolean Whether the feature is enabled. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 0.6

SDK Examples

Java SDK
GetImageQgaAction action = new GetImageQgaAction();
action.uuid = "0d7b698ccb174702ae5fa7f15bce8612";
action.sessionId = "3e59586b589d4dbeb0afd078bb887655";
GetImageQgaAction.Result res = action.call();
Python SDK
GetImageQgaAction action = GetImageQgaAction()
action.uuid = "82a89e52f2c54fab9b73f095e23ddecb"
action.sessionId = "fc8ea8bda61143cea7db98957ccd026f"
GetImageQgaAction.Result res = action.call()

SetImageQga

API Request

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setImageQga": {
    "enable": true
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"setImageQga":{"enable":true}}' \
http://localhost:8080/zstack/v1/images/f85a077c64883070ac3ba72079edc804/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Resource UUID, uniquely identifies the resource 0.6
enable boolean body (contained in setImageQga structure) Whether the feature is enabled. 0.6
systemTags (Optional) List body Optional. The system tags. 0.6
userTags (Optional) List body Optional. The user tags. 0.6

API Response

This API returns an empty JSON object {} on success. On error, the returned JSON contains 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 Examples

Java SDK
SetImageQgaAction action = new SetImageQgaAction();
action.uuid = "0eca41aa133a43d2b8d14958cd3b3f26";
action.enable = true;
action.sessionId = "a05d7d13fb514bb5bd16060c7584d6e6";
SetImageQgaAction.Result res = action.call();
Python SDK
SetImageQgaAction action = SetImageQgaAction()
action.uuid = "f397649bf07049efb0be7836962d03fe"
action.enable = true
action.sessionId = "0bfcd0ef201142bcb00ab5903b178da5"
SetImageQgaAction.Result res = action.call()

SetImageBootMode

API Request

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setImageBootMode": {
    "bootMode": "Legacy"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"setImageBootMode":{"bootMode":"Legacy"}}' http://localhost:8080/zstack/v1/images/4efcba4c12cc35f4a1b262038f7e7b80/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Resource UUID, uniquely identifies the resource 3.9.0
bootMode String body (contained in setImageBootMode structure) Image boot mode
  • Legacy
  • UEFI
  • UEFI_WITH_CSM
 3.9.0
systemTags (Optional) List body System Tags 3.9.0
userTags (Optional) List body User Tags 3.9.0

API Response

This API returns an empty JSON object {} on success. On error, the returned JSON contains 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 Examples

Java SDK
SetImageBootModeAction action = new SetImageBootModeAction();
action.uuid = "4efcba4c12cc35f4a1b262038f7e7b80";
action.bootMode = "Legacy";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
SetImageBootModeAction.Result res = action.call();
Python SDK
SetImageBootModeAction action = SetImageBootModeAction()
action.uuid = "4efcba4c12cc35f4a1b262038f7e7b80"
action.bootMode = "Legacy"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
SetImageBootModeAction.Result res = action.call()

GetUploadImageJobDetails

API Request

URLs
PUT zstack/v1/images/upload-job/details/{imageId}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setImageBootMode": {
    "bootMode": "Legacy"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/images/upload-job/details/d41d8cd98f00b204e9800998ecf8427e?
Parameter List
Name Type Location Description Allowed Values Starting Version
imageId String url Unique identifier for the image upload, user-defined, md5 recommended 4.1.0
systemTags (Optional) List body System Tags 4.1.0
userTags (Optional) List body User Tags 4.1.0

API Response

Response Example
{
  "existingJobDetails": [
    {
      "longJobUuid": "0792dd52aeb9329cb1e677fae6465f23",
      "longJobState": "Suspended",
      "imageUuid": "ccf943310d86335bb3d2511ca8e14137",
      "imageUploadUrl": "http://127.0.0.1:8001/imagestore/upload",
      "offset": 4.52984832E8
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.1.0
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 4.1.0
existingJobDetails See existingJobDetails 4.1.0
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 4.1.0
description String Brief description of the error 4.1.0
details String Detailed error information 4.1.0
elaboration String Reserved field, defaults to null 4.1.0
opaque LinkedHashMap Reserved field, defaults to null 4.1.0
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 4.1.0
#existingJobDetails
Name Type Description Starting Version
longJobUuid String Long job UUID 4.1.0
longJobState String Long job state 4.1.0
imageUuid String Image UUID 4.1.0
imageUploadUrl String Image upload URL 4.1.0
offset long Upload offset, in bytes 4.1.0

SDK Examples

Java SDK
GetUploadImageJobDetailsAction action = new GetUploadImageJobDetailsAction();
action.imageId = "d41d8cd98f00b204e9800998ecf8427e";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetUploadImageJobDetailsAction.Result res = action.call();
Python SDK
GetUploadImageJobDetailsAction action = GetUploadImageJobDetailsAction()
action.imageId = "d41d8cd98f00b204e9800998ecf8427e"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetUploadImageJobDetailsAction.Result res = action.call()

CalculateImageHash

API Request

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "calculateImageHash": {
    "backupStorageUuid": "0eeaa5988c743c638485304f3d1f867e",
    "algorithm": "MD5"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"calculateImageHash":{"backupStorageUuid":"0eeaa5988c743c638485304f3d1f867e","algorithm":"MD5"}}' \
http://localhost:8080/zstack/v1/images/383bcf0b1515369a8169b66a91de1e00/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Resource UUID, uniquely identifies the resource 4.1.0
backupStorageUuid String body (contained in calculateImageHash structure) Backup Storage UUID 4.1.0
algorithm (Optional) String body (contained in calculateImageHash structure) Optional. The algorithm. 4.1.0
systemTags (Optional) List body System Tags 4.1.0
userTags (Optional) List body User Tags 4.1.0

API Response

Response Example
{
  "inventory": {
    "uuid": "368da584193638818c480bef63732659",
    "name": "TinyLinux",
    "md5Sum": "6fc2357e711877c14c09eec960e51aed",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0,
        "imageUuid": "368da584193638818c480bef63732659",
        "backupStorageUuid": "17f9f8d310763247b5dc31779d880a41",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 4.1.0
inventory ImageInventory See inventory 4.1.0
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 4.1.0
#error
Name Type Description Starting Version
code String Error code number, a globally unique identifier for the error, for example SYS.1000, HOST.1001 5.0.0
description String Brief description of the error 5.0.0
details String Detailed error information 5.0.0
elaboration String Reserved field, defaults to null 5.0.0
opaque LinkedHashMap Reserved field, defaults to null 5.0.0
cause ErrorCode Root cause. The source error that triggered the current error. This field is null if there is no original error 5.0.0
#inventory
Name Type Description Starting Version
uuid String Resource UUID, uniquely identifies the resource 4.1.0
name String Resource name 4.1.0
description String Detailed description of the resource 4.1.0
state String Image state 4.1.0
status String Image status 4.1.0
size Long Image size 4.1.0
actualSize Long Actual image size 4.1.0
md5Sum String Image MD5 value 4.1.0
url String Image URL 4.1.0
mediaType String Media type 4.1.0
guestOsType String Guest OS type 4.1.0
type String Internal field 4.1.0
platform String Image platform 4.1.0
architecture String The architecture. 4.1.0
format String Image format, for example: raw 4.1.0
system Boolean Indicates whether it is a system image 4.1.0
virtio Boolean The virtio. 4.1.0
createDate Timestamp Creation time 4.1.0
lastOpDate Timestamp Last modification time 4.1.0
backupStorageRefs List See backupStorageRefs 4.1.0
#backupStorageRefs
Name Type Description Starting Version
imageUuid String Image UUID 4.1.0
backupStorageUuid String Backup Storage UUID 4.1.0
installPath String Install path on the image repository 4.1.0
exportUrl String Export image URL 4.1.0
exportMd5Sum String Export image MD5 value 4.1.0
status String Image status 4.1.0
createDate Timestamp Creation time 4.1.0
lastOpDate Timestamp Last modification time 4.1.0

SDK Examples

Java SDK
CalculateImageHashAction action = new CalculateImageHashAction();
action.uuid = "383bcf0b1515369a8169b66a91de1e00";
action.backupStorageUuid = "0eeaa5988c743c638485304f3d1f867e";
action.algorithm = "MD5";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CalculateImageHashAction.Result res = action.call();
Python SDK
CalculateImageHashAction action = CalculateImageHashAction()
action.uuid = "383bcf0b1515369a8169b66a91de1e00"
action.backupStorageUuid = "0eeaa5988c743c638485304f3d1f867e"
action.algorithm = "MD5"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
CalculateImageHashAction.Result res = action.call()

GetCandidateImagesForCreatingVm

API Request

URLs
GET zstack/v1/images/primaryStorage/{primaryStorageUuid}/candidate-image
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/images/primaryStorage/f9a502b0665b33faa19c15ebf389408f/candidate-image
Parameter List
Name Type Location Description Allowed Values Starting Version
primaryStorageUuid String url Primary Storage UUID 4.1.1
systemTags (Optional) List query System Tags 4.1.1
userTags (Optional) List query User Tags 4.1.1

API Response

This API returns an empty JSON object {} on success. On error, the returned JSON contains 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 Examples

Java SDK
GetCandidateImagesForCreatingVmAction action = new GetCandidateImagesForCreatingVmAction();
action.primaryStorageUuid = "f9a502b0665b33faa19c15ebf389408f";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetCandidateImagesForCreatingVmAction.Result res = action.call();
Python SDK
GetCandidateImagesForCreatingVmAction action = GetCandidateImagesForCreatingVmAction()
action.primaryStorageUuid = "f9a502b0665b33faa19c15ebf389408f"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetCandidateImagesForCreatingVmAction.Result res = action.call()

SetImageSecurityLevel

API Request

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setImageSecurityLevel": {
    "securityLevel": "low"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"setImageSecurityLevel":{"securityLevel":"low"}}' \
http://localhost:8080/zstack/v1/images/21637a774f6a38738c723d4699a87f72/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Resource UUID, uniquely identifies the resource 0.6
securityLevel (Optional) String body (contained in setImageSecurityLevel structure) Optional. The security level. 0.6
systemTags (Optional) List body System Tags 0.6
userTags (Optional) List body User Tags 0.6

API Response

This API returns an empty JSON object {} on success. On error, the returned JSON contains 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 Examples

Java SDK
SetImageSecurityLevelAction action = new SetImageSecurityLevelAction();
action.uuid = "21637a774f6a38738c723d4699a87f72";
action.securityLevel = "low";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
SetImageSecurityLevelAction.Result res = action.call();v
Python SDK
SetImageSecurityLevelAction action = SetImageSecurityLevelAction()
action.uuid = "21637a774f6a38738c723d4699a87f72"
action.securityLevel = "low"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
SetImageSecurityLevelAction.Result res = action.call()
PreviousImage Storage Related InterfacesNextVM Related Interfaces
API Reference | ZStack ZSphere · ZVF | ZStack Resource Center