文档目录

镜像相关接口

添加镜像(AddImage)

向镜像服务器添加镜像。

API请求

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": true
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中userTags字段可以省略。列出是为了表示body中可以包含这个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
name String body(包含在params结构中) 镜像名称 0.6
description (可选) String body(包含在params结构中) 镜像的详细描述 0.6
url String body(包含在params结构中) 被添加镜像的URL地址 0.6
mediaType (可选) String body(包含在params结构中) 镜像的类型
  • RootVolumeTemplate
  • ISO
  • DataVolumeTemplate
0.6
guestOsType (可选) String body(包含在params结构中) 镜像对应客户机操作系统的类型 0.6
system (可选) boolean body(包含在params结构中) 是否系统镜像 0.6
format (可选) String body(包含在params结构中) 镜像的格式,比如:raw 4.0.0
platform (可选) String body(包含在params结构中) 镜像的系统平台
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
0.6
backupStorageUuids List body(包含在params结构中) 指定添加镜像的镜像服务器UUID列表 0.6
type (可选) String body(包含在params结构中) 内部使用字段 0.6
resourceUuid (可选) String body(包含在params结构中) 资源UUID。若指定,镜像会使用该字段值作为UUID。 0.6
architecture (可选) String body(包含在params结构中)
  • x86_64
  • aarch64
  • mips64el
  • loongarch64
4.0.0
tagUuids (可选) List body(包含在params结构中) 标签UUID列表 4.0.0
systemTags List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6

API返回

返回示例
{
  "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"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 4.0.0
status String 镜像的就绪状态 4.0.0
size Long 镜像大小 4.0.0
actualSize Long 镜像真实容量 4.0.0
md5Sum String 镜像的md5值 4.0.0
url String 镜像的URL地址 4.0.0
mediaType String 镜像的类型 4.0.0
guestOsType String 镜像对应的客户机操作系统类型 4.0.0
type String 内部使用字段 4.0.0
platform String 镜像的系统平台 4.0.0
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 4.0.0
system Boolean 标识是否为系统镜像 4.0.0
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 在镜像服务器上的安装路径 4.0.0
exportUrl String 导出镜像的url 4.0.0
exportMd5Sum String 导出镜像的md5值 4.0.0
status String 镜像就绪状态 4.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6

SDK示例

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请求

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: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth fb8be86094544022ad3e3abd0027b420" \
-X DELETE http://localhost:8080/zstack/v1/images/f92e888c970c4f739d91e59f6dd94b1e?
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 镜像的UUID,唯一标示该子资源 0.6
backupStorageUuids (可选) List body 镜像服务器UUID列表 0.6
deleteMode (可选) String body 删除模式(Permissive 或者 Enforcing, 默认 Permissive) 0.6
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK示例

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请求

URLs
PUT zstack/v1/images/{imageUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "expungeImage": {
    "backupStorageUuids": [
      "ef3843bdde80427e9c8c0d4f05aa5cde"
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
Uuid String body(包含在params结构中) 资源的UUID,唯一标示该资源 0.6
imageUuid String url 镜像UUID 0.6
backupStorageUuids (可选) List body(包含在params结构中) 镜像服务器UUID列表 0.6
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK示例

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请求

URLs
GET zstack/v1/images
GET zstack/v1/images/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
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

可查询字段

运行CLI命令行工具,输入QueryImage并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例
{
    "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示例

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)

恢复被删除(但未彻底删除)的镜像。

API请求

URLs
PUT zstack/v1/images/{imageUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "recoverImage": {
    "backupStorageUuids": [
      "b63989ade2194ce8b8f1823083395681"
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
imageUuid String url 镜像UUID 0.6
backupStorageUuids (可选) List body(包含在params结构中) 镜像服务器UUID列表 0.6
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6

API返回

返回示例
{
  "inventory": {
    "uuid": "c019173f2b5742868058049be43033a1",
    "name": "TinyLinux",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0,
        "imageUuid": "c019173f2b5742868058049be43033a1",
        "backupStorageUuid": "609d29fb59ee414f90cedbc3a71038c6",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
名字 类型 描述 起始版本
success Boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 0.6
status String 镜像的就绪状态 0.6
size Long 镜像大小 0.6
actualSize Long 镜像真实容量 0.6
md5Sum String 镜像的md5值 0.6
url String 镜像的URL地址 0.6
mediaType String 镜像的类型 0.6
guestOsType String 镜像对应的客户机操作系统类型 0.6
type String 内部使用字段 0.6
platform String 镜像的系统平台 0.6
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 0.6
system Boolean 标识是否为系统镜像 0.6
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 在镜像服务器上的安装路径 0.6
exportUrl String 导出镜像的url 0.6
exportMd5Sum String 导出镜像的md5值 0.6
status String 镜像就绪状态 0.6
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6

SDK示例

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请求

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "changeImageState": {
    "stateEvent": "disable"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 镜像的UUID,唯一标示该镜像 0.6
stateEvent String body(包含在params结构中) 镜像的状态
  • enable
  • disable
0.6
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6

API返回

返回示例
{
  "inventory": {
    "uuid": "e4891e6ef3a64ea08ce91ab379a5c856",
    "name": "TinyLinux",
    "url": "http://192.168.1.20/share/images/tinylinux.qcow2",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "qcow2",
    "backupStorageRefs": [
      {
        "id": 0,
        "imageUuid": "e4891e6ef3a64ea08ce91ab379a5c856",
        "backupStorageUuid": "8bf8f2f17e7c4cca8d684ae5d89eee9e",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 0.6
status String 镜像的就绪状态 0.6
size Long 镜像大小 0.6
actualSize Long 镜像真实容量 0.6
md5Sum String 镜像的md5值 0.6
url String 镜像的URL地址 0.6
mediaType String 镜像的类型 0.6
guestOsType String 镜像对应的客户机操作系统类型 0.6
type String 内部使用字段 0.6
platform String 镜像的系统平台 0.6
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 0.6
system Boolean 标识是否为系统镜像 0.6
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 在镜像服务器上的安装路径 0.6
exportUrl String 导出镜像的url 0.6
exportMd5Sum String 导出镜像的md5值 0.6
status String 镜像就绪状态 0.6
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6

SDK示例

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请求

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateImage": {
    "platform": "Windows",
    "virtio": false
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 镜像的UUID,唯一标示该镜像 0.6
name (可选) String body(包含在params结构中) 镜像名称 0.6
description (可选) String body(包含在params结构中) 镜像的详细描述 0.6
guestOsType (可选) String body(包含在params结构中) 镜像对应的客户机操作系统类型 0.6
mediaType (可选) String body(包含在params结构中) 镜像的类型
  • RootVolumeTemplate
  • DataVolumeTemplate
  • ISO
0.6
format (可选) String body(包含在params结构中) 镜像的格式
  • raw
  • qcow2
  • iso
0.6
system (可选) Boolean body(包含在params结构中) 标识是否为系统镜像 0.6
platform (可选) String body(包含在params结构中) 镜像的系统平台
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
0.6
architecture(可选) String body(包含在updateImage结构中)
  • x86_64
  • aarch64
  • mips64el
  • loongarch64
4.0.0
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6
virtio (可选) Boolean body(包含在updateImage结构中) 5.0.0

API返回

返回示例
{
  "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"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 4.0.0
status String 镜像的就绪状态 4.0.0
size Long 镜像大小 4.0.0
actualSize Long 镜像真实容量 4.0.0
md5Sum String 镜像的md5值 4.0.0
url String 镜像的URL地址 4.0.0
mediaType String 镜像的类型 4.0.0
guestOsType String 镜像对应的客户机操作系统类型 4.0.0
type String 内部使用字段 4.0.0
platform String 镜像的系统平台 4.0.0
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 4.0.0
system Boolean 标识是否为系统镜像 4.0.0
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 在镜像服务器上的安装路径 4.0.0
exportUrl String 导出镜像的url 4.0.0
exportMd5Sum String 导出镜像的md5值 4.0.0
status String 镜像就绪状态 4.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6

SDK示例

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请求

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "syncImageSize": {},
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 镜像的UUID,唯一标示该镜像 0.6
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6

API返回

返回示例
{
  "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,
        "imageUuid": "a5288a2598074daabb0450db1eaf0e69",
        "backupStorageUuid": "1a917c0b47c6475a996ed678f230419d",
        "installPath": "ceph://zs-images/f0b149e053b34c7eb7fe694b182ebffd",
        "status": "Ready"
      }
    ]
  }
}
名字 类型 描述 起始版本
success Boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 0.6
status String 镜像的就绪状态 0.6
size Long 镜像大小 0.6
actualSize Long 镜像真实容量 0.6
md5Sum String 镜像的md5值 0.6
url String 镜像的URL地址 0.6
mediaType String 镜像的类型 0.6
guestOsType String 镜像对应的客户机操作系统类型 0.6
type String 内部使用字段 0.6
architecture String 镜像CPU架构 5.0.0
platform String 镜像的系统平台 0.6
format String 镜像的格式,比如:raw 0.6
system Boolean 标识是否为系统镜像 0.6
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 0.6
exportUrl String 0.6
exportMd5Sum String 0.6
status String 0.6
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6

SDK示例

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请求

URLs
DELETE zstack/v1/image-packages/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/image-packages/e7660c815f483befb15905bf6c776781?
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID,唯一标示该资源 4.4.6
deleteMode (可选) String body 删除模式
  • Permissive
  • Enforcing
4.4.6
systemTags (可选) List body 系统标签 4.4.6
userTags (可选) List body 用户标签 4.4.6

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK示例

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请求

URLs
PUT zstack/v1/image-packages/{uuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateImagePackage": {
    "name": "ova-update",
    "description": "description-update"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/image-packages/eeed157556d2328c9c3aeec71ab75463
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID,唯一标示该资源 4.4.6
name (可选) String body(包含在updateImagePackage结构中) 资源名称 4.4.6
description (可选) String body(包含在updateImagePackage结构中) 资源的详细描述 4.4.6
systemTags (可选) List body 系统标签 4.4.6
userTags (可选) List body 用户标签 4.4.6

API返回

返回示例
{
  "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"
  }
}
名字 类型 描述 起始版本
success boolean 4.4.6
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 4.4.6
inventory ImagePackageInventory 详情参考inventory 4.4.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 4.4.6
description String 错误的概要描述 4.4.6
details String 错误的详细信息 4.4.6
elaboration String 保留字段,默认为null 4.4.6
opaque LinkedHashMap 保留字段,默认为null 4.4.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 4.4.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 4.4.6
name String 资源名称 4.4.6
description String 资源的详细描述 4.4.6
vmUuid String 源虚拟机UUID 4.4.6
backupStorageUuid String 镜像包文件位于的镜像存储UUID 4.4.6
exportUrl String 下载地址 4.4.6
md5Sum String 镜像包文件MD5校验码 4.4.6
format String 镜像包文件格式 4.4.6
size Long 镜像包文件大小 4.4.6
createDate Timestamp 创建时间 4.4.6
lastOpDate Timestamp 最后一次修改时间 4.4.6
state ImagePackageState 详情参考state 4.4.6
#state
名字 类型 描述 起始版本
Exporting ImagePackageState 导出中 4.4.6
Exported ImagePackageState 已导出 4.4.6

SDK示例

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请求

URLs
GET zstack/v1/image-packages
GET zstack/v1/image-packages/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/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

可查询字段

运行CLI命令行工具,输入QueryImagePackage并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例
{
  "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"
    }
  ]
}
名字 类型 描述 起始版本
success boolean 4.4.6
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 4.4.6
inventories List 详情参考inventories 4.4.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 4.4.6
description String 错误的概要描述 4.4.6
details String 错误的详细信息 4.4.6
elaboration String 保留字段,默认为null 4.4.6
opaque LinkedHashMap 保留字段,默认为null 4.4.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 4.4.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 4.4.6
name String 资源名称 4.4.6
description String 资源的详细描述 4.4.6
vmUuid String 源虚拟机UUID 4.4.6
backupStorageUuid String 镜像包文件位于的镜像存储UUID 4.4.6
exportUrl String 下载地址 4.4.6
md5Sum String 镜像包文件MD5校验码 4.4.6
format String 镜像包文件格式 4.4.6
size Long 镜像包文件大小 4.4.6
createDate Timestamp 创建时间 4.4.6
lastOpDate Timestamp 最后一次修改时间 4.4.6
state ImagePackageState 详情参考state 4.4.6
#state
名字 类型 描述 起始版本
Exporting ImagePackageState 导出中 4.4.6
Exported ImagePackageState 已导出 4.4.6

SDK示例

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)

获取创建镜像的镜像服务器候选。

API请求

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示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
volumeUuid (可选) String query 云盘UUID,注意:volumeUuid 和 volumeSnapshotUuid 二选一 0.6
volumeSnapshotUuid (可选) String query 云盘快照UUID,注意:volumeUuid 和 volumeSnapshotUuid 二选一 0.6
systemTags (可选) List query 系统标签 0.6
userTags (可选) List query 用户标签 0.6

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK示例

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请求

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: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
name String body(包含在params结构中) 根云盘镜像名称 0.6
description (可选) String body(包含在params结构中) 根云盘镜像的详细描述 0.6
guestOsType (可选) String body(包含在params结构中) 根云盘镜像对应客户机操作系统类型 0.6
backupStorageUuids (可选) List body(包含在params结构中) 镜像服务器UUID列表 0.6
rootVolumeUuid String body(包含在params结构中) 根云盘UUID 0.6
platform (可选) String body(包含在params结构中) 根云盘镜像对应的系统平台
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
0.6
system (可选) boolean body(包含在params结构中) 是否系统根云盘镜像 0.6
resourceUuid (可选) String body(包含在params结构中) 根云盘镜像UUID。若指定,根云盘镜像会使用该字段值作为UUID。 0.6
architecture (可选) String body(包含在params结构中) 4.0.0
tagUuids (可选) List body(包含在params结构中) 标签UUID列表 4.0.0
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6
virtio (可选) boolean body(包含在params结构中) 5.0.0
Note:
  • ZStack Cloud从根云盘创建根云盘镜像时支持从云主机拷贝GuestTools标签值到镜像, 使用该镜像创建云主机时,从镜像拷贝GuestTools标签值到新云主机。SystemTags增加GuestTools选项。
    • 选项格式为:GuestTools::TOOLS_VERSION,其中TOOLS_VERSION初值为1.0.0,未来随着工具版本的提升,这个值会随之变化。
    • 例如:GuestTools::1.0.0
    • 补充说明:云主机根云盘创建镜像时,从云主机拷贝GuestTools标签值到镜像。

API返回

返回示例
{
  "inventory": {
    "uuid": "cad3a82224363f1e8592a7fd0bf419f9",
    "name": "My Root Volume Template",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "architecture": "x86_64",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0,
        "imageUuid": "cad3a82224363f1e8592a7fd0bf419f9",
        "backupStorageUuid": "ac938bdf013b3a94acf679955f69f647",
        "installPath": "ceph://zs-images/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 4.0.0
status String 镜像的就绪状态 4.0.0
size Long 镜像大小 4.0.0
actualSize Long 镜像真实容量 4.0.0
md5Sum String 镜像的md5值 4.0.0
url String 镜像的URL地址 4.0.0
mediaType String 镜像的类型 4.0.0
guestOsType String 镜像对应的客户机操作系统类型 4.0.0
type String 内部使用字段 4.0.0
platform String 镜像的系统平台 4.0.0
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 4.0.0
system Boolean 标识是否为系统镜像 4.0.0
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 在镜像服务器上的安装路径 4.0.0
exportUrl String 导出镜像的url 4.0.0
exportMd5Sum String 导出镜像的md5值 4.0.0
status String 镜像就绪状态 4.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6

SDK示例

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)

从云盘快照创建根云盘镜像。

API请求

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: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
snapshotUuid String url 快照UUID 0.6
name String body(包含在params结构中) 根云盘镜像名称 0.6
description (可选) String body(包含在params结构中) 根云盘镜像的详细描述 0.6
guestOsType (可选) String body(包含在params结构中) 根云盘客户机操作系统类型 0.6
backupStorageUuids List body(包含在params结构中) 镜像服务器UUID列表 0.6
platform (可选) String body(包含在params结构中) 根云盘镜像对应的系统平台
  • Linux
  • Windows
  • WindowsVirtio
  • Other
  • Paravirtualization
0.6
system (可选) boolean body(包含在params结构中) 是否系统根云盘镜像 0.6
resourceUuid (可选) String body(包含在params结构中) 根云盘镜像UUID。若指定,根云盘镜像会使用该字段值作为UUID。 0.6
architecture (可选) String body(包含在params结构中) 4.0.0
tagUuids (可选) List body(包含在params结构中) 标签UUID列表 4.0.0
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6
virtio (可选) boolean body(包含在params结构中) 5.0.0

API返回

返回示例
{
  "inventory": {
    "uuid": "cfe7842a8c1a30a1870965a7d6133760",
    "name": "My Root Volume Template",
    "mediaType": "RootVolumeTemplate",
    "platform": "Linux",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0,
        "imageUuid": "cfe7842a8c1a30a1870965a7d6133760",
        "backupStorageUuid": "f5f16e1618323606a7501b50be251c05",
        "installPath": "ceph://zs-images/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
failures List 详情参考failures 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 4.0.0
status String 镜像的就绪状态 4.0.0
size Long 镜像大小 4.0.0
actualSize Long 镜像真实容量 4.0.0
md5Sum String 镜像的md5值 4.0.0
url String 镜像的URL地址 4.0.0
mediaType String 镜像的类型 4.0.0
guestOsType String 镜像对应的客户机操作系统类型 4.0.0
type String 内部使用字段 4.0.0
platform String 镜像的系统平台 4.0.0
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 4.0.0
system Boolean 标识是否为系统镜像 4.0.0
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 在镜像服务器上的安装路径 4.0.0
exportUrl String 导出镜像的url 4.0.0
exportMd5Sum String 导出镜像的md5值 4.0.0
status String 镜像就绪状态 4.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
#failures
名字 类型 描述 起始版本
backupStorageUuid String 镜像存储UUID 0.6
error ErrorCode 详情参考error 0.6

SDK示例

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请求

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: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
name String body(包含在params结构中) 数据云盘镜像名称 0.6
description (可选) String body(包含在params结构中) 数据云盘镜像的详细描述 0.6
volumeUuid String body(包含在params结构中) 起始云盘UUID 0.6
backupStorageUuids (可选) List body(包含在params结构中) 镜像服务器UUID列表 0.6
resourceUuid (可选) String body(包含在params结构中) 数据云盘镜像UUID。若指定,数据云盘镜像会使用该字段值作为UUID。 0.6
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6
tagUuids(可选) List body(包含在params结构中) 标签UUID 5.0.0

API返回

返回示例
{
  "inventory": {
    "uuid": "7247cf569e2b4104832071822cf845c5",
    "name": "My Data Volume Template",
    "mediaType": "DataVolumeTemplate",
    "platform": "Linux",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0,
        "imageUuid": "7247cf569e2b4104832071822cf845c5",
        "backupStorageUuid": "1b8ab68b7e224a30aa31f00f1db2b5a6",
        "installPath": "ceph://zs-data-volume/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 0.6
status String 镜像的就绪状态 0.6
size Long 镜像大小 0.6
actualSize Long 镜像真实容量 0.6
md5Sum String 镜像的md5值 0.6
url String 镜像的URL地址 0.6
mediaType String 镜像的类型 0.6
guestOsType String 镜像对应的客户机操作系统类型 0.6
type String 内部使用字段 0.6
platform String 镜像的系统平台 0.6
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 0.6
system Boolean 标识是否为系统镜像 0.6
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 0.6
exportUrl String 0.6
exportMd5Sum String 0.6
status String 0.6
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6

SDK示例

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)

从指定的云盘快照创建出一个数据云盘镜像。

API请求

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: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
snapshotUuid String url 快照UUID 0.6
name String body(包含在params结构中) 数据云盘镜像名称 0.6
description (可选) String body(包含在params结构中) 数据云盘镜像的详细描述 0.6
backupStorageUuids List body(包含在params结构中) 镜像服务器UUID列表 0.6
resourceUuid (可选) String body(包含在params结构中) 数据云盘镜像UUID。若指定,数据云盘镜像会使用该字段值作为UUID 0.6
tagUuids (可选) List body(包含在params结构中) 标签UUID列表 0.6
systemTags (可选) List body 系统标签 0.6
userTags (可选) List body 用户标签 0.6

API返回

返回示例
{
  "inventory": {
    "uuid": "314d80c2feb5352c984b3ffd36108c32",
    "name": "My Data Volume Template",
    "mediaType": "DataVolumeTemplate",
    "platform": "Linux",
    "format": "raw",
    "backupStorageRefs": [
      {
        "id": 0,
        "imageUuid": "314d80c2feb5352c984b3ffd36108c32",
        "backupStorageUuid": "d861144baadf31e3b1cbbb282242adcf",
        "installPath": "ceph://zs-images/0cd599ec519249489475112a058bb93a",
        "status": "Ready"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
inventory ImageInventory 详情参考inventory 0.6
failures List 详情参考failures 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
name String 资源名称 0.6
description String 资源的详细描述 0.6
state String 镜像的启动状态 0.6
status String 镜像的就绪状态 0.6
size Long 镜像大小 0.6
actualSize Long 镜像真实容量 0.6
md5Sum String 镜像的md5值 0.6
url String 镜像的URL地址 0.6
mediaType String 镜像的类型 0.6
guestOsType String 镜像对应的客户机操作系统类型 0.6
type String 内部使用字段 0.6
platform String 镜像的系统平台 0.6
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 0.6
system Boolean 标识是否为系统镜像 0.6
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
backupStorageRefs List 详情参考backupStorageRefs 0.6
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 0.6
backupStorageUuid String 镜像存储UUID 0.6
installPath String 在镜像服务器上的安装路径 0.6
exportUrl String 导出镜像的url 0.6
exportMd5Sum String 导出镜像的md5值 0.6
status String 镜像就绪状态 0.6
createDate Timestamp 创建时间 0.6
lastOpDate Timestamp 最后一次修改时间 0.6
#failures
名字 类型 描述 起始版本
backupStorageUuid String 镜像存储UUID 0.6
error ErrorCode 详情参考error 0.6

SDK示例

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()

获取镜像Qga(GetImageQga)

API请求

URLs
GET zstack/v1/images/{uuid}/qga
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth e74211f026f741c1898d4377ecf58bd1" \
-X GET http://localhost:8080/zstack/v1/images/34a5bf0cc1014286bd944771c77e1c07/qga
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID,唯一标示该资源 0.6
systemTags (可选) List query 0.6
userTags (可选) List query 0.6

API返回

返回示例
{
  "enable": false
}
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 0.6
enable boolean 0.6
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 0.6
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段,默认为null 0.6
opaque LinkedHashMap 保留字段,默认为null 0.6
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 0.6

SDK示例

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()

设置镜像Qga(SetImageQga)

API请求

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setImageQga": {
    "enable": true
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID,唯一标示该资源 0.6
enable boolean body(包含在setImageQga结构中) 0.6
systemTags (可选) List body 0.6
userTags (可选) List body 0.6

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK示例

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请求

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setImageBootMode": {
    "bootMode": "Legacy"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID,唯一标示该资源 3.9.0
bootMode String body(包含在setImageBootMode结构中) 镜像启动模式
  • Legacy
  • UEFI
  • UEFI_WITH_CSM
3.9.0
systemTags (可选) List body 系统标签 3.9.0
userTags (可选) List body 用户标签 3.9.0

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK示例

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请求

URLs
GET zstack/v1/images/upload-job/details/{imageId}
Headers
Authorization: OAuth the-session-uuid
Curl示例
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/images/upload-job/details/d41d8cd98f00b204e9800998ecf8427e?
参数列表
名字 类型 位置 描述 可选值 起始版本
imageId String url 上传镜像的唯一标识,由用户自定义,推荐使用 md5 4.1.0
systemTags (可选) List query 系统标签 4.1.0
userTags (可选) List query 用户标签 4.1.0

API返回

返回示例
{
  "existingJobDetails": [
    {
      "longJobUuid": "0792dd52aeb9329cb1e677fae6465f23",
      "longJobState": "Suspended",
      "imageUuid": "ccf943310d86335bb3d2511ca8e14137",
      "imageUploadUrl": "http://127.0.0.1:8001/imagestore/upload",
      "offset": 452984832
    }
  ]
}
名字 类型 描述 起始版本
success boolean 4.1.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 4.1.0
existingJobDetails List 详情参考existingJobDetails 4.1.0
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 4.1.0
description String 错误的概要描述 4.1.0
details String 错误的详细信息 4.1.0
elaboration String 保留字段,默认为null 4.1.0
opaque LinkedHashMap 保留字段,默认为null 4.1.0
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 4.1.0
#existingJobDetails
名字 类型 描述 起始版本
longJobUuid String 长任务UUID 4.1.0
longJobState String 长任务状态 4.1.0
imageUuid String 镜像UUID 4.1.0
imageUploadUrl String 镜像上传URL 4.1.0
offset long 上传偏移量,单位为 Byte 4.1.0

SDK示例

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()

计算镜像的MD5值(CalculateImageHash)

API请求

URLs
PUT zstack/v1/images/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "calculateImageHash": {
    "backupStorageUuid": "0eeaa5988c743c638485304f3d1f867e",
    "algorithm": "MD5"
  },
  "systemTags": [],
  "userTags": []
}
Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源的UUID,唯一标示该资源 5.0.0
backupStorageUuid String body(包含在calculateImageHash结构中) 镜像存储UUID 5.0.0
algorithm (可选) String body(包含在calculateImageHash结构中) 5.0.0
systemTags (可选) List body 系统标签 5.0.0
userTags (可选) List body 用户标签 5.0.0

API返回

返回示例
{
  "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"
      }
    ]
  }
}
名字 类型 描述 起始版本
success boolean 5.0.0
inventory ImageInventory 详情参考inventory 5.0.0
error ErrorCode 错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error 5.0.0
#error
名字 类型 描述 起始版本
code String 错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001 5.0.0
description String 错误的概要描述 5.0.0
details String 错误的详细信息 5.0.0
elaboration String 保留字段,默认为null 5.0.0
opaque LinkedHashMap 保留字段,默认为null 5.0.0
cause ErrorCode 根错误,引发当前错误的源错误,若无原错误,该字段为null 5.0.0
#inventory
名字 类型 描述 起始版本
uuid String 资源的UUID,唯一标示该资源 5.0.0
name String 资源名称 5.0.0
description String 资源的详细描述 5.0.0
state String 镜像的启动状态 5.0.0
status String 镜像的就绪状态 5.0.0
size Long 镜像大小 5.0.0
actualSize Long 镜像真实容量 5.0.0
md5Sum String 镜像的md5值 5.0.0
url String 镜像的URL地址 5.0.0
mediaType String 镜像的类型 5.0.0
guestOsType String 镜像对应的客户机操作系统类型 5.0.0
type String 内部使用字段 5.0.0
platform String 镜像的系统平台 5.0.0
architecture String 镜像CPU架构 5.0.0
format String 镜像的格式,比如:raw 5.0.0
system Boolean 标识是否为系统镜像 5.0.0
virtio Boolean 是否支持virtio 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0
backupStorageRefs List 详情参考backupStorageRefs 5.0.0
#backupStorageRefs
名字 类型 描述 起始版本
imageUuid String 镜像UUID 5.0.0
backupStorageUuid String 镜像存储UUID 5.0.0
installPath String 在镜像服务器上的安装路径 5.0.0
exportUrl String 导出镜像的url 5.0.0
exportMd5Sum String 导出镜像的md5值 5.0.0
status String 镜像就绪状态 5.0.0
createDate Timestamp 创建时间 5.0.0
lastOpDate Timestamp 最后一次修改时间 5.0.0

SDK示例

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()
开发手册 | 5.5.30 | ZStack Cloud · ZCF | ZStack 资源中心