制作镜像
功能介绍
本接口用于制作私有镜像,支持:
- 使用云服务器制作私有镜像(系统盘镜像/数据盘镜像)。
- 使用上传至OBS桶中的外部镜像文件制作系统盘镜像。
- 使用数据盘制作系统盘镜像。
作为异步接口,调用成功,只是说明云平台收到了制作请求,镜像是否制作成功需要通过异步任务查询接口查询该任务的执行状态,具体请参考异步任务查询。
约束与限制
- 使用外部镜像文件制作镜像
外部镜像文件的限制请参见“准备镜像文件(Windows)”或“准备镜像文件(Linux)”。
- 使用数据盘创建系统盘镜像
使用数据盘制作系统盘镜像时,需确保该数据盘中有操作系统,且操作系统已提前完成优化步骤。如何优化,请参见优化私有镜像(Windows)和优化私有镜像(Linux)。
由于系统无法校验您在调用该接口时指定的卷是否存在操作系统,因此制作系统盘镜像时,请务必确保您输入的os_version(操作系统版本)值合法,具体请参见相关参数取值列表。
调试
您可以在API Explorer中调试该接口。
URI
POST /v2/cloudimages/action
请求消息
- 使用云服务器制作镜像(系统盘镜像/数据盘镜像)时的请求参数
参数
是否必选
参数类型
描述
name
是
String
系统盘镜像名称。name参数说明请参考镜像属性。
description
否
String
镜像描述信息。description参数说明请参考镜像属性。支持字母、数字、中文等,不支持回车、<、>,长度不能超过1024个字符。默认为空。
instance_id
是
String
用于制作镜像的源云服务器ID。
如何获取云服务器ID:
- 登录控制台。
- 选择“计算 > 弹性云服务器”。
- 在云服务器列表栏,单击源云服务器名称,在详情页查看ID。
data_images
否
Array of objects
需要转换的数据盘信息,其中,当使用云服务器上的数据盘进行私有数据盘镜像创建时,该字段必选,详情请参见表1。
如果不是用于制作数据盘镜像,该字段默认为空。
说明:当需要用数据盘创建数据盘镜像时,此表中的其他参数(如name、description、tags)如果有值,系统以data_images中的值为准,不允许再输入instance_id。
tags
否
Array of strings
镜像标签列表。默认为空。
tags和image_tags只能使用一个。
image_tags
否
Array of objects
新规范的镜像标签列表。默认为空。
tags和image_tags只能使用一个。
image_tags数据结构说明请参见表3。
enterprise_project_id
否
String
表示当前镜像所属的企业项目。
- 取值为0或无该值,表示属于default企业项目。
- 取值为UUID,表示属于该UUID对应的企业项目。
关于企业项目ID的获取及企业项目特性的详细信息,请参考“企业中心总览”。
max_ram
否
Integer
表示镜像支持的最大内存,单位为MB。
min_ram
否
Integer
表示镜像支持的最小内存,单位为MB,默认为0,表示不受限制。
- 使用上传至OBS桶中的外部镜像文件时的请求参数
参数
是否必选
参数类型
描述
name
是
String
镜像名称。name参数说明请参考镜像属性。
description
否
String
镜像描述信息。description参数说明请参考镜像属性。支持字母、数字、中文等,不支持回车、<、>,长度不能超过1024个字符。默认为空。
os_type
否
String
操作系统类型。
取值为Linux、Windows、Other。
os_version
否
String
操作系统版本。
使用上传至OBS桶中的外部镜像文件制作镜像时生效,具体取值见相关参数取值列表。
说明:如果上传的文件为ISO格式,则该参数为必填参数。
当“is_quick_import”的值为“true”时,即使用镜像文件快速导入方式导入系统盘镜像,则该参数为必填参数。
image_url
是
String
OBS桶中外部镜像文件地址。
在使用OBS桶的外部镜像文件制作镜像时生效且为必选字段。格式为<OBS桶名>:<OBS镜像文件名称>。
- “OBS桶名”获取方式:
- “OBS镜像文件名称”获取方式:
说明:此处的OBS桶和镜像文件的存储类别必须是OBS标准存储。
min_disk
是
Integer
最小系统盘大小。
在使用OBS桶的外部镜像文件制作镜像时生效且为必选字段。linux操作系统取值为10~1024GB,Windows操作系统取值为20~1024GB。
is_config
否
Boolean
是否自动配置。
取值为true或false。
如果需要后台自动配置,取值为true,否则为false。默认取值为false。
后台自动配置的内容请参考“注册镜像(Linux)”。
cmk_id
否
String
创建加密镜像的自定义密钥,具体取值请参考“查看密钥”获取。
tags
否
Array of strings
镜像标签列表。默认为空。
tags和image_tags只能使用一个。
image_tags
否
Array of objects
新规范的镜像标签列表。默认为空。tags和image_tags只能使用一个。
image_tags数据结构说明请参见表3。
type
否
String
镜像的类型。
取值为ECS、BMS、FusionCompute、Ironic、IsoImage。默认使用“ECS”。
- ECS/FusionCompute:表示是ECS服务器的镜像。
- BMS/Ironic:表示是BMS服务器的镜像。
- IsoImage:表示是使用ISO文件创建的镜像。
enterprise_project_id
否
String
表示当前镜像所属的企业项目。
- 取值为0或无该值,表示属于default企业项目。
- 取值为UUID,表示属于该UUID对应的企业项目。
关于企业项目ID的获取及企业项目特性的详细信息,请参考“企业中心总览”。
max_ram
否
Integer
表示镜像支持的最大内存,单位为MB。
min_ram
否
Integer
表示镜像要求的最小内存,单位为MB,默认为0,表示不受限制。
data_images
否
Array of objects
需要导入的数据盘信息。
外部镜像文件最多可携带3块数据盘,此时系统会创建1块系统盘、3块数据盘。
详情请参见表2。
说明:- 使用数据盘镜像文件创建数据盘镜像时,数据盘镜像的操作系统类型将和系统盘镜像保持一致。
- 表2中的其他参数(如name、description、tags)如果有值,系统以data_images中的值为准。
is_quick_import
否
Boolean
是否使用镜像文件快速导入方式,导入系统盘镜像。
- 是,配置为true。
- 否,配置为false。
关于镜像文件快速导入的约束与限制请参见镜像文件快速导入。
architecture
否
String
镜像的架构类型。取值包括:
- x86
- arm
默认使用“x86”。
说明:当架构类型为arm时,镜像引导方式将自动转为UEFI。
表2 data_images字段说明 参数
是否必选
参数类型
描述
name
否
String
镜像名称。
name参数说明请参见镜像属性。
description
否
String
镜像描述信息。默认为空。
支持字母、数字、中文等,不支持回车、<、>,长度不能超过1024个字符。
description参数说明请参见镜像属性。
image_url
是
String
OBS桶中外部镜像文件地址。
格式为“<OBS桶名>:<OBS镜像文件名称>”。
- “OBS桶名”获取方式:
- “OBS镜像文件名称”获取方式:
说明:此处的OBS桶和镜像文件的存储类别必须是OBS标准存储。
min_disk
是
Integer
最小数据盘大小。
单位:GB
取值范围:1~2048GB
is_quick_import
否
Boolean
当前数据盘镜像是否使用镜像文件快速导入方式,创建数据盘镜像。
- 是,配置为true。
- 否,配置为false。
关于镜像文件快速导入的约束与限制请参见镜像文件快速导入。
tags
否
Array of strings
镜像标签列表。默认为空。
tag的参数说明请参见镜像标签数据格式。
tags和image_tags只能使用一个。
image_tags
否
Array of objects
新规范的镜像标签列表。默认为空。
tags和image_tags只能使用一个。
image_tags参数说明请参见镜像标签数据格式。
image_tags数据结构说明请参见表3。
- 使用数据盘制作系统盘镜像时的请求参数
参数
是否必选
参数类型
描述
name
是
String
系统盘镜像名称。
name参数说明请参见镜像属性。
volume_id
是
String
数据盘的卷ID。
os_version
是
String
操作系统版本。
os_version的具体取值请参见相关参数取值列表,请严格按照列表要求填写该值,否则可能会引起制作的系统盘镜像不可用。
制作系统盘镜像过程中,如果系统能获取到卷中的操作系统,则以卷中的操作系统版本为准,此时,设置的os_version无效。如果系统无法获取到卷中的操作系统,此时,系统以输入的os_version版本为准。
type
否
Sting
镜像的类型。
取值为ECS、BMS、FusionCompute、Ironic。
- ECS/FusionCompute:表示是云服务器的镜像。
- BMS/Ironic:表示是裸金属服务器的镜像。
默认使用ECS。
description
否
String
镜像描述信息,默认为空。
参数说明请参见镜像属性。
- 支持字母、数字、中文等。
- 不支持回车、<、>。
- 长度不能超过1024个字符。
min_ram
否
Integer
镜像运行需要的最小内存,单位为MB。
参数取值依据云服务器的规格限制,默认设置为0。
云服务器的规格限制,请参见规格清单。
max_ram
否
Integer
镜像运行需要的最大内存,单位为MB。
参数取值依据云服务器的规格限制,默认设置为0。
云服务器的规格限制,请参见规格清单。
tags
否
Array of strings
镜像标签列表,默认为空。
tags和image_tags只能使用一个。
image_tags
否
Array of objects
新规范的镜像标签列表,默认为空。
tags和image_tags只能使用一个。
image_tags数据结构说明请参见表3。
enterprise_project_id
否
String
表示当前镜像所属的企业项目。
- 取值为0或无该值,表示属于default企业项目。
- 取值为UUID,表示属于该UUID对应的企业项目。
关于企业项目ID的获取及企业项目特性的详细信息,请参考“企业中心总览”。
请求示例
- 使用云服务器制作系统盘镜像,其中,镜像标签数据格式为tags,虚拟机ID为“877a2cda-ba63-4e1e-b95f-e67e48b6129a”。
POST https://{Endpoint}/v2/cloudimages/action { "name": "ims_test", "description": "云服务器制作系统盘镜像", "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }
- 使用云服务器数据盘制作数据盘镜像,其中,镜像标签数据格式为tags,卷ID为“c5dfbd0c-bf0a-4798-a453-61dc6b54aa30”。
1 2 3 4 5 6 7 8 9 10 11 12
POST https://{Endpoint}/v2/cloudimages/action { "data_images": [{"name": "ims_data_image_test", "description": "云服务器数据盘制作数据盘镜像", "volume_id": "c5dfbd0c-bf0a-4798-a453-61dc6b54aa30", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }] }
- 使用上传至OBS桶中的外部镜像文件制作镜像,其中,镜像标签数据格式为tags,OBS桶中外部镜像文件地址为“ims-image:centos70.qcow2”。
1 2 3 4 5 6 7 8 9 10 11 12 13
POST https://{Endpoint}/v2/cloudimages/action { "name": "ims_test_file", "description": "OBS文件制作镜像", "image_url": "ims-image:centos70.qcow2", "os_version": "CentOS 7.0 64bit", "min_disk": 40, "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }
- 使用云服务器制作系统盘镜像,其中,镜像标签数据格式为image_tags,虚拟机ID为“877a2cda-ba63-4e1e-b95f-e67e48b6129a”。
POST https://{Endpoint}/v2/cloudimages/action { "name": "ims_test", "description": "云服务器制作系统盘镜像", "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "image_tags": [ { "key": "key2", "value": "value2" }, { "key": "key1", "value": "value1" } ] }
- 使用云服务器数据盘制作数据盘镜像,其中,镜像标签数据格式为image_tags,卷ID为“c5dfbd0c-bf0a-4798-a453-61dc6b54aa30”。
1 2 3 4 5 6 7 8
POST /v2/cloudimages/action { "data_images": [{"name": "ims_data_image_test", "description": "云服务器数据盘制作数据盘镜像", "volume_id": "c5dfbd0c-bf0a-4798-a453-61dc6b54aa30", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }] }
- 使用上传至OBS桶中的外部镜像文件制作镜像,其中,镜像标签数据格式为image_tags,OBS桶中外部镜像文件地址为“ims-image:centos70.qcow2”。
1 2 3 4 5 6 7 8 9
POST https://{Endpoint}/v2/cloudimages/action { "name": "ims_test_file", "description": "OBS文件制作镜像", "image_url": "ims-image:centos70.qcow2", "os_version": "CentOS 7.0 64bit", "min_disk": 40, "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }
- 使用数据盘制作系统盘镜像,其中,镜像标签数据格式为tags,卷ID为 "877a2cda-ba63-4e1e-b95f-e67e48b6129a"。
1 2 3 4 5 6 7 8 9 10 11 12 13
POST https://{Endpoint}/v2/cloudimages/action { "name": "ims_test", "description": "数据盘制作系统盘镜像", "volume_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "type": "ECS", "os_version": "CentOS 7.0 64bit", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }
- 使用数据盘制作系统盘镜像,其中,镜像标签数据格式为image_tags,卷ID为“877a2cda-ba63-4e1e-b95f-e67e48b6129a”。
1 2 3 4 5 6 7 8 9
POST https://{Endpoint}/v2/cloudimages/action { "name": "ims_test", "description": "数据盘制作系统盘镜像", "volume_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "type": "ECS", "os_version": "CentOS 7.0 64bit", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }
响应消息
- 响应参数
参数
参数类型
描述
job_id
String
异步任务ID。
详情请参见异步任务查询。
- 响应样例
STATUS CODE 200
1 2 3
{ "job_id": "8a12fc664fb4daa3014fb4e581380005" }
返回值
- 正常
- 异常
返回值
说明
400 Bad Request
请求错误,具体返回错误码请参见错误码。
401 Unauthorized
鉴权失败。
403 Forbidden
没有操作权限。
404 Not Found
找不到资源。
500 Internal Server Error
服务内部错误。
503 Service Unavailable
服务不可用。