glance/api-ref/source/v2/images-parameters.yaml
vinay_m 3949fc467c api-ref needs update about 'checksum' image prop
Modified the "Checksum" description as mentioned , it is not computed from
victoria release .
Closes-Bug: #1875629

Change-Id: Id4299c7e02298157ad88971a78fac72a9f0248d0
2022-04-11 22:24:27 +00:00

737 lines
21 KiB
YAML

# variables in header
cache-clear-header:
description: |
A keyword indicating 'cache', 'queue' or empty string to indicate the delete
API to delete images from cache or queue or delete from both. If this header
is missing then all cached and queued images for caching will be deleted.
in: header
required: false
type: string
Content-Length:
description: |
The length of the body in octets (8-bit bytes)
in: header
required: true
type: string
Content-Md5:
description: |
The MD5 checksum of the body.
in: header
required: true
type: string
Content-Range:
description: |
The content range of image data. For details, see
`Hypertext Transfer Protocol (HTTP/1.1): Range Requests
<http://tools.ietf.org/html/rfc7233>`_.
in: header
required: false
type: string
Content-Type-data:
description: |
The media type descriptor for the request body. Use
``application/octet-stream``
in: header
required: true
type: string
Content-Type-data-response:
description: |
The media type descriptor of the response body, namely
``application/octet-stream``
in: header
required: true
type: string
Content-Type-json:
description: |
The media type descriptor for the request body. Use
``application/json``.
in: header
required: true
type: string
Content-Type-patch:
description: |
The media type descriptor for the request body. Use
``application/openstack-images-v2.1-json-patch``. (You can also use
``application/openstack-images-v2.0-json-patch``, but keep in mind that
it's deprecated.)
in: header
required: true
type: string
import-header:
description: |
A comma separated list of import method identifiers. Included
only if image import is enabled in your cloud. *Since Image API v2.6*
in: header
required: false
type: string
Location:
description: |
The URL to access the image file from the
external store.
in: header
required: true
type: string
Range:
description: |
The range of image data requested. Note that multi range requests are
not supported. For details, see
`Hypertext Transfer Protocol (HTTP/1.1): Range Requests
<http://tools.ietf.org/html/rfc7233>`_.
in: header
required: false
type: string
store-header:
description: |
A store identifier to upload or import image data. Should only be included
when making a request to a cloud that supports multiple backing stores. Use
the :ref:`Store Discovery <store-discovery-call>` call to determine an
appropriate store identifier. Simply omit this header to use the default
store. *(Since Image API v2.8)*
in: header
required: false
type: string
stores-header:
description: |
A comma separated list of available store identifiers. If this header
is missing the cloud does not support multiple backend stores.
in: header
required: false
type: string
# variables in path
image_id-in-path:
description: |
The UUID of the image.
in: path
required: true
type: string
member_id-in-path:
description: |
The ID of the image member. An image member is usually the project (also
called the "tenant") with whom the image is shared.
in: path
required: true
type: string
store-in-path:
description: |
The ID of the store from which image is to be deleted.
in: path
required: true
type: string
tag-in-path:
description: |
The image tag. A tag is limited to 255 chars in length. You may wish
to use characters that can easily be written in a URL.
in: path
required: true
type: string
# variables in query
created_at-in-query:
description: |
Specify a *comparison filter* based on the date and time when the resource
was created. (See :ref:`Time Comparison Filters <v2-comparison-ops>`).
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
in: query
required: false
type: string
limit:
description: |
Requests a page size of items. Returns a number of items up to a limit
value. Use the ``limit`` parameter to make an initial limited request and
use the ID of the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: integer
marker:
description: |
The ID of the last-seen item. Use the ``limit`` parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the ``marker`` parameter value in a subsequent limited request.
in: query
required: false
type: string
member_status-in-query:
description: |
Filters the response by a member status. A valid value is ``accepted``,
``pending``, ``rejected``, or ``all``. Default is ``accepted``.
in: query
required: false
type: string
name-in-query:
description: |
Filters the response by a name, as a string. A valid value is the name of
an image.
in: query
required: false
type: string
os_hidden-in-query:
description: |
When ``true``, filters the response to display only "hidden" images. By
default, "hidden" images are not included in the image-list response.
*(Since Image API v2.7)*
in: query
required: false
type: boolean
owner-in-query:
description: |
Filters the response by a project (also called a "tenant") ID. Shows only
images that are shared with you by the specified owner.
in: query
required: false
type: string
protected-in-query:
description: |
Filters the response by the 'protected' image property. A valid value is
one of 'true', 'false' (must be all lowercase). Any other value will
result in a 400 response.
in: query
required: false
type: boolean
size_max:
description: |
Filters the response by a maximum image size, in
bytes.
in: query
required: false
type: string
size_min:
description: |
Filters the response by a minimum image size, in
bytes.
in: query
required: false
type: string
sort:
description: |
Sorts the response by one or more attribute and sort direction
combinations. You can also set multiple sort keys and directions.
Default direction is ``desc``.
Use the comma (``,``) character to separate multiple values. For
example:
.. code-block:: none
GET /v2/images?sort=name:asc,status:desc
in: query
required: false
type: string
sort_dir:
description: |
Sorts the response by a set of one or more sort
direction and attribute (``sort_key``) combinations. A valid value
for the sort direction is ``asc`` (ascending) or ``desc``
(descending). If you omit the sort direction in a set, the default
is ``desc``.
in: query
required: false
type: string
sort_key:
description: |
Sorts the response by an attribute, such as
``name``, ``id``, or ``updated_at``. Default is ``created_at``.
The API uses the natural sorting direction of the ``sort_key``
image attribute.
in: query
required: false
type: string
status-in-query:
description: |
Filters the response by an image status.
in: query
required: false
type: integer
tag-in-query:
description: |
Filters the response by the specified tag value. May be repeated, but keep
in mind that you're making a conjunctive query, so only images containing
*all* the tags specified will appear in the response.
in: query
required: false
type: string
updated_at-in-query:
description: |
Specify a *comparison filter* based on the date and time when the resource
was most recently modified. (See :ref:`Time Comparison Filters
<v2-comparison-ops>`).
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
in: query
required: false
type: string
visibility-in-query:
description: |
Filters the response by an image visibility value. A valid value is
``public``, ``private``, ``community``, ``shared``, or ``all``. (Note
that if you filter on ``shared``, the images included in the response
will only be those where your member status is ``accepted`` unless you
explicitly include a ``member_status`` filter in the request.) If you
omit this parameter, the response shows ``public``, ``private``, and those
``shared`` images with a member status of ``accepted``.
in: query
required: false
type: string
# variables in body
all-stores-in-request:
description: |
When set to True the data will be imported to the set of stores you may
consume from this particular deployment of Glance (ie: the same set of
stores returned to a call to /v2/info/stores on the glance-api the request
hits).
This can't be used simultaneously with the ``stores`` parameter.
in: body
required: false
type: boolean
all-stores-succeed-in-request:
description: |
A boolean parameter indicating the behavior of the import workflow when an
error occurs.
When set to True (default), if an error occurs during the upload in at least one
store, the worfklow fails, the data is deleted from stores where copying
is done (not staging), and the state of the image is unchanged.
When set to False, the workflow will fail (data deleted from stores, ...)
only if the import fails on all stores specified by the user. In case of a
partial success, the locations added to the image will be the stores where
the data has been correctly uploaded. Default is True.
in: body
required: false
type: boolean
checksum:
description: |
An MD5 hash over the image data. The value might be ``null`` (JSON null data type),
as this field is no longer populated by the Image Service beginning with the
Victoria release. It remains present for backward compatibility with legacy
images. To validate image data, instead use the secure multihash fields
``os_hash_algo`` and ``os_hash_value``.
in: body
required: true
type: string
container_format:
description: |
|container_format_description|
in: body
required: true
type: enum
container_format-in-request:
description: |
|container_format_description|
in: body
required: false
type: enum
created_at:
description: |
The date and time when the resource was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
in: body
required: true
type: string
direct_url:
description: |
The URL to access the image file kept in external store. *It is present
only if the* ``show_image_direct_url`` *option is* ``true`` *in the Image
service's configuration file.* **Because it presents a security risk, this
option is disabled by default.**
in: body
required: false
type: string
disk_format:
description: |
|disk_format_description|
in: body
required: true
type: enum
disk_format-in-request:
description: |
|disk_format_description|
in: body
required: false
type: enum
file:
description: |
The URL for the virtual machine image file.
in: body
required: true
type: string
first:
description: |
The URI for the first page of response.
in: body
required: true
type: string
id:
description: |
A unique, user-defined image UUID, in the format:
::
nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where **n** is a hexadecimal digit from 0 to f, or F.
For example:
::
b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image.
in: body
required: true
type: string
id-in-request:
description: |
A unique, user-defined image UUID, in the format:
::
nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where **n** is a hexadecimal digit from 0 to f, or F.
For example:
::
b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image. If you
specify a value that has already been assigned, the request fails with
a ``409`` response code.
in: body
required: false
type: string
image_id-in-body:
description: |
The UUID of the image.
in: body
required: true
type: string
images:
description: |
A list of *image* objects, as described by the :ref:`Images Schema
<images-schema>`.
in: body
required: true
type: array
import-methods:
description: |
A JSON object containing a ``value`` element, which is an array of
string identifiers indicating what import methods are available in
the cloud in which the call is made. This list may be empty.
in: body
required: true
type: object
locations:
description: |
A list of objects, each of which describes an image location. Each object
contains a ``url`` key, whose value is a URL specifying a location, and a
``metadata`` key, whose value is a dict of key:value pairs containing
information appropriate to the use of whatever external store is indicated
by the URL. *This list appears only if the* ``show_multiple_locations``
*option is set to* ``true`` *in the Image service's configuration file.*
**Because it presents a security risk, this option is disabled by
default.**
in: body
required: false
type: array
member_id:
description: |
The ID of the image member. An image member is usually a project (also
called the "tenant") with whom the image is shared.
in: body
required: true
type: string
member_status:
description: |
The status of this image member. Value is one of ``pending``,
``accepted``, ``rejected``.
in: body
required: true
type: string
members:
description: |
A list of *member* objects, as described by the :ref:`Image Members Schema
<image-members-schema>`. Each *member* object describes a member with whom
this image is being shared.
in: body
required: true
type: array
method-in-request:
description: |
A JSON object indicating what import method you wish to use to import
your image. The content of this JSON object is another JSON object
with a ``name`` field whose value is the identifier for the import
method.
in: body
required: true
type: object
min_disk:
description: |
Amount of disk space in GB that is required to boot the image.
The value might be ``null`` (JSON null data type).
in: body
required: true
type: integer
min_disk-in-request:
description: |
Amount of disk space in GB that is required to boot the image.
in: body
required: false
type: integer
min_ram:
description: |
Amount of RAM in MB that is required to boot the image.
The value might be ``null`` (JSON null data type).
in: body
required: true
type: integer
min_ram-in-request:
description: |
Amount of RAM in MB that is required to boot the image.
in: body
required: false
type: integer
name:
description: |
The name of the image. Value might be ``null`` (JSON null data type).
in: body
required: true
type: string
name-in-request:
description: |
The name of the image.
in: body
required: false
type: string
next:
description: |
The URI for the next page of response. Will not be present on the last
page of the response.
in: body
required: true
type: string
os_hash_algo:
description: |
The algorithm used to compute a secure hash of the image data for this
image. The result of the computation is displayed as the value of the
``os_hash_value`` property. The value might be ``null`` (JSON null
data type). The algorithm used is chosen by the cloud operator; it
may not be configured by end users. *(Since Image API v2.7)*
in: body
required: true
type: string
os_hash_value:
description: |
The hexdigest of the secure hash of the image data computed using the
algorithm whose name is the value of the ``os_hash_algo`` property.
The value might be ``null`` (JSON null data type) if data has not
yet been associated with this image, or if the image was created using
a version of the Image Service API prior to version 2.7.
*(Since Image API v2.7)*
in: body
required: true
type: string
os_hidden:
description: |
This field controls whether an image is displayed in the default
image-list response. A "hidden" image is out of date somehow (for
example, it may not have the latest updates applied) and hence should
not be a user's first choice, but it's not deleted because it may be
needed for server rebuilds. By hiding it from the default image list,
it's easier for end users to find and use a more up-to-date version of
this image. *(Since Image API v2.7)*
in: body
required: true
type: boolean
owner:
description: |
An identifier for the owner of the image, usually the project (also
called the "tenant") ID.
The value might be ``null`` (JSON null data type).
in: body
required: true
type: string
protected:
description: |
A boolean value that must be ``false`` or the image cannot be deleted.
in: body
required: true
type: boolean
protected-in-request:
description: |
Image protection for deletion. Valid value is ``true`` or ``false``.
Default is ``false``.
in: body
required: false
type: boolean
schema-image:
description: |
The URL for the schema describing a virtual machine image.
in: body
required: true
type: string
schema-images:
description: |
The URL for the schema describing a list of images.
in: body
required: true
type: string
schema-member:
description: |
The URL for the schema describing an image member.
in: body
required: true
type: string
schema-members:
description: |
The URL for the schema describing an image member list.
in: body
required: true
type: string
self:
description: |
The URL for the virtual machine image.
in: body
required: true
type: string
size:
description: |
The size of the image data, in bytes. The value
might be ``null`` (JSON null data type).
in: body
required: true
type: integer
status:
description: |
The image status.
in: body
required: true
type: string
stores-in-request:
description: |
If present contains the list of store id to import the image binary data
to.
in: body
required: false
type: array
tags:
description: |
List of tags for this image, possibly an empty list.
in: body
required: true
type: array
tags-in-request:
description: |
List of tags for this image. Each tag is a string of at most 255 chars.
The maximum number of tags allowed on an image is set by the operator.
in: body
required: false
type: array
tasks:
description: |
A list of *task* objects, associated with the given image.
in: body
required: true
type: array
updated_at:
description: |
The date and time when the resource was updated.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC. In the previous example, the offset value is ``-05:00``.
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
in: body
required: true
type: string
url:
description: |
The URL to access the image file kept in external
store.
in: body
required: true
type: string
value:
description: |
Value of image property used in add or replace
operations expressed in JSON notation. For example, you must
enclose strings in quotation marks, and you do not enclose numeric
values in quotation marks.
in: body
required: true
type: string
virtual_size:
description: |
The virtual size of the image. The value might
be ``null`` (JSON null data type).
in: body
required: true
type: integer
visibility:
description: |
Image visibility, that is, the access permission for the image.
in: body
required: true
type: string
visibility-in-request:
description: |
Visibility for this image. Valid value is one of: ``public``, ``private``,
``shared``, or ``community``.
At most sites, only an administrator can make an image ``public``.
Some sites may restrict what users can make an image ``community``.
Some sites may restrict what users can perform member operations on
a ``shared`` image.
*Since the Image API v2.5, the default value is ``shared``.*
in: body
required: false
type: string