List images¶
Overview¶
Lists virtual machine (VM) images.
Classification¶
- List
API Operation Object¶
- images
Synchronous / Asynchronous¶
- synchronous
Request¶
HTTP Request Method¶
- GET
HTTP Request Path¶
{api_endpoint}/v2/images
HTTP Request Header¶
HTTP Request Body¶
Format¶
- none
Request Parameter¶
| name | style | format | description | required/optional | default value | action for invalid parameter | response code for invalid parameter |
|---|---|---|---|---|---|---|---|
| token_id | Header | authentication token string | keystone authentication token | required | - | Terminate | 401 |
| limit | Query | integer | Use to request a specific page size | optional | 25 | Terminate | 400 |
| marker | Query | UUID String | Specifies the ID of the last-seen image | optional | - | Terminate | 400 |
| name | Query | String(nolimit) | Name of the image as a string | optional | - | - | - |
| visibility | Query | String(public, private, shared) | Image visibility | optional | public, private, shared | Terminate | 400 |
| member_status | Query | String(accepted, pending, rejected, all) | Only show images with the specified member status | optional | accepted | Terminate | 400 |
| owner | Query | String(nolimit) | Shows images shared with me by the specified owner, where the owner is indicated by project ID | optional | - | - | - |
| status | Query | String(nolimit) | The image status, such as queued, saving, active, killed, deleted, and pending_delete. | optional | - | - | - |
| size_min | Query | integer | Value of the minimum size of the image in bytes | optional | - | Terminate | 400 |
| size_max | Query | integer | Value of the maximum size of the image in bytes | optional | - | Terminate | 400 |
| sort_key | Query | All image attributes can be used as the sort_key, except tags and link attributes | Sort key | optional | created_at | Terminate | 400 |
| sort_dir | Query | String(desc, asc) | Sort direction | optional | desc | Terminate | 400 |
| tag | Query | String(nolimit) | Image tag | optional | - | - | - |
Response¶
HTTP Response Header¶
Format¶
HTTP/1.1 <response code> <message> (ex. 200 OK)
<response code>: see "HTTP Responses" section
<message> message based on the response code
- skip auto inserted field such as "X-Openstack-Request-Id", "Content-type", "Content-Length", "Date"
Response Code¶
| response code | condition |
|---|---|
| 200 | normal end |
| 400 | limit is not integer value or not positive value |
| - | maker is not a existent image_id |
| - | visibility is invalid value (valid value : public, private, shared) |
| - | member_status is invalid value (valid value : accepted, pending, rejected, all) |
| - | size_min is not a integer value |
| - | size_max is not a integer value |
| - | sort_key is not a attribute value of image |
| - | sort_key is a invalid image attribute value as sort key (when choose container_format, visibility, file, self or schema) |
| - | sort_dir is a invalid value (valid value : asc, desc) |
| - | specify "changes-since" query which is no longer available on v2 API |
| 401 | unauthorized |
| 403 | Not authorized to perform the requested action |
| 500 | Internal Error |
HTTP Response Body¶
Format¶
{
"images": [
{
"status": "<image_status>",
"name": "<image_name>",
"tags": ["<tag>", <<repeat>> ],
"container_format": "<container_format>",
"created_at": "<created_time>",
"disk_format": "<disk_format>",
"locations": [
{
"url": "<location_url>",
"metadata": <metadata>
},
<<repeat>>
],
"direct_url": "<direct_url>",
*"<extra_key>": "<extra_value>",
"updated_at": "<updated_time>",
"visibility": "<visibility>",
"self": "<self>",
"min_disk": <minimum_disk_size>,
"protected": <protected_flag>,
"id": "<image_id>",
"file": "<file>",
"checksum": "<checksum>",
"owner": "<owner>",
"size": <size>,
"min_ram": <minimum_ram_size>,
"schema": "<image_schema>"
},
<<repeat>>
],
"schema": "<images_schema>",
"first": "<first>"
}
- * There are multiple set of <extra_key> and <extra_value> which user added
Response Parameter¶
| item | format | description |
|---|---|---|
| image_status | String (queued, saving, active, killed, deleted, pending_delete) | Status of the image |
| image_name | String (1-255 characters) | Descriptive name for the image |
| tag | String (1-255 characters) | String related to the image |
| container_format | String (bare) | Format of the container |
| created_time | time/date | Date and time of image registration |
| disk_format | String (raw, qcow2, iso) | Format of the disk |
| location_url | URL String | URL to access the image file kept in external store (it is shown when 'show_multiple_locations' option is enabled) |
| metadata |
|
The location metadata |
| direct_url | URL String | URL to access the image file kept in external store (it is shown when 'show_image_direct_url' option is enabled) |
| extra_key | String (1-255 characters) | The key of the extra properties |
| extra_value | text (2^16 - 1 bytes) | The value of the extra properties |
| updated_time | time/date | Date and time of the last image modification |
| visibility | String (public, private) | Scope of image accessibility |
| self | URL String | URL for the virtual machine image |
| minimum_disk_size | integer | Amount of disk space (in GB) required to boot image |
| protected_flag | boolean | If true, image will not be deletable |
| image_id | UUID | An identifier for the image |
| file | URL String | URL for the virtual machine image file |
| checksum | MD5 | md5 hash of image contents |
| owner | UUID(3) | Owner of the image |
| size | integer | Size of image file in bytes |
| minimum_ram_size | integer | Amount of ram (in MB) required to boot image |
| image_schema | URL String | URL for schema of the virtual machine image |
| images_schema | URL String | URL for schema of the virtual machine images |
| first | URL string | URL for the first page of response |
Sample API Request and Response¶
Sample API Response¶
Response Header¶
HTTP/1.1 200 OK
<response code>: see "HTTP Responses" section
<message> message based on the response code
- skip auto inserted field such as "X-Openstack-Request-Id", "Content-type", "Content-Length", "Date"
Response Body¶
{
"images": [
{
"status": "<image_status>",
"name": "<image_name>",
"tags": ["<tag>", <<repeat>> ],
"container_format": "<container_format>",
"created_at": "<created_time>",
"disk_format": "<disk_format>",
"locations": [
{
"url": "<location_url>",
"metadata": <metadata>
},
<<repeat>
],
"direct_url": "<direct_url>",
*"<extra_key>": "<extra_value>",
"updated_at": "<updated_time>",
"visibility": "<visibility>",
"self": "<self>",
"min_disk": <minimum_disk_size>,
"protected": <protected_flag>,
"id": "<image_id>",
"file": "<file>",
"checksum": "<checksum>",
"owner": "<owner>",
"size": <size>,
"min_ram": <minimum_ram_size>,
"schema": "<image_schema>"
},
<<repeat>>
],
"schema": "<images_schema>",
"first": "<first>"
}
- * There are multiple set of <extra_key> and <extra_value> which user added
Execution Example¶
HTTP Request¶
GET /v2/images HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.11.141:9292
Accept: */*
X-Auth-Token: 4086d667aa3648fd96a7886cbb6354c1
HTTP Response¶
HTTP/1.1 200 OK
Content-Length: 3862
Content-Type: application/json; charset=UTF-8
X-Openstack-Request-Id: req-8ceb83e3-0343-4728-8fd6-f351138842ae
Date: Wed, 24 Sep 2014 11:29:12 GMT
{"images": [{"status": "active", "schema": "/v2/schemas/image", "name": "private_admin_admin", "tags": ["tag1", "tag2", "tag3"], "updated_at": "2014-09-24T11:13:10Z", "container_format": "bare", "min_ram": 0, "disk_format": "raw", "locations": [{"url": "file:///home/stack/test", "metadata": {"replace_01": "replace_01_value"}}, {"url": "file:///home/stack/test", "metadata": {"replace_02": "replace_02_value"}}], "visibility": "private", "self": "/v2/images/5521fbf2-0b89-4b7c-91b5-e3afbecd4a35", "extra1": "extra1", "protected": false, "extra3": "extra3", "file": "/v2/images/5521fbf2-0b89-4b7c-91b5-e3afbecd4a35/file", "owner": "014908bf180c4004a6c289d2d95b2285", "min_disk": 0, "created_at": "2014-09-24T11:05:39Z", "direct_url": "file:///home/stack/test", "id": "5521fbf2-0b89-4b7c-91b5-e3afbecd4a35", "size": 25165824}, {"status": "active", "name": "Fedora-x86_64-20-20140618-sda", "tags": [], "container_format": "bare", "created_at": "2014-09-19T10:09:06Z", "size": 209649664, "disk_format": "qcow2", "updated_at": "2014-09-19T10:09:07Z", "visibility": "public", "locations": [{"url": "file:///opt/stack/data/glance/images/4c213754-3989-4632-a619-b78a92603be2", "metadata": {}}], "self": "/v2/images/4c213754-3989-4632-a619-b78a92603be2", "min_disk": 0, "protected": false, "id": "4c213754-3989-4632-a619-b78a92603be2", "file": "/v2/images/4c213754-3989-4632-a619-b78a92603be2/file", "checksum": "9e486c3bf76219a6a37add392e425b36", "owner": "8c673f31843d438ca2562a6f66531482", "direct_url": "file:///opt/stack/data/glance/images/4c213754-3989-4632-a619-b78a92603be2", "min_ram": 0, "schema": "/v2/schemas/image"}, {"status": "active", "schema": "/v2/schemas/image", "name": "cirros-0.3.2-x86_64-uec", "tags": [], "locations": [{"url": "file:///opt/stack/data/glance/images/0d2705c4-56c2-4d61-a16a-b1b36fde26dd", "metadata": {}}], "container_format": "bare", "min_ram": 0, "ramdisk_id": "07c85e37-c7ff-4094-98e3-f3846e524ef0", "disk_format": "iso", "updated_at": "2014-09-19T10:09:06Z", "visibility": "public", "self": "/v2/images/0d2705c4-56c2-4d61-a16a-b1b36fde26dd", "min_disk": 0, "protected": false, "file": "/v2/images/0d2705c4-56c2-4d61-a16a-b1b36fde26dd/file", "checksum": "4eada48c2843d2a262c814ddc92ecf2c", "owner": "8c673f31843d438ca2562a6f66531482", "created_at": "2014-09-19T10:09:05Z", "direct_url": "file:///opt/stack/data/glance/images/0d2705c4-56c2-4d61-a16a-b1b36fde26dd", "id": "0d2705c4-56c2-4d61-a16a-b1b36fde26dd", "size": 25165824}, {"status": "active", "name": "cirros-0.3.2-x86_64-uec-ramdisk", "tags": [], "container_format": "bare", "created_at": "2014-09-19T10:09:05Z", "size": 3723817, "disk_format": "qcow2", "updated_at": "2014-09-19T10:09:05Z", "visibility": "public", "locations": [{"url": "file:///opt/stack/data/glance/images/07c85e37-c7ff-4094-98e3-f3846e524ef0", "metadata": {}}], "self": "/v2/images/07c85e37-c7ff-4094-98e3-f3846e524ef0", "min_disk": 0, "protected": false, "id": "07c85e37-c7ff-4094-98e3-f3846e524ef0", "file": "/v2/images/07c85e37-c7ff-4094-98e3-f3846e524ef0/file", "checksum": "68085af2609d03e51c7662395b5b6e4b", "owner": "8c673f31843d438ca2562a6f66531482", "direct_url": "file:///opt/stack/data/glance/images/07c85e37-c7ff-4094-98e3-f3846e524ef0", "min_ram": 0, "schema": "/v2/schemas/image"}, {"status": "queued", "name": "cirros-0.3.2-x86_64-uec-kernel", "tags": [], "container_format": "bare", "created_at": "2014-09-19T10:09:04Z", "disk_format": "qcow2", "updated_at": "2014-09-19T10:09:04Z", "visibility": "public", "locations": [], "self": "/v2/images/78c84922-a2bc-4694-a546-7a0471b1668e", "min_disk": 0, "protected": false, "id": "78c84922-a2bc-4694-a546-7a0471b1668e", "file": "/v2/images/78c84922-a2bc-4694-a546-7a0471b1668e/file", "owner": "8c673f31843d438ca2562a6f66531482", "size": 4969360, "min_ram": 0, "schema": "/v2/schemas/image"}], "schema": "/v2/schemas/images", "first": "/v2/images"}
Error Execution Example¶
HTTP Request¶
GET /v2/images?limit=test HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:9292
Accept: */*
X-Auth-Token: 9e55330892434fc78e86ee09e50a95ee
HTTP Response¶
HTTP/1.1 400 Bad Request
Content-Length: 156
Content-Type: text/html; charset=UTF-8
X-Openstack-Request-Id: req-7d3c0e38-58e9-4048-b3bf-de6647ecfd4f
Date: Thu, 15 Oct 2015 11:52:42 GMT
400 Bad Request
limit param must be an integer