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