Update image¶
Overview¶
Updates a specified image.
Classification¶
Update
API Operation Object¶
images
Synchronous / Asynchronous¶
synchronous
Request¶
HTTP Request Method¶
PATCH
HTTP Request Path¶
{api_endpoint}/v2/images/{image_id}
HTTP Request Header¶
Format¶
X-Auth-Token: <token_id>
Content-Type: application/openstack-images-v2.1-json-patch
(Content-Type: application/openstack-images-v2.0-json-patch is deprecated)
User-Agent, Host, Accept, Content-Length fields are automatically added
HTTP Request Body¶
Format¶
* The request body can be specified in six patterns.
<<To add properties >>
[
{
"path": "/<path>",
"value": <value>,
"op": "<operation>"
},
<<repeat>>
]
<<To remove properties >>
[
{
"path": "/<path>",
"op": "<operation>"
},
<<repeat>>
]
<<To replace properties >>
[
{
"path": "/<path>",
"value": <value>,
"op": "<operation>"
},
<<repeat>>
]
Request Parameter¶
name |
style |
format |
description |
required/optional |
default value |
action for invalid parameter |
response code for invalid parameter |
---|---|---|---|---|---|---|---|
image_id |
URL |
UUID |
An identifier for the image |
required |
- |
Terminate |
404 |
token_id |
Header |
authentication token string |
Keystone authentication token |
required |
- |
Terminate |
401 |
path |
Body |
String |
Image's property |
required |
- |
Terminate |
400, 500 |
value |
Body |
String (json format) |
Value of image property used in add / replace operation expressed in JSON notation (For example, strings must be quoted, numeric values are unquoted) |
required (when operation is add or replace) |
- |
Terminate |
400 |
operation |
Body |
String ("add", "remove", "replace") |
|
required |
- |
Terminate |
500 |
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 insert field such as "X-Compute-Request-Id" and "Content-Length", "Date"
Response Code¶
response code |
condition |
---|---|
200 |
normal end |
400 |
empty body |
- |
call with malformed JSON |
- |
key 'op' is not specified |
- |
key 'path' is not specified |
- |
<path> does not start with "/" |
- |
<path> contains adjacent "/" |
- |
<path> end with "/" |
- |
<path> does not contains valid token |
- |
<path> contains not part of a recognized escape sequence |
- |
<path> depth does not match specified <operation> path depth (add's and remove's path depth is 2, replace's path depth is 1) |
- |
<value> is not specified when <operation> is add / remove |
- |
specify a invalid <value> for a property or location when <operation> is add / replace |
401 |
unauthorized |
403 |
|
- |
|
- |
specify a properties in <path> which is not allowed to remove |
- |
requested for replacing container_format of not 'queued' status image |
- |
requested for replacing disk_format of not 'queued' status image |
- |
if authority of non admin, image has no owner |
- |
if authority of non admin, requested by user whose project is not the owner of specified private image |
- |
if authority of non admin, requested for replacing visibility to public |
404 |
specify non-existent image_id |
- |
specify the image_id of deleted image |
- |
if authority of non admin, requested by user whose project is not the member and not the owner of specified private image (assuming that the image has owner) |
409 |
Specify a exsiting property of the specified image when <operation> is add |
- |
Specify a non-existent property of the specified image when <operation> is replace / remove |
413 |
The number of image properties exceeds the limit |
- |
The number of image tags exceeds the limit |
- |
Specified image's file (location) size exceeds the total capacity which user can use across all storage systems |
415 |
Content-Type does not specify 'application/openstack-images-v2.1-json-patch' |
500 |
specify a invalid <operation> |
- |
specify 'None' in <path> |
- |
specify int in the value of <metadata> |
- |
specify '2^16 - 1' or more value in the value of <metadata> |
HTTP Response Body¶
Format¶
{
"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>>
],
*"<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>"
}
* 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 |
metadata |
|
The location metadata |
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 |
Sample API Request and Response¶
Sample API Request¶
Request URI¶
https://example.com/v2/images/{image_id}
Request Header¶
X-Auth-Token: <token_id>
Content-Type: application/openstack-images-v2.1-json-patch
(Content-Type: application/openstack-images-v2.0-json-patch is deprecated)
User-Agent, Host, Accept, Content-Length fields are automatically added
Request Body¶
* The request body can be specified in six patterns.
<<To add properties >>
[
{
"path": "/<path>",
"value": <value>,
"op": "<operation>"
},
<<repeat>>
]
<<To remove properties >>
[
{
"path": "/<path>",
"op": "<operation>"
},
<<repeat>>
]
<<To replace properties >>
[
{
"path": "/<path>",
"value": <value>,
"op": "<operation>"
},
<<repeat>>
]
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 insert field such as "X-Compute-Request-Id" and "Content-Length", "Date"
Response Body¶
{
"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>>
],
*"<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>"
}
* There are multiple set of <extra_key> and <extra_value> which user added
Execution Example¶
HTTP Request¶
PATCH /v2/images/5521fbf2-0b89-4b7c-91b5-e3afbecd4a35 HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.11.141:9292
Accept: */*
X-Auth-Token: 896d37fcb1f34f1392537b0ffbc60064
Content-Type: application/openstack-images-v2.1-json-patch
Content-Length: 85
[{"path":"/extra3", "value":"extra3", "op":"add"}, {"path":"/extra2", "op":"remove"}]
HTTP Response¶
HTTP/1.1 200 OK
Content-Length: 713
Content-Type: application/json; charset=UTF-8
X-Openstack-Request-Id: req-133e4f2f-118a-4db9-8287-38ae2a9eeabc
Date: Wed, 24 Sep 2014 11:06:54 GMT
{"status": "active", "schema": "/v2/schemas/image", "name": "private_admin_admin", "tags": ["tag1", "tag2", "tag3"], "updated_at": "2014-09-24T11:06:54Z", "container_format": "bare", "min_ram": 0, "disk_format": "qcow2", "locations": [{"url": "file:///home/stack/test", "metadata": {"meta_key": "meta"}}], "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", "id": "5521fbf2-0b89-4b7c-91b5-e3afbecd4a35", "size": 25165824}
Error Execution Example¶
HTTP Request¶
PATCH /v2/images/455af5de-e503-46de-9884-f0334f5b17e0 HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:9292
Accept: */*
X-Auth-Token: fa72b568b7874a35a835b2639f51fbbc
Content-type: application/openstack-images-v2.1-json-patch
Content-Length: 83
HTTP Response¶
HTTP/1.1 400 Bad Request
Content-Length: 157
Content-Type: text/html; charset=UTF-8
X-Openstack-Request-Id: req-2597d5da-b568-471d-84f8-711c0de0dd2e
Date: Thu, 15 Oct 2015 12:17:16 GMT
400 Bad Request
Malformed JSON in request body.