Image task#

Use image task operations to initiate and manage asynchronous image tasks like those created when importing and exporting images. For more information, see Asynchronous image tasks.

Note

The method and URI (POST tasks) used to create an asynchronous task is the same for both importing and export images. However, the operations are listed separately to reduce confusion. The desired end result, the request and response bodies, and the examples of the two operations are different.

List tasks#

GET /tasks

This operation returns list of tasks, with basic details about each task. The response conforms to the schema found in Get tasks schema.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
404	Not Found	Resource not found.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
first	String	The URI for the first task in the list.
schema	String	The schema of the tasks list.
tasks	Array	The container for tasks in the list.
tasks.created_at	String	The date and time that the task resource was created.
tasks.id	String	The UUID of the task resource.
tasks.owner	String	The tenant-id of the task owner.
tasks.schema	String	The schema of the task.
tasks.self	String	The link to the task.
tasks.status	String	The status of the task. For status values, see Image statuses.
tasks.type	String	The type of the task (`export` for task exports).
tasks.updated_at	String	The date and time that the task resource was updated.

Example: List Tasks

{
    "first": "/v2/tasks",
    "schema": "/v2/schemas/tasks",
    "tasks": [
        {
            "created_at": "2014-02-26T02:04:18Z",
            "id": "baef2134-9c33-47b9-9d63-c29a2a224715",
            "owner": "00000123",
            "schema": "/v2/schemas/task",
            "self": "/v2/tasks/baef2134-9c33-47b9-9d63-c29a2a224715",
            "status": "pending",
            "type": "export",
            "updated_at": "2014-02-26T02:04:18Z"
        },
        {
            "created_at": "2014-02-26T02:01:13Z",
            "id": "7bdc8ede-9098-4d79-9477-697f586cb333",
            "owner": "00000123",
            "schema": "/v2/schemas/task",
            "self": "/v2/tasks/7bdc8ede-9098-4d79-9477-697f586cb333",
            "status": "processing",
            "type": "export",
            "updated_at": "2014-02-26T02:01:13Z"
        }
    ]
}

Get task details#

GET /tasks/{taskID}

This operation shows the details for the specified task, including the status. You can use it to confirm whether an import or export task completed successfully. For more information on statuses, see Task statuses. The response conforms to the schema found in Get tasks schema.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
404	Not Found	Resource not found.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{task_id}	UUID	The task id. This task id is the same as the id parameter returned in the Import Task or Export Task operation response body.

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
created_at	String	The date and time that the task resource was created.
expires_at	String	The date and time that the task resource expires. Even after the task resource expires (and is thus no longer available to be polled), the result of the task (such as an imported or exported image) still exists. Note This parameter is required for response with `status` of `success` and `failure`.
id	String	The UUID of the task resource.
input	Object	The container for import input parameters.
input.image_properties	Object	The container for image properties.
input.image_properties.name	String	The name of the image.
input.import_from	String	The source of the imported image.
message	String	`None` if task import succeeded or the reason why the import failed. Possible errors include the following: `111`: The image cannot be imported/ There is an unspecified problem with your VHD that caused it to fail our validation checks. `396`: The image cannot be imported. The file is not a valid VHD. `413`: The image cannot be imported. The virtual size of the disk exceeds the 40GB limit. `523`: The image cannot be imported. Only fixed or dynamic disks may be imported. `609`: The image cannot be imported. The physical size of the disk exceeds the 40GB limit. `614`: The image cannot be imported. The internal UUID of the VHD is all zeros. `721`: The image cannot be imported. Your VHD has a parent disk. You can only import a stand-alone VHD.
result		The container for results. Note This parameter is required for responses with a `status` of `success`.
result.image_id	UUID	The UUID of the image.
owner	String	The tenant-id of the task owner.
schema	String	The schema of the task.
self	String	The link to the task.
status	String	The status of the task. For possible task statuses, see Task statuses.
type	String	The type of the task ( `export` for task exports).
updated_at	String	The date and time that the task resource was updated.

Example: Get import task details - pending response

{
    "created_at": "2014-02-26T02:58:46Z",
    "id": "fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
    "input": {
        "image_properties": {
            "name": "My excellent custom image"
        },
        "import_from": "exports/my-excellent-image.vhd"
    },
    "message": "None",
    "owner": "00000123",
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
    "status": "pending",
    "type": "import",
    "updated_at": "2014-02-26T02:58:46Z"
}

Example: Get import task details - success response

