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.