Importing an Image File Quickly

Function

This API is used to quickly create a private image from an oversized external image file that has been uploaded to an OBS bucket. Currently, only ZVHD2 and RAW image files can be imported quickly, and the size of such an image file cannot exceed 1 TB.

The fast image creation function is only available for image files in RAW or ZVHD2 format. For other formats of image files that are smaller than 128 GB, you are advised to import these files with the common method.

This is an asynchronous API. A successful call only means the background has received the request. To see if an image is created successfully, you need to use the asynchronous job query API to query the image creation status. For details, see Querying the Progress of an Asynchronous Job.

Constraints

For details about how to convert the image file format and generate a bitmap file, see Quickly Importing an Image File.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned. For details about the required permissions, see Permissions and Supported Actions.

URI

POST /v2/cloudimages/quickimport/action

Request

• Parameters in the request body when an image file in an OBS bucket is used to create a system disk image

  Parameter	Mandatory	Type	Description
  name	Yes	String	Definition Image name. For details about name, see Image Attributes. Constraints A name cannot start or end with a space. The name length must be 1 to 128 characters. Range A name can contain only letters, digits, spaces, hyphens (-), underscores (_), and periods (.), and cannot start or end with a space. Default Value N/A
  description	No	String	Definition Image description. For details about description, see Image Attributes. Constraints The value contains a maximum of 1,024 characters, including letters and digits. Carriage returns and angle brackets (< >) are not allowed. Range N/A Default Value N/A
  os_version	Yes	String	Definition OS version. Constraints This parameter is valid when you create an image from an external image file uploaded to an OBS bucket. Range For details, see Values of Related Parameters. Default Value N/A
  license_type	No	String	Definition OS license type. Constraints Currently, this parameter is only available for Windows. Range platform: license provided by Huawei Cloud byol: Bring Your Own License Default Value N/A
  image_url	Yes	String	Definition URL of the external image file in an OBS bucket. Constraints This parameter is mandatory if an external image file in an OBS bucket is used to create an image. The format is <OBS-bucket-name>:<image-file-name>. NOTE: The storage class of the OBS bucket and image files in it must be Standard. Range N/A Default Value N/A
  min_disk	Yes	Integer	Definition Minimum system disk size, in GB. Constraints This parameter is mandatory if an external image file in an OBS bucket is used to create an image. The value must be greater than the system disk size in the selected image file. Range The value must be greater than the system disk size in the selected image file. For Linux, the value ranges from 10 GB to 1024 GB. For Windows, the value ranges from 20 GB to 1024 GB. Default Value N/A
  tags	No	Array of strings	Definition Image tags. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Lists the image tags. For details about image_tags, see Table 1. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  type	No	String	Definition Image type. Constraints N/A Range ECS: ECS system disk image BMS: BMS system disk image Default Value ECS
  enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Center. Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0 or left blank, the image belongs to the default enterprise project. If the value is a UUID, the image belongs to the enterprise project corresponding to the UUID. Default Value N/A
  architecture	No	String	Definition Image architecture. Constraints If the architecture is Arm, the boot mode is automatically changed to UEFI. Range x86 arm Default Value The default value is x86.
  hw_firmware_type	No	String	Definition Cloud server boot mode. Constraints If the image architecture is Arm, only the UEFI boot mode is supported. Range bios indicates the BIOS boot mode. uefi indicates the UEFI boot mode. Default Value N/A

