接口功能介绍
使用存在对象存储的桶上的指定的镜像文件来创建 1 份云主机私有镜像。
准备:
1. 在调用前需了解如何构造请求,可参见:如何调用 API - 构造请求。
2. OpenAPI 请求需进行加密调用,可参见:如何调用 API - 认证鉴权。
注意:
1. 在调用前,请您认真阅读此文档,包括但不限于参数描述中的“注意”部分。
2. 此接口在多可用区资源池中可响应创建中的私有镜像的 imageID。此时,若您欲删除镜像状态为 error 的私有镜像,则可使用删除私有镜像接口来删除 1 份私有镜像。
3. 此接口在非多可用区资源池中可响应创建中的私有镜像的 taskID。此时,若您欲删除镜像状态为 error 的私有镜像,则可使用删除创建私有镜像(镜像文件)任务接口来删除 1 个失败的使用镜像文件来创建私有镜像的任务。
接口约束
接口请求成功需至少满足:
1. 您具有调用此接口的权限。
2. 传入的有取值范围的参数的值在取值范围内且满足要求。
3. 传入的 imageFileSource 参数所指定的镜像文件地址满足要求。
4. 传入的 imageProperties.description 参数所指定的描述信息满足要求。
5. 传入的 imageProperties.imageName 参数所指定的镜像名称满足要求。
6. 传入的 imageProperties.imageType 参数所指定的镜像类型满足要求。
7. 传入的 labels 参数所指定的标签列表满足要求。
8. 传入的 projectID 参数所指定的企业项目对您而言是存在的。
9. 传入的 regionID 参数所指定的资源池对您而言是存在的。
10. 您的私有镜像配额余量足够,即可创建的私有镜像数量未达上限。
URI
POST /v4/image/import
路径参数
无
Query参数
无
请求参数
请求头header参数
无
请求体body参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
imageFileSource | 是 | String | 镜像文件地址,即存储桶内对象的 URL。可使用校验镜像文件地址接口来校验 1 个镜像文件地址。注意: 1. 格式应为 {internetEndpoint}/{bucket}/{key}。可使用访问控制 endpoint 查询接口来查询外网 endpoint,可使用查询所有桶接口来查询您拥有的桶的列表,可使用查询桶信息接口来查询 1 个桶的详细信息,可使用查看对象列表接口来查询存储桶内所有对象,可使用查询对象是否存在接口来查询 1 个对象的详细信息,可使用获取对象 ACL 接口来查询 1 个对象的访问权限控制列表。 2. 所指向的桶应是属于您的、存储类型为 STANDARD、未加密的桶。 3. 所指向的对象应是所指向的桶内的存储类型为 STANDARD、未加密的对象。此对象在非多可用区资源池中还应可公共读。您需自行确保此对象是 QCOW2、RAW、VHD 或 VMDK 格式的镜像文件。 4. 在 imageProperties.imageType 参数值为空(系统盘镜像)时,所指向的对象的大小应不超过您所能创建的 1 份私有系统盘镜像的最大大小。 5. 在 imageProperties.imageType 参数值为 data_disk_image 时,所指向的对象的大小应不超过您所能创建的 1 份私有数据盘镜像的最大大小。 6. 在 imageProperties.imageType 参数值为 iso_image 时,所指向的对象的大小应不超过 1099511627776 bytes(即 1 TiB)。 |
https://xxx.zos.ctyun.cn/bucket-xxx/image-xxx | |
imageProperties | 是 | Object | 镜像属性。 | imageProperties | |
regionID | 是 | String | 资源池 ID。可使用资源池列表查询接口来查询您可见的资源池的列表。 | 88f8888888dd88ec888888888d888d8b | |
enableImageIntegrityCheck | 否 | Boolean | 用于表示是否启用镜像完整性校验的标识。默认 false。注意:仅在传入的 regionID 参数所指定的资源池具备镜像完整性校验功能时生效。 | false | |
labels | 否 | Array of Objects | 标签列表。注意: 1. 列表中最多 10 个标签。 2. 标签键不可重复。 3. 单个标签键或值应满足长度为 1~32 个字符,不能换行,且不能以空格开头或结尾。 4. 若传入的 regionID 参数所指定的资源池是非多可用区资源池,则此参数仅在此资源池具备从镜像文件创建私有镜像时设置标签的功能时生效。 |
labels | |
projectID | 否 | String | 企业项目 ID。默认 0(即 default 企业项目)。可使用查询企业项目列表接口来查询您可以使用的企业项目 ID。 | 0 |
表 imageProperties
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
imageName | 是 | String | 镜像名称。注意: 1. 长度为 2~32 个字符,只能由数字、字母、- 组成,不能以数字、- 开头,且不能以 - 结尾。 2. 不能与您已有的私有镜像的名称重复。可使用查询可以使用的镜像资源接口来查询您已有的私有镜像。 |
CTyunOS-test | |
architecture | 否 | String | 系统架构。取值范围(值:描述): x86_64:x86_64 架构(默认值)。 aarch64:AArch64 架构。 注意: 1. 在 imageProperties.imageType 参数值为 data_disk_image 时不会生效。 2. 在 imageProperties.imageType 参数值为 iso_image 或在传入的 regionID 参数所指定的资源池不具备从镜像文件创建 AArch64 架构的私有镜像的功能时将始终使用默认值。 |
x86_64 | |
bootMode | 否 | String | x86_64 架构非数据盘镜像的启动方式。取值范围(值:描述): bios:BIOS 启动方式(默认值)。 uefi:UEFI 启动方式。 注意:仅在以下条件均满足时生效。 1. imageProperties.architecture 参数值为 x86_64。 2. imageProperties.imageType 参数值为空(系统盘镜像)。 3. 传入的 regionID 参数所指定的资源池具备 x86_64 UEFI 启动方式功能。 |
bios | |
description | 否 | String | 描述信息。注意:长度为 1~128 个字符,不能以空格开头或结尾。 | Test CTyunOS | |
diskSize | 否 | Integer | 磁盘容量。单位为 GiB。默认 40。注意: 1. 在 imageProperties.imageType 参数值为空(系统盘镜像)时,最小 40,最大为您所能创建的 1 份私有系统盘镜像的最大大小。 2. 在 imageProperties.imageType 参数值为 data_disk_image 时,最小 10,最大为您所能创建的 1 份私有数据盘镜像的最大大小。 3. 在 imageProperties.imageType 参数值为 iso_image 时,最小 40,最大 1024。 4. 若传入的值小于最小值,则自动调整为最小值。若传入的值大于最大值,则自动调整为最大值。 温馨提示:若传入的值小于传入的 imageFileSource 参数所指定的镜像文件的虚拟大小,则所创建的镜像的磁盘容量将是此虚拟大小。 |
40 | |
imageType | 否 | String | 镜像类型。取值范围(值:描述): (空,即 null 或空字符串):系统盘镜像(默认值)。 data_disk_image:数据盘镜像。 iso_image:ISO 镜像。 注意:仅在传入的 regionID 参数所指定的资源池具备从镜像文件创建私有系统盘镜像的功能时可使用默认值。数据盘镜像和 ISO 镜像同理。 |
data_disk_image | |
maximumRAM | 否 | Integer | 最大内存。单位为 GiB。取值范围:0(默认值,即不限制)/1/2/4/8/16/32/64/128/256/512。注意: 1. 若同时限制最大和最小内存,则最大内存不能小于最小内存。 2. 仅在传入的 regionID 参数所指定的资源池具备设置最大/最小内存的功能且 imageType 参数值为空(系统盘镜像)时生效。 |
0 | |
minimumRAM | 否 | Integer | 最小内存。单位为 GiB。取值范围:0(默认值,即不限制)/1/2/4/8/16/32/64/128/256/512。注意: 1. 若同时限制最大和最小内存,则最大内存不能小于最小内存。 2. 仅在传入的 regionID 参数所指定的资源池具备设置最大/最小内存的功能且 imageType 参数值为空(系统盘镜像)时生效。 |
0 | |
osDistro | 否 | String | 操作系统发行版。取值范围(值:描述): Other Linux:不归属明确列出的操作系统发行版的 Linux 系统(默认值)。 AlmaLinux:AlmaLinux 操作系统。 Anolis:龙蜥操作系统。 CTyunOS:天翼云服务器操作系统。 CentOS:社区企业操作系统(Community ENTerprise Operating System)。 Debian:Debian 操作系统。 Fedora:Fedora 操作系统。 KylinOS:银河麒麟操作系统。 Linx:凝思操作系统。 NFSChina:中科方德操作系统。 Other Windows:不归属明确列出的操作系统发行版的 Windows 系统。 RedHat:红帽操作系统。 Rocky Linux:Rocky Linux 操作系统。 SUSE:SUSE 操作系统。 Ubuntu:Ubuntu 操作系统。 UnionTechOS:统信操作系统。 Windows Server:Windows Server 操作系统。 openEuler:openEuler 操作系统。 openSUSE:openSUSE 操作系统。 注意:在 imageType 参数值为 data_disk_image 时不会生效,但您仍需传入此参数或使用默认值来使镜像条目按您的预期区分 Linux 或 Windows。 |
CTyunOS | |
osVersion | 否 | String | 操作系统版本。默认与 osDistro 参数值一致。注意: 1. 长度为 1~32 个字符,不能换行,且不能以空格开头或结尾。 2. 在 imageType 参数值为 data_disk_image 时不会生效。 |
23.01 |
表 labels
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
labelKey | 是 | String | 标签键。 | test-key | |
labelValue | 是 | String | 标签值。 | test-value |
响应参数
参数 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|
statusCode | Integer | 状态码。取值范围(值:描述): 800:成功。 900:失败。 |
800 | |
error | String | 错误码(product.module.code 三段式码)。 | Openapi.PatternCheck.NotValid | |
errorCode | String | 同 error 参数。 | Openapi.PatternCheck.NotValid | |
message | String | 响应状态描述(一般为英文)。 | SUCCESS | |
description | String | 响应状态描述(一般为中文)。 | 成功 | |
returnObj | Object | 成功时返回的数据。 | returnObj |
表 returnObj
参数 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|
images | Array of Objects | 镜像列表。应包含 1 个镜像。 | image |
表 image
参数 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|
appVersion | String | 应用版本。 | 19.03.9 | |
architecture | String | 系统架构。取值范围与对应的请求参数相同。 | x86_64 | |
azName | String | 在多可用区资源池下物理机镜像的可用区名称。 | cn-huadong1-jsnj1A-public-ctcloud | |
bootMode | String | x86_64 架构非数据盘镜像的启动方式。取值范围(值:描述): bios:BIOS 启动方式。 uefi:UEFI 启动方式。 |
bios | |
chargeableImage | Boolean | 用于表示是否是收费镜像的标识。 | false | |
containerFormat | String | 容器格式。 | bare | |
createdTime | Integer | 创建时间戳。 | 1698145871 | |
createdTimeStr | String | 创建时间。 | 2023-10-24T11:11:11Z | |
cwaiType | String | 云骁智算云主机节点类型。取值范围(值:描述): control:控制面云主机节点。 node:GPU 云主机节点。 注意:镜像可适用于多节点类型,多个云骁智算云主机节点类型之间以英文逗号(,)分隔,如 control,node。 |
control | |
description | String | 描述信息。 | Test CTyunOS | |
destinationAccountID | String | 共享镜像接受者的账号 ID。 | 8888f88ee8888fddbdb888bef888e8fe | |
destinationUser | String | 共享镜像接受者。 | test@test.com | |
diskFormat | String | 磁盘格式。取值范围(值:描述): qcow2:QCOW2 格式。 raw:RAW 格式。 vhd:VHD 格式。 vmdk:VMDK 格式。 |
raw | |
diskID | String | 私有镜像来源的系统盘/数据盘 ID。 | 8888a888-b888-8888-a888-baee8d8ce88c | |
diskSize | Integer | 磁盘容量。单位为 GiB。 | 40 | |
enableImageIntegrityCheck | Boolean | 用于表示是否启用镜像完整性校验的标识。 | false | |
fullECSDiskSize | Integer | 云主机整机磁盘容量。单位为 GiB。 | 50 | |
gpuImageCategory | String | GPU 镜像种类。取值范围(值:描述): pass_through:GPU 直通镜像。 vgpu:vGPU 镜像。 |
pass_through | |
hasAcceptedSharedImages | Boolean | 用于表示私有镜像的共享列表中是否有镜像状态为 accepted 的共享镜像的标识。 | false | |
imageClass | String | 镜像类别。取值范围(值:描述): BMS:物理机。 ECS:云主机。 |
ECS | |
imageDisplayName | String | 镜像展示名称。 | CTyunOS 23.01 64 位 | |
imageID | String | 镜像 ID。 | 8d8e8888-8ed8-88b8-88cb-888f8b8cf8fa | |
imageIntegrityCheckStatus | String | 镜像完整性校验状态。取值范围(值:描述): abnormal:异常。 check_fail:非完整。 check_processing:校验中。 check_success:完整。 compute_processing:HMAC 计算中。 compute_success:未校验。 |
check_success | |
imageName | String | 镜像名称。 | CTyunOS-test | |
imageScene | String | 镜像场景。取值范围(值:描述): dev:开发工具。 ecommerce:电商。 gaming:游戏。 website:网站。 注意:镜像可适用于多场景,多个镜像场景之间以英文逗号(,)分隔,如 ecommerce,website。 |
dev | |
imageShareCount | Integer | 私有镜像的共享数量。 | 0 | |
imageSize | Long | 镜像大小。单位为 byte。 | 42949672960 | |
imageSource | String | 私有镜像来源。取值范围(值:描述): cloud_server:云主机。 full_ecs:云主机整机。 image_file:镜像文件。 metal_server:物理机。 snapshot:云主机快照。 |
cloud_server | |
imageStatus | String | 镜像状态。取值范围(值:描述): accepted:已接受共享镜像。 active:正常。 deactivated:已弃用。 deactivating:弃用中。 deleted:已删除。 deleting:删除中。 error:错误。 queued:排队中/创建中。 reactivating:取消弃用中。 rejected:已拒绝共享镜像。 saving:保存中。 waiting:等待接受/拒绝共享镜像。 |
rejected | |
imageSubcategory | String | 镜像子种类。取值范围(值:描述): app:云主机应用镜像。 thin_app:轻量型云主机应用镜像。 注意:镜像可适用于多子种类,多个镜像子种类之间以英文逗号(,)分隔,如 app,thin_app。 |
app | |
imageType | String | 镜像类型。取值范围(值:描述): (空,即 null):系统盘镜像。 data_disk_image:数据盘镜像。 full_ecs_image:整机镜像。 iso_image:ISO 镜像。 |
data_disk_image | |
imageVisibility | String | 镜像可见类型。取值范围(值:描述): private:私有镜像。 public:公共镜像。 shared:共享镜像。 safe:安全产品镜像。 community:甄选镜像。 app:应用镜像。 |
private | |
maximumRAM | Integer | 最大内存。单位为 GiB。 | 0 | |
minimumRAM | Integer | 最小内存。单位为 GiB。 | 0 | |
osDistro | String | 操作系统发行版。 | CTyunOS | |
osType | String | 操作系统类型。取值范围(值:描述): linux:Linux 系操作系统。 windows:Windows 系操作系统。 |
linux | |
osVersion | String | 操作系统版本。 | 23.01 | |
projectID | String | 企业项目 ID。 | 0 | |
sourceAccountID | String | 共享镜像提供者的账号 ID。 | a88fc8888a8a8b8e8f8888888d888ed8 | |
sourceServerID | String | 私有镜像来源的云主机/云主机快照/物理机 ID。 | 88f888ea-88ff-88ec-a8bc-888888888fe8 | |
sourceUser | String | 共享镜像提供者。 | ims-test@test.com | |
supportOneClickSFSMount | Boolean | 用于表示是否支持一键挂载文件系统的标识。 | false | |
supportXSSD | Boolean | 用于表示是否支持 XSSD 类型盘的标识。 | false | |
taskID | String | 任务 ID。 | 8d8e8888-8ed8-88b8-88cb-888f8b8cf8fa | |
updatedTime | Integer | 更新时间戳。 | 1698145871 | |
updatedTimeStr | String | 更新时间。 | 2023-10-24T11:11:11Z |
枚举参数
无
请求示例
请求url
无
请求头header
无
请求体body
示例 1:在华东 1 使用镜像文件来创建 1 份云主机私有系统盘镜像。
{
"imageFileSource": "https://jiangsu-10.zos.ctyun.cn/ims-openapi/ImportSystemDiskImage.qcow2",
"imageProperties": {
"architecture": "aarch64",
"diskSize": 40,
"imageName": "CTyunOS-test",
"maximumRAM": 2,
"osDistro": "CTyunOS",
"osVersion": "23.01"
},
"labels": [{ "labelKey": "test-key", "labelValue": "test-value" }],
"regionID": "bb9fdb42056f11eda1610242ac110002"
}
示例 2:在华东 1 使用镜像文件来创建 1 份云主机私有数据盘镜像。
{
"imageFileSource": "https://jiangsu-10.zos.ctyun.cn/ims-openapi/ImportDataDiskImage.qcow2",
"imageProperties": {
"diskSize": 10,
"imageName": "CTyunOS-test",
"imageType": "data_disk_image",
"osDistro": "CTyunOS"
},
"labels": [{ "labelKey": "test-key", "labelValue": "test-value" }],
"regionID": "bb9fdb42056f11eda1610242ac110002"
}
响应示例
{
"returnObj": {
"images": [
{
"appVersion": null,
"architecture": "x86_64",
"azName": null,
"bootMode": "bios",
"chargeableImage": false,
"containerFormat": "bare",
"createdTime": 1698145871,
"createdTimeStr": "2023-10-24T11:11:11Z",
"cwaiType": null,
"description": "Test CTyunOS",
"destinationAccountID": null,
"destinationUser": null,
"diskFormat": "raw",
"diskID": null,
"diskSize": 40,
"enableImageIntegrityCheck": false,
"fullECSDiskSize": null,
"gpuImageCategory": null,
"hasAcceptedSharedImages": false,
"imageClass": "ECS",
"imageDisplayName": null,
"imageID": "8d8e8888-8ed8-88b8-88cb-888f8b8cf8fa",
"imageIntegrityCheckStatus": null,
"imageName": "CTyunOS-test",
"imageScene": null,
"imageShareCount": 0,
"imageSize": 42949672960,
"imageSource": "image_file",
"imageStatus": "queued",
"imageSubcategory": null,
"imageType": null,
"imageVisibility": "private",
"maximumRAM": 0,
"minimumRAM": 0,
"osDistro": "CTyunOS",
"osType": "linux",
"osVersion": "23.01",
"projectID": "0",
"sourceAccountID": null,
"sourceServerID": null,
"sourceUser": null,
"supportOneClickSFSMount": false,
"supportXSSD": false,
"taskID": null,
"updatedTime": 1698145871,
"updatedTimeStr": "2023-10-24T11:11:11Z"
}
]
},
"errorCode": "",
"message": "SUCCESS",
"description": "成功",
"statusCode": 800
}
状态码
请参考 状态码
错误码
请参考 错误码