# 制作整机镜像 - CreateWholeImage #### 功能介绍 使用云服务器、云服务器备份或者云备份制作整机镜像。作为异步接口，调用成功，只是说明后台收到了制作整机镜像的请求，镜像是否制作成功需要通过异步任务查询接口查询该任务的执行状态，具体请参考[异步任务进度查询 - ShowJobProgress](https://support.huaweicloud.com/api-ims/ims_03_0911.html)。 #### 约束与限制（使用云服务器制作整机镜像） - 创建整机镜像时，请确保弹性云服务器已完成相关配置，否则可能导致整机镜像创建弹性云服务器失败。 详情请参见"[创建私有镜像前云服务器、裸金属服务器或镜像文件需要完成哪些初始化配置？](https://support.huaweicloud.com/ims_faq/ims_faq_0022.html)"。 - 使用Windows操作系统弹性云服务器制作整机镜像时，不允许弹性云服务器存在跨区卷，否则制作的整机镜像创建弹性云服务器时可能会导致数据丢失。 - 使用Linux操作系统弹性云服务器制作整机镜像时，不允许弹性云服务器存在由多个物理卷组成的卷组、或由多个物理卷组成的逻辑卷，否则制作的整机镜像创建弹性云服务器时可能会造成数据丢失。 - 带有专属分布式存储磁盘的云服务器不支持创建整机镜像。 - 不支持将整机镜像发布为市场镜像。 - 不支持将整机镜像导出到本地使用。 - 不支持同区域内复制整机镜像。 - 跨区域复制整机镜像各区域存在差异，请以控制台界面显示为准。 对于不支持跨区域复制的情况，您可以使用整机镜像创建云服务器，再分别创建系统盘镜像和数据盘镜像，然后跨区域复制到目标区域，实现整机镜像的跨区域复制功能。 对于使用弹性云服务器备份创建的整机镜像，仅支持对当前区域生成的备份执行跨区域复制操作，不支持对复制操作产生的备份再次执行跨区域复制操作。 - 云服务器在宽限期和保留期内，可正常创建整机镜像（包含用户运行业务所需的操作系统、应用软件和业务数据的镜像），保留期到期后，不支持创建整机镜像。 - 使用Windows操作系统弹性云服务器制作整机镜像时，需修改弹性云服务器SAN策略为OnlineAll类型。否则可能导致使用镜像创建弹性云服务器时，弹性云服务器磁盘处于脱机状态。配置OnlineAll类型的方法请参考[修改弹性云服务器SAN策略为OnlineAll类型](https://support.huaweicloud.com/usermanual-ims/ims_01_0216.html#section5)。 #### 约束与限制（使用云服务器备份制作整机镜像） - 创建整机镜像时，请确保创建该云服务器备份所属的弹性云服务器已完成相关配置，否则可能导致整机镜像创建弹性云服务器失败。 详情请参见"[创建私有镜像前云服务器、裸金属服务器或镜像文件需要完成哪些初始化配置？](https://support.huaweicloud.com/ims_faq/ims_faq_0022.html)"。 - 在云服务器关机状态下，制作整机镜像的过程中，用户不能启动云服务器。 - 使用云服务器备份创建整机镜像时，不允许云服务器备份存在共享卷。 - 使用云服务器备份创建整机镜像时，云服务器备份必须是可用状态，且每个云服务器备份只能创建一个整机镜像。 - 不支持将整机镜像发布为市场镜像。 - 不支持将整机镜像导出到本地使用。 - 不支持同区域内复制整机镜像。 - 跨区域复制整机镜像各区域存在差异，请以控制台界面显示为准。 对于不支持跨区域复制的情况，您可以使用整机镜像创建云服务器，再分别创建系统盘镜像和数据盘镜像，然后跨区域复制到目标区域，实现整机镜像的跨区域复制功能。 对于使用弹性云服务器备份创建的整机镜像，仅支持对当前区域生成的备份执行跨区域复制操作，不支持对复制操作产生的备份再次执行跨区域复制操作。 #### 约束与限制（使用云备份制作整机镜像） - 创建整机镜像前，请确保创建该云备份所属的弹性云服务器已完成相关配置，否则可能导致整机镜像创建弹性云服务器失败。 详情请参见"[创建私有镜像前云服务器、裸金属服务器或镜像文件需要完成哪些初始化配置？](https://support.huaweicloud.com/ims_faq/ims_faq_0022.html)"。 - 每个云备份只能创建一个整机镜像。 - 在云服务器关机状态下，制作整机镜像的过程中，用户不能启动云服务器。 - 通过云备份创建的整机镜像可以共享给其他租户。但是，如果这个云备份是由其他租户共享的，那么创建的整机镜像不支持共享。 - 不支持将整机镜像发布为市场镜像。 - 不支持将整机镜像导出到本地使用。 - 不支持同区域内复制整机镜像。 - 跨区域复制整机镜像各区域存在差异，请以控制台界面显示为准。 对于不支持跨区域复制的情况，您可以使用整机镜像创建云服务器，再分别创建系统盘镜像和数据盘镜像，然后跨区域复制到目标区域，实现整机镜像的跨区域复制功能。 对于使用弹性云服务器备份创建的整机镜像，仅支持对当前区域生成的备份执行跨区域复制操作，不支持对复制操作产生的备份再次执行跨区域复制操作。 - 使用云备份制作整机镜像，若关联的云备份因欠费原因导致被删除，整机镜像也会随之删除。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?locale=zh-cn&consoleCurrentProductId=ims&consoleCurrentProductshort=&product=IMS&api=CreateWholeImage)中调试该接口。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-ims/ims_03_appendix_03.html)。 #### URI POST /v1/cloudimages/wholeimages/action #### 请求消息 - 使用云服务器创建整机镜像的请求参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释：** 镜像名称。name参数说明请参考[镜像属性](https://support.huaweicloud.com/api-ims/ims_03_0901.html)。 **约束限制：** 名称的首尾字符不能为空格。 **取值范围：** 只能由中文、字母、数字、空格和特殊字符 - _ . 组成，且首尾字符都不能为空格。名称的长度为1～128位。 **默认取值：** 不涉及 | | description | 否 | String | **参数解释：** 镜像描述信息。description参数说明请参考[镜像属性](https://support.huaweicloud.com/api-ims/ims_03_0901.html)。 **约束限制：** 不涉及 **取值范围：** 支持字母、数字、中文等，不支持回车、\<、\>，长度不能超过1024个字符。 **默认取值：** 不涉及 | | tags | 否 | Array of strings | **参数解释：** 镜像标签列表。每个镜像标签包含key和value两个字段，tags的参数说明请参考[镜像标签数据格式](https://support.huaweicloud.com/api-ims/ims_03_0902.html)。 **约束限制：** tags和image_tags只能使用一个。 | | image_tags | 否 | Array of objects | **参数解释：** 新规范的镜像标签列表。每个镜像标签包含key和value两个字段，image_tags数据结构说明请参见[表1 image_tags数据结构说明]。 **约束限制：** tags和image_tags只能使用一个。 | | instance_id | 是 | String | **参数解释：** 云服务器ID。使用云服务器制作整机镜像时使用此参数。 如何获取云服务器ID： 1. 登录[ECS控制台](https://console.huaweicloud.com/ecm/?#/ecs/manager/vmList)。 2. 在云服务器列表栏，单击源云服务器名称，在详情页查看ID。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | enterprise_project_id | 否 | String | **参数解释：** 表示当前镜像所属的企业项目。 关于企业项目特性的详细信息，请参考"[企业中心总览](https://support.huaweicloud.com/usermanual-em/zh-cn_topic_0123692049.html)"。企业项目ID的获取，请参考[如何获取企业项目ID](https://support.huaweicloud.com/usermanual-em/zh-cn_topic_0126101490.html)。 **约束限制：** 如果只使用企业项目授权，必须传入enterprise_project_id参数，否则可能会出现报错无权限。 **取值范围：** - 取值为0或无该值，表示属于default企业项目。 - 取值为UUID，表示属于该UUID对应的企业项目。 **默认取值：** 不涉及 | | max_ram | 否 | Integer | **参数解释：** 表示镜像支持的最大内存，单位为MB。 **约束限制：** 必须大于等于min_ram。 **取值范围：** 大于0的整数。 **默认取值：** 不涉及 | | min_ram | 否 | Integer | **参数解释：** 表示镜像支持的最小内存，单位为MB。 **约束限制：** 不涉及 **取值范围：** 大于等于0的整数。 **默认取值：** 默认为0。 | | vault_id | 否 | String | **参数解释：** 表示云服务器待加入的或已加入的存储库的ID。 存储库ID可以从云备份服务控制台获取，或者参考"[查询存储库列表](https://support.huaweicloud.com/api-cbr/ListVault.html)"查询。 **约束限制：** 使用云服务器创建整机镜像的过程为：先创建一个备份，再将备份创建为整机镜像。如果这个备份为CBR，vault_id为必填项；如果备份为CSBS，vault_id参数可不填。 **取值范围：** 不涉及 **默认取值：** 不涉及 | - 使用云服务器备份或云备份创建整机镜像的请求参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释：** 镜像名称。name参数说明请参考[镜像属性](https://support.huaweicloud.com/api-ims/ims_03_0901.html)。 **约束限制：** - 名称的首尾字符不能为空格。 - 名称的长度为1～128位。 **取值范围：** 只能由中文、字母、数字、空格和特殊字符 - _ . 组成，且首尾字符都不能为空格。 **默认取值：** 不涉及 | | description | 否 | String | **参数解释：** 镜像描述信息。description参数说明请参考[镜像属性](https://support.huaweicloud.com/api-ims/ims_03_0901.html)。 **约束限制：** 不涉及 **取值范围：** 支持字母、数字、中文等，不支持回车、\<、\>，长度不能超过1024个字符。 **默认取值：** 不涉及 | | tags | 否 | Array of strings | **参数解释：** 镜像标签列表。每个镜像标签包含key和value两个字段，tags的参数说明请参考[镜像标签数据格式](https://support.huaweicloud.com/api-ims/ims_03_0902.html)。 **约束限制：** tags和image_tags只能使用一个。 | | image_tags | 否 | Array of objects | **参数解释：** 新规范的镜像标签列表。每个镜像标签包含key和value两个字段，image_tags数据结构说明请参见[表1 image_tags数据结构说明]。 **约束限制：** tags和image_tags只能使用一个。 | | backup_id | 是 | String | **参数解释：** 云服务器备份ID或者云备份ID。 如何获取云服务器备份ID： 1. 登录[CBR控制台](https://console.huaweicloud.com/cbr/v2/?#/cbr/manager/overview)。 2. 进入[云服务器备份](https://console.huaweicloud.com/cbr/v2/?#/cbr/manager/csbs/vaultList)页面。 3. 在备份列表栏，展开备份详情，查看备份ID。 如何获取云备份ID： 1. 登录[CBR控制台](https://console.huaweicloud.com/cbr/v2/?#/cbr/manager/overview)。 2. 进入[云服务器备份](https://console.huaweicloud.com/cbr/v2/?#/cbr/manager/csbs/vaultList)页面。 3. 在云服务器备份页面，单击"备份副本"页签，在备份列表中查看备份ID。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | enterprise_project_id | 否 | String | **参数解释：** 表示当前镜像所属的企业项目。 关于企业项目特性的详细信息，请参考"[企业中心总览](https://support.huaweicloud.com/usermanual-em/zh-cn_topic_0123692049.html)"。企业项目ID的获取，请参考[如何获取企业项目ID](https://support.huaweicloud.com/usermanual-em/zh-cn_topic_0126101490.html)。 **约束限制：** 如果只使用企业项目授权，必须传入enterprise_project_id参数，否则可能会出现报错无权限。 **取值范围：** - 取值为0或无该值，表示属于default企业项目。 - 取值为UUID，表示属于该UUID对应的企业项目。 **默认取值：** 不涉及 | | max_ram | 否 | Integer | **参数解释：** 表示镜像支持的最大内存，单位为MB。 **约束限制：** 必须大于等于min_ram。 **取值范围：** 大于0的整数。 **默认取值：** 不涉及 | | min_ram | 否 | Integer | **参数解释：** 表示镜像支持的最小内存，单位为MB。 **约束限制：** 不涉及 **取值范围：** 大于等于0的整数。 **默认取值：** 默认为0。 | | whole_image_type | 否 | String | **参数解释：** 表示创建整机镜像的方式。 **约束限制：** - 若通过CBR服务的备份创建整机镜像，该参数必填，设置为CBR，此时，backup_id为云备份ID。 - 若通过CSBS服务的备份创建整机镜像，该参数可为空，取默认值CSBS，此时，backup_id为云服务器备份ID。 **取值范围：** - CBR：通过CBR服务的备份创建整机镜像。 - CSBS：通过CSBS服务的备份创建整机镜像。 **默认取值：** CSBS | 表1image_tags数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释：** 标签的键。 **约束限制：** 不涉及 **取值范围：** 标签的键可以包含任意语种字母、数字、空格和 _ . : + - @，但首尾不能含有空格,不能以sys_开头。长度不能超过128个字符。 **默认取值：** 不涉及 | | value | 是 | String | **参数解释：** 标签的值。 **约束限制：** 不涉及 **取值范围：** 标签的值可以包含任意语种字母、数字、空格和_ . : / + - @，但首尾不能含有空格。长度不能超过255个字符。 **默认取值：** 不涉及 | #### 请求示例 - 使用云服务器制作整机镜像，其中，镜像标签数据格式为tags，虚拟机ID为"877a2cda-ba63-4e1e-b95f-e67e48b6129a"。 ``` POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "instance_whole_image", "description": "云服务器制作镜像", "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "vault_id": "de9fcf45-11b2-432c-8562-5c5428574600", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] } ``` - 使用云服务器制作整机镜像，其中，镜像标签数据格式为image_tags，虚拟机ID为"877a2cda-ba63-4e1e-b95f-e67e48b6129a"。 ``` POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "instance_whole_image", "description": "云服务器制作镜像", "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "vault_id": "de9fcf45-11b2-432c-8562-5c5428574600", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] } ``` - 使用云服务器备份或云备份制作整机镜像，其中，镜像标签数据格式为tags，备份ID为"9b27efab-4a17-4c06-bfa2-3e0cf021d3c3"。 ``` POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "backup_whole_image", "description": "云备份制作镜像", "backup_id": "9b27efab-4a17-4c06-bfa2-3e0cf021d3c3", "whole_image_type": "CBR", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] } ``` - 使用云服务器备份或云备份制作整机镜像，其中，镜像标签数据格式为image_tags，备份ID为"9b27efab-4a17-4c06-bfa2-3e0cf021d3c3"。 ``` POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "backup_whole_image", "description": "云备份制作镜像", "backup_id": "9b27efab-4a17-4c06-bfa2-3e0cf021d3c3", "whole_image_type": "CBR", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] } ``` #### 响应消息 - 响应参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | job_id | String | **参数解释：** 异步任务ID。 详情请参见[6.6.2-异步任务进度查询 - ShowJobProgress](https://support.huaweicloud.com/api-ims/ims_03_0911.html)。 **取值范围：** 不涉及 | - 响应样例 ``` STATUS CODE 200 ``` ``` { "job_id": "4010a32b5f909853015f90aaa24b0015" } ``` #### 返回值 - 正常 200 - 异常 | 返回值 | 说明 | |:---|:---| | 400 Bad Request | 请求错误，具体返回错误码请参见[错误码](https://support.huaweicloud.com/api-ims/ims_03_0908.html)。 | | 401 Unauthorized | 鉴权失败。 | | 403 Forbidden | 没有操作权限。 | | 404 Not Found | 找不到资源。 | | 500 Internal Server Error | 服务内部错误。 | | 503 Service Unavailable | 服务不可用。 |