• Parameters in the request body when an image file in an OBS bucket is used to create a data disk image

  Parameter	Mandatory	Type	Description
  name	Yes	String	Definition Image name. For details about name, see Image Attributes. Constraints A name cannot start or end with a space. The name length must be 1 to 128 characters. Range A name can contain only letters, digits, spaces, hyphens (-), underscores (_), and periods (.), and cannot start or end with a space. Default Value N/A
  description	No	String	Definition Image description. For details about description, see Image Attributes. Constraints The value contains a maximum of 1,024 characters, including letters and digits. Carriage returns and angle brackets (< >) are not allowed. Range N/A Default Value N/A
  os_type	No	String	Definition OS version. Constraints N/A Range The value is Linux or Windows when a data disk image is created. Default Value The default value is Linux.
  image_url	Yes	String	Definition URL of the external image file in an OBS bucket. Constraints This parameter is mandatory if an external image file in an OBS bucket is used to create an image. The format is <OBS-bucket-name>:<image-file-name>. NOTE: The storage class of the OBS bucket and image files in it must be Standard. Range N/A Default Value N/A
  min_disk	Yes	Integer	Definition Minimum size of a system disk. Constraints This parameter is mandatory if an external image file in an OBS bucket is used to create an image. Range For Linux, the value ranges from 10 GB to 1024 GB. For Windows, the value ranges from 20 GB to 1024 GB. Default Value N/A
  tags	No	Array of strings	Definition Image tags. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Lists the image tags. For details about image_tags, see Table 1. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  type	Yes	String	Definition Image type. Constraints N/A Range DataImage: data disk image Default Value N/A
  enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Center. Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0 or left blank, the image belongs to the default enterprise project. If the value is a UUID, the image belongs to the enterprise project corresponding to the UUID. Default Value N/A

Example Request

• Creating a system disk image with parameter tags using a file in an OBS bucket (file address in the bucket: ims-image:centos70.zvhd2)

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

  POST https://{Endpoint}/v2/cloudimages/quickimport/action { "name": "ims_test_file", "description": "Create an image using a file in an OBS bucket.", "image_url": "ims-image:centos70.zvhd2", "os_version": "CentOS 7.0 64bit", "min_disk": 40, "type": "ECS", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }

• Creating a system disk image with parameter image_tags using a file in an OBS bucket (file address in the bucket: ims-image:centos70.zvhd2)

  1 2 3 4 5 6 7 8 9 10

  POST https://{Endpoint}/v2/cloudimages/quickimport/action { "name": "ims_test_file", "description": "Create an image using a file in an OBS bucket.", "image_url": "ims-image:centos70.zvhd2", "os_version": "CentOS 7.0 64bit", "min_disk": 40, "type": "ECS", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }

• Creating a data disk image with parameter tags using a file in an OBS bucket (file address in the bucket: ims-image:centos70.zvhd2)

  1 2 3 4 5 6 7 8 9 10 11 12 13 14

  POST https://{Endpoint}/v2/cloudimages/quickimport/action { "name": "ims_test_file", "description": "Create an image using a file in an OBS bucket.", "image_url": "ims-image:centos70.zvhd2", "os_type": "Linux", "min_disk": 40, "type": "DataImage", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }

• Creating a data disk image with parameter image_tags using a file in an OBS bucket (file address in the bucket: ims-image:centos70.zvhd2)

  1 2 3 4 5 6 7 8 9 10

  POST https://{Endpoint}/v2/cloudimages/quickimport/action { "name": "ims_test_file", "description": "Create an image using a file in an OBS bucket.", "image_url": "ims-image:centos70.zvhd2", "os_type": "Linux", "min_disk": 40, "type": "DataImage", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }

Response

• Response parameters

  Parameter	Type	Description
  job_id	String	Definition Asynchronous job ID. For details, see Querying the Progress of an Asynchronous Job. Range N/A

• Example response

  STATUS CODE 200

  1 2 3

  { "job_id": "8a12fc664fb4daa3014fb4e581380005" }

Returned Values

• Normal

  200

• Abnormal

  Return Value	Description
  400 Bad Request	Request error. For details about the returned error code, see Error Codes.
  401 Unauthorized	Authentication failed.
  403 Forbidden	Insufficient permissions.
  404 Not Found	Requested resource not found.
  500 Internal Server Error	Internal service error.
  503 Service Unavailable	Service unavailable.