更新时间:2024-04-17 GMT+08:00

制作镜像

功能介绍

本接口用于制作私有镜像,支持:

  • 使用云服务器制作私有镜像(系统盘镜像/数据盘镜像)。
  • 使用上传至OBS桶中的外部镜像文件制作系统盘镜像。
  • 使用数据盘制作系统盘镜像。

作为异步接口,调用成功,只是说明云平台收到了制作请求,镜像是否制作成功需要通过异步任务查询接口查询该任务的执行状态,具体请参考异步任务查询

约束与限制(使用数据盘创建系统盘镜像)

  • 使用数据盘制作系统盘镜像时,需确保该数据盘中有操作系统,且操作系统已提前完成优化步骤。如何优化,请参见《镜像服务用户指南》的“优化私有镜像(Windows)”和“优化私有镜像(Linux)”章节。
  • 由于系统无法校验您在调用该接口时指定的卷是否存在操作系统,因此制作系统盘镜像时,请务必确保您输入的os_version(操作系统版本)值合法,具体请参见相关参数取值列表

URI

POST /v2/cloudimages/action

请求消息

  • 使用云服务器制作镜像(系统盘镜像/数据盘镜像)时的请求参数

    参数

    是否必选

    参数类型

    描述

    name

    String

    系统盘镜像名称。name参数说明请参考镜像属性

    description

    String

    镜像描述信息。description参数说明请参考镜像属性。支持字母、数字、中文等,不支持回车、<、>,长度不能超过1024个字符。默认为空。

    instance_id

    String

    用于制作镜像的源云服务器ID。

    如何获取云服务器ID:

    1. 登录控制台。
    2. 选择“计算 > 弹性云服务器”。
    3. 云服务器列表栏,单击源云服务器名称,在详情页查看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只能使用一个。

    enterprise_project_id

    String

    表示当前镜像所属的企业项目。

    • 取值为0或无该值,表示属于default企业项目。
    • 取值为UUID,表示属于该UUID对应的企业项目。

      关于企业项目ID的获取及企业项目特性的详细信息,请参考《企业管理用户指南》。

    max_ram

    Integer

    表示镜像支持的最大内存,单位为MB。

    min_ram

    Integer

    表示镜像支持的最小内存,单位为MB,默认为0,表示不受限制。

    表1 data_images字段数据结构说明

    参数

    是否必选

    参数类型

    描述

    name

    String

    数据盘镜像名称。

    volume_id

    String

    数据盘ID。

    description

    String

    数据盘描述。

    tags

    Array of strings

    数据盘镜像标签。

  • 使用上传至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桶名”获取方式:
      1. 登录控制台,选择“存储 > 对象存储服务”。

        在下方OBS桶列表栏显示所有已创建的OBS桶。

      2. 查看当前Region下,用于存放外部镜像文件的“桶名称”。
    • “OBS镜像文件名称”获取方式:
      1. 登录控制台,选择“存储 > 对象存储服务”。

        在下方OBS桶列表栏显示所有已创建的OBS桶。

      2. 查看当前Region下,用于存放外部镜像文件的“桶名称”。
      3. 单击桶名称,进入对应OBS桶详情页。
      4. 在左侧目录中选择“对象”,查看当前OBS桶中的对象,并记录用于制作镜像的外部镜像文件名称。
    说明:

    此处的OBS桶和镜像文件的存储类别必须是OBS标准存储。

    min_disk

    Integer

    最小系统盘大小。

    在使用OBS桶的外部镜像文件制作镜像时生效且为必选字段。取值为40~255GB。

    is_config

    Boolean

    是否自动配置。

    取值为true或false。

    如果需要后台自动配置,取值为true,否则为false。默认取值为false。

    后台自动配置的内容请参考《镜像服务用户指南》中的“通过外部镜像文件创建Linux系统盘镜像 > 注册镜像(Linux)”。

    cmk_id

    String

    创建加密镜像的自定义密钥,具体取值请参考《密钥管理服务用户指南》获取。

    tags

    Array of strings

    镜像标签列表。默认为空。

    tags和image_tags只能使用一个。

    image_tags

    Array of objects

    新规范的镜像标签列表。默认为空。tags和image_tags只能使用一个。

    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。

    关于镜像文件快速导入的约束与限制请参见镜像文件快速导入

    表2 data_images字段说明

    参数

    是否必选

    参数类型

    描述

    name

    String

    镜像名称。

    name参数说明请参见镜像属性

    description

    String

    镜像描述信息。默认为空。

    支持字母、数字、中文等,不支持回车、<、>,长度不能超过1024个字符。

    description参数说明请参见镜像属性

    image_url

    String

    OBS桶中外部镜像文件地址。

    格式为“<OBS桶名>:<OBS镜像文件名称>”

    • “OBS桶名”获取方式:
      1. 登录控制台,选择“存储 > 对象存储服务”。

        在下方OBS桶列表栏显示所有已创建的OBS桶。

      2. 查看当前Region下,用于存放外部镜像文件的“桶名称”。
    • “OBS镜像文件名称”获取方式:
      1. 登录控制台,选择“存储 > 对象存储服务”。

        在下方OBS桶列表栏显示所有已创建的OBS桶。

      2. 查看当前Region下,用于存放外部镜像文件的“桶名称”。
      3. 单击桶名称,进入对应OBS桶详情页。
      4. 在左侧目录中选择“对象”,查看当前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

    新规范的镜像标签列表。默认为空。

    image_tags参数说明请参见镜像标签数据格式

    tags和image_tags只能使用一个。

  • 使用数据盘制作系统盘镜像时的请求参数

    参数

    是否必选

    参数类型

    描述

    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只能使用一个。

    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"
    }
    

返回值

  • 正常

    200

  • 异常

    返回值

    说明

    400 Bad Request

    请求错误,具体返回错误码请参见错误码

    401 Unauthorized

    鉴权失败。

    403 Forbidden

    没有操作权限。

    404 Not Found

    找不到资源。

    500 Internal Server Error

    服务内部错误。

    503 Service Unavailable

    服务不可用。