{
    "created_at": "2014-02-26T03:02:23Z",
    "expires_at": "2014-02-28T03:28:18Z",
    "id": "d8dd8c24-2534-473c-881f-9097bc784068",
    "input": {
        "image_properties": {
            "name": "My excellent custom image"
        },
        "import_from": "exports/my-excellent-image.vhd"
    },
    "message": "None",
    "owner": "00000123",
    "result": {
        "image_id": "1d944ab7-6748-4f3c-b7e2-3553bf006677"
    },
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/d8dd8c24-2534-473c-881f-9097bc784068",
    "status": "success",
    "type": "import",
    "updated_at": "2014-02-26T03:28:18Z"
}

Example: Get import task details - failure response

{
    "created_at": "2014-02-26T02:58:46Z",
    "expires_at": "2014-02-28T02:58:49Z",
    "id": "fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
    "input":
    {
        "image_properties":
        {
            "name": "my imported image"
        },
        "import_from": "nonexistentcontainer/noimage.vhd"
    },
    "message": "Error: Image not found for import. Possible invalid location",
    "owner": "00000123",
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
    "status": "failure",
    "type": "import",
    "updated_at": "2014-02-26T02:58:49Z"
}

Example Get export task details - pending response

{
    "created_at": "2014-02-26T02:01:13Z",
    "id": "7bdc8ede-9098-4d79-9477-697f586cb333",
    "input":
    {
        "image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6",
        "receiving_swift_container": "exports"
    },
    "message": "None",
    "owner": "00000123",
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/7bdc8ede-9098-4d79-9477-697f586cb333",
    "status": "pending",
    "type": "export",
    "updated_at": "2014-02-26T02:01:13Z"
}

Example: Get export task details - success response

{
    "created_at": "2014-02-26T02:01:13Z",
    "expires_at": "2014-02-28T02:16:50Z",
    "id": "7bdc8ede-9098-4d79-9477-697f586cb333",
    "input":
    {
        "image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6",
        "receiving_swift_container": "exports"
    },
    "message": "None",
    "owner": "00000123",
    "result":
    {
        "export_location": "exports/ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6.vhd"
    },
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/7bdc8ede-9098-4d79-9477-697f586cb333",
    "status": "success",
    "type": "export",
    "updated_at": "2014-02-26T02:16:50Z"
}

Example: Get export task details - failure response

{
    "created_at": "2014-02-26T02:04:18Z",
    "expires_at": "2014-02-28T02:25:12Z",
    "id": "baef2134-9c33-47b9-9d63-c29a2a224715",
    "input":
    {
        "image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6",
        "receiving_swift_container": "exports"
    },
    "message": "Swift already has an object with id 'ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6.vhd' in container 'exports'",
    "owner": "00000123",
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/baef2134-9c33-47b9-9d63-c29a2a224715",
    "status": "failure",
    "type": "export",
    "updated_at": "2014-02-26T02:25:12Z"
}

Task to import image#

POST /tasks

This operation imports an image using an asynchronous task request. The request begins the import process and returns the task UUID that can be subsequently polled to determine the status of the import by using the : ref:Get task details <get-task-details>. The response conforms to the schema found in Get tasks schema. To successfully import an image:

Format the image using the VHD format.

If you are importing an image that you have previously exported from Cloud Images in another region of the Rackspace open cloud, your image is already in the appropriate format. This article provides information on preparing a custom image for import.
Store the image in your Cloud Files account.

Note

As described in the Rackspace general terms and conditions, make sure that you are aware of and respect all licensing restrictions that apply to any software that you import into the Rackspace open cloud. For example, Microsoft licensing rules are very restrictive. Microsoft product use rights do not allow the use of License Mobility for Windows licenses. Given the limitations related to this software platform, image import is not available for Windows images. If you have questions, please contact the software vendor.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	Request succeeded.
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
415	Bad Media Type	Bad media type. This may result if the wrong media type is used in the cURL request.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the body parameters for the request:

Name	Type	Description
type	String (Required)	The type of task. Use `import` for task imports.
input	(Required)	The container for import input parameters.
input.image_properties	(Required)	The container for image properties.
input.image_properties.name	String (Required)	The name of the image. .. warning:: Name is the only property that can be included in `image- properties`. Including any other property will cause the operation to fail.
input.import_from	String (Required)	The source of the imported image.

Example: Task to import image: JSON request

{
    "type": "import",
    "input": {
        "image_properties": {
            "name": "My excellent custom image"
        },
        "import_from": "exports/my-excellent-image.vhd"
    }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
created_at	String	The date and time that the task resource was created.
expires_at	String	The date and time that the task resource expires. Even after the task resource expires (and is thus no longer available to be polled), the result of the task (such as an imported or exported image) still exists. .. note:: This parameter is required for responses with `status` of `success` and `failure`.
id	String	The UUID of the task resource.
input	Object	The container for import input parameters.
input.image_properties	Object	The container for image properties.
input.image_properties.name	String	The name of the image. Warning Name is the only property that can be included in `image-properties`. Including any other property will cause the operation to fail.
input.import_from	String	The source of the imported image.
message	String	`None` if task import succeeded or the reason why the import failed. Possible errors include the following: `111`: The image cannot be imported/ There is an unspecified problem with your VHD that caused it to fail our validation checks. `396`: The image cannot be imported. The file is not a valid VHD. `413`: The image cannot be imported. The virtual size of the disk exceeds the 40GB limit. `523`: The image cannot be imported. Only fixed or dynamic disks may be imported. `609`: The image cannot be imported. The physical size of the disk exceeds the 40GB limit. `614`: The image cannot be imported. The internal UUID of the VHD is all zeros. `721`: The image cannot be imported. Your VHD has a parent disk. You can only import a stand-alone VHD.
result	Object	The container for results. .. note:: This parameter is required for responses with `status` of `success`.
result.image_id	UUID	The UUID of the image.
owner	String	The tenant-id of the task owner.
schema	String	The schema of the task.
self	String	The link to the task.
status	String	The status of the image. For possible image statuses, see Image statuses
type	String	The type of the task ( `export` for task exports).
updated_at	String	The date and time that the task resource was updated.

Example: Import Task - Pending Response

{
    "created_at": "2014-02-26T02:58:46Z",
    "id": "fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
    "input": {
        "image_properties": {
            "name": "My excellent custom image"
        },
        "import_from": "exports/my-excellent-image.vhd"
    },
    "message": "None",
    "owner": "00000123",
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/fc29a67c-ad76-49bc-a317-a5f38dcb44c0",
    "status": "pending",
    "type": "import",
    "updated_at": "2014-02-26T02:58:46Z"
}

Task to export image#

POST /tasks

This operation exports an image in VHD format using an asynchronous task request to export. The request begins the export process and returns the task UUID that can be subsequently polled to determine the status of the export by using the Get task details operation. The response conforms to the schema found in Get tasks schema.

Note

The exported image is deposited in your Cloud Files account and is identified by the image_uuid with a.vhd extension. You are responsible for ensuring that any distribution of your image from the Rackspace open cloud complies with any licensing restrictions.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	Task export request succeeded.
400	Error	A general error has occurred.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
413	Over Limit	The number of items returned is above the allowed limit.
415	Bad Media Type	Bad media type. This may result if the wrong media type is used in the cURL request.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request#

This table shows the body parameters for the request:

Name	Type	Description
type	String (Required)	The type of the task. Use `export` for task exports.
input	(Required)	The container for export input parameters.
input.image_uuid	String (Required)	The UUID for the exported image. You must own the image or the export task will fail.
input.receiving_swift_container	String (Required)	The Cloud Files container for the exported image. If the container does not exist, the task fails. The task also fails if the container name contains any of the following three characters: forward slash ( `/` ), question mark ( `?` ) or period ( `.` ).

Example Task to export image: JSON request

{
    "type": "export",
    "input":
    {
        "image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6",
        "receiving_swift_container": "exports"
    }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
created_at	String	The date and time that the task resource was created.
expires_at	String	The date and time that the task resource expires. Even after the task resource expires (and is thus no longer available to be polled), the result of the task (such as an imported or exported image) still exists. .. note:: This parameter is required for responses with `status` of `success` and``failure``.
id	String	The UUID of the task resource.
input	Object	The container for export export input parameters.
input.image_uuid	Object	The UUID for the exported image.
input.receiving_swift_container	String	The Cloud Files container for the exported image.
message	String	`None` if task export succeeded or the reason why the export failed.
result	Object	The container for results. .. note:: This parameter is required for responses with status` of `success`.
result.export_location	String	The location of the exported image in Cloud Files.
owner	String	The tenant-id of the task owner.
schema	String	The schema of the task.
self	String	The link to the task.
status	String	The status of the task. For task statuses, see Image statuses
type	String	The type of the task (`export` for task exports).
updated_at	String	The date and time that the task resource was updated.

Example Export Task - Pending Response

{
    "created_at": "2014-02-26T02:01:13Z",
    "id": "7bdc8ede-9098-4d79-9477-697f586cb333",
    "input":
    {
        "image_uuid": "ca5e7f11-5d57-4dd7-8ace-03ab647fe6c6",
        "receiving_swift_container": "exports"
    },
    "message": "None",
    "owner": "00000123",
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/7bdc8ede-9098-4d79-9477-697f586cb333",
    "status": "pending",
    "type": "export",
    "updated_at": "2014-02-26T02:01:13Z"
}