• Native OpenStack API

noa
  1. Help Center
  2. Native OpenStack API
  3. API Reference
  4. Glance
  5. Image (Native OpenStack APIs)
  6. Querying Images (Native OpenStack API)

Querying Images (Native OpenStack API)

Function

This API is used to obtain the image list.

This API does not return the complete result at once, but uses pagination.

Pagination

Pagination refers to the function of returning a subset of a group of images, a link to obtain the next set of images, and a link of the set of images. By default, a set contains 25 images. You can also use the limit and marker parameters to paginate through images manually and specify the number of images that can be returned.

The parameter first in the response indicates the URL of the first page of images, and parameter next indicates the URL of the next page of images. When the last page of images is queried, there is no parameter next.

URI

  • URI format

    GET /v2/images

    NOTE:
    • You can type a question mark (?) and an ampersand (&) at the end of the URI to define multiple search criteria. For details, see the example request.
  • URI parameter description

    Parameter

    Mandatory

    Type

    Description

    __isregistered

    No

    String

    Specifies whether the image is available. The value can be true. The value is true for all extension APIs by default. Common users can query only the images for which the value of this parameter is true.

    __imagetype

    No

    String

    Specifies the image type. The following types are supported:

    • Public image: The value is gold.
    • Private image: The value is private.
    • Shared image: The value is shared.

    protected

    No

    Boolean

    Specifies whether the image is protected. The value is true or false. Set it to true when you query public images. This parameter is optional when you query private images.

    visibility

    No

    String

    Specifies whether the image is available to other tenants. Available values include:

    • public: public image
    • private: private image
    • shared: shared image

    owner

    No

    String

    Specifies the image owner.

    id

    No

    String

    Specifies the image ID.

    status

    No

    String

    Specifies the image status. The value can be one of the following:

    • queued: indicates that the image metadata has already been created, and it is ready for the image file to upload.
    • saving: indicates that the image file is being uploaded to the backend storage.
    • deleted: indicates that the image has been deleted.
    • killed: indicates that an error occurs on the image uploading.
    • active: indicates that the image is available for use.

    name

    No

    String

    Specifies the image name. For detailed description, see Image Attributes.

    container_format

    No

    String

    Specifies the container type. The default value is bare.

    disk_format

    No

    String

    Specifies the image format. The value can be vhd, raw, zvhd, or qcow2. The default value is vhd.

    min_ram

    No

    Int

    Specifies the minimum memory size (MB) required for running the image. The parameter value depends on the ECS specifications limit. The value is generally set to 0.

    min_disk

    No

    Int

    Specifies the minimum disk space (GB) required for running the image. The value ranges from 1 GB to 1024 GB.

    __os_bit

    No

    String

    Specifies the OS architecture, 32 bit or 64 bit.

    __platform

    No

    String

    Specifies the image platform type. The value can be Windows, Ubuntu, RedHat, SUSE, CentOS, Debian, OpenSUSE, Oracle Linux, Fedora, Other, CoreOS, or EulerOS.

    marker

    No

    String

    Specifies the start number from which images are queried. The value is the image ID.

    limit

    No

    Int

    Specifies the number of images to be queried. The value is an integer. By default, 25 images can be queried.

    sort_key

    No

    String

    Specifies the field for sorting the query results. The value can be an attribute of the image: name, container_format, disk_format, status, id, size, or create_at. The default value is create_at.

    sort_dir

    No

    String

    Specifies whether the query results are sorted in ascending or descending order. Its value can be desc (default) or asc. This parameter is used together with parameter sort_key. The default value is desc.

    __os_type

    No

    String

    Indicates the image OS type. The value can be Linux, Windows, or Other.

    tag

    No

    String

    Specifies a tag added to an image. Tags can be used as a filter to query images.

    NOTE:

    The tagging function has been upgraded. If the tags added before the function upgrade are in the format of "Key.Value", query tags using "Key=Value". For example, an existing tag is a.b. After the tag function upgrade, query the tag using "tag=a=b".

    member_status

    No

    String

    Specifies the member status. The value can be accepted, rejected, or pending. accepted: indicates that the shared image is accepted. rejected indicates that the image shared by others is rejected. pending indicates that the image shared by others needs to be confirmed. To use this parameter, set visibility to shared during the query.

    __support_kvm

    No

    String

    Specifies whether the image supports KVM. If yes, the value is true. Otherwise, this attribute is not required.

    __support_xen

    No

    String

    Specifies whether the image supports Xen. If yes, the value is true. Otherwise, this attribute is not required.

    __support_largememory

    No

    String

    Specifies whether the image supports large-memory ECSs. If the image supports large-memory ECSs, the value is true. Otherwise, this attribute is not required. For details about the image OSs supported by large-memory ECSs, see Table 3.

    __support_diskintensive

    No

    String

    Specifies whether the image supports disk-intensive ECSs. If the image supports disk-intensive ECSs, the value is true. Otherwise, this attribute is not required. For details about the image OSs supported by disk-intensive ECSs, see Table 3.

    __support_highperformance

    No

    String

    Specifies whether the image supports high-performance ECSs. If the image supports high-performance ECSs, the value is true. Otherwise, this attribute is not required. For details about the image OSs supported by high-performance computing ECSs, see Table 3.

    __support_xen_gpu_type

    No

    String

    Specifies whether the image is supported by GPU ECSs on Xen. See Table 2 for its value. For the OSs supported by GPU-accelerated ECSs, see Table 3. If the image does not support GPU-optimized ECSs on the Xen platform, this attribute is not required. This attribute cannot co-exist with __support_xen and __support_kvm.

    __support_kvm_gpu_type

    No

    String

    Specifies whether the image supports GPU-optimized ECSs on the KVM platform. See Table 2 for its value. If the image does not support GPU-optimized ECSs on the KVM platform, this attribute is not required. This attribute cannot co-exist with __support_xen and __support_kvm.

    __support_xen_hana

    No

    String

    Specifies whether the image supports HANA ECSs on the Xen platform. If yes, the value is true. Otherwise, this attribute is not required.

    This attribute cannot co-exist with __support_xen and __support_kvm.

    __support_kvm_infiniband

    No

    String

    Specifies whether the image supports ECSs with the InfiniBand NIC on the KVM platform. If yes, the value is true. Otherwise, this attribute is not required.

    This attribute cannot co-exist with __support_xen.

    created_at

    No

    String

    Specifies the time when the image was created. Images can be queried by time. The value is in the format of Operator:UTC time.

    The following operators are supported:

    • gt: greater than
    • gte: greater than or equal to
    • lt: less than
    • lte: less than or equal to
    • eq: equal to
    • neq: not equal to

    The time format is yyyy-MM-ddThh:mm:ssZ or yyyy-MM-dd hh:mm:ss.

    For example, to query images whose creation time is earlier than Oct 28, 2018 10:00:00, set the value of created_at to gt:2018-10-28T10:00:00Z.

    updated_at

    No

    String

    Specifies the time when the image was modified. Images can be queried by time. The value is in the format of Operator:UTC time.

    The following operators are supported:

    • gt: greater than
    • gte: greater than or equal to
    • lt: less than
    • lte: less than or equal to
    • eq: equal to
    • neq: not equal to

    The time format is yyyy-MM-ddThh:mm:ssZ or yyyy-MM-dd hh:mm:ss.

    For example, to query images whose creation time is earlier than Oct 28, 2018 10:00:00, set the value of created_at to gt:2018-10-28T10:00:00Z.

Common Query Methods

  • Public images

    GET /v2/images?__imagetype=gold&visibility=public&protected=true

  • Private images

    GET /v2/images?owner={project_id}

  • Shared images

    GET /v2/images?member_status=accepted&visibility=shared&__imagetype=shared

  • Rejected images

    GET /v2/images?member_status=rejected&visibility=shared&__imagetype=shared

  • Unaccepted images

    GET /v2/images?member_status=pending&visibility=shared&__imagetype=shared

Request

  • Parameter description

    None

  • Example request
    GET https://{Endpoint}/v2/images

Response

  • Response parameters

    Parameter

    Type

    Description

    __isregistered

    String

    Specifies whether the image is available. The value can be true. The value is true for all extension APIs by default. Common users can query only the images for which the value of this parameter is true.

    __imagetype

    String

    Specifies the image type. The following types are supported:

    • Public image: The value is gold.
    • Private image: The value is private.
    • Shared image: The value is shared.

    protected

    Boolean

    Specifies whether the image is protected. Set it to true when you query public images. This parameter is optional when you query private images.

    visibility

    String

    Specifies whether the image is available to other tenants. The value can be one of the following:

    • public: public image
    • private: private image
    • shared: shared image

    owner

    String

    Specifies the image owner.

    id

    String

    Specifies the image ID.

    status

    String

    Specifies the image status. The value can be one of the following:

    • queued: indicates that the image metadata has already been created, and it is ready for the image file to upload.
    • saving: indicates that the image file is being uploaded to the backend storage.
    • deleted: indicates that the image has been deleted.
    • killed: indicates that an error occurs on the image uploading.
    • active: indicates that the image is available for use.

    name

    String

    Specifies the image name. For detailed description, see Image Attributes.

    container_format

    String

    Specifies the container type.

    disk_format

    String

    Specifies the image format. The value can be vhd, raw, zvhd, or qcow2. The default value is vhd.

    min_ram

    Int

    Specifies the minimum memory size (MB) required for running the image. The parameter value depends on the ECS specifications limit. The value is generally set to 0.

    min_disk

    Int

    Specifies the minimum disk space (GB) required for running the image. The value ranges from 1 GB to 1024 GB.

    __os_bit

    String

    Specifies the OS architecture, 32 bit or 64 bit.

    __platform

    String

    Specifies the image platform type. The value can be Windows, Ubuntu, RedHat, SUSE, CentOS, Debian, OpenSUSE, Oracle Linux, Fedora, Other, CoreOS, or EulerOS.

    marker

    String

    Specifies the start number from which images are queried. The value is the image ID.

    limit

    Int

    Specifies the number of images to be queried. The value is an integer. By default, 25 images can be queried.

    sort_key

    String

    Specifies the field for sorting the query results. The value can be an attribute of the image: name, container_format, disk_format, status, id, or size. The default value is created_at.

    sort_dir

    String

    Specifies whether the query results are sorted in ascending or descending order. Its value can be desc (default) or asc. This parameter is used together with parameter sort_key. The default value is desc.

    __os_type

    String

    Indicates the image OS type. The value can be Linux, Windows, or Other.

    tags

    List<String>

    Specifies a tag added to an image. Tags can be used as a filter to query images.

    member_status

    String

    Specifies the member status. The value can be accepted, rejected, or pending. accepted: indicates that the shared image is accepted. rejected indicates that the image shared by others is rejected. pending indicates that the image shared by others needs to be confirmed. To use this parameter, set visibility to shared during the query.

    __support_kvm

    String

    Specifies whether the image supports KVM. If yes, the value is true. Otherwise, this attribute is not required.

    __support_xen

    String

    Specifies whether the image supports Xen. If yes, the value is true. Otherwise, this attribute is not required.

    __support_largememory

    String

    Specifies whether the image supports large-memory ECSs. If the image supports large-memory ECSs, the value is true. Otherwise, this attribute is not required. For details about the image OSs supported by large-memory ECSs, see Table 3.

    __support_diskintensive

    String

    Specifies whether the image supports disk-intensive ECSs. If the image supports disk-intensive ECSs, the value is true. Otherwise, this attribute is not required. For details about the image OSs supported by disk-intensive ECSs, see Table 3.

    __support_highperformance

    String

    Specifies whether the image supports high-performance ECSs. If the image supports high-performance ECSs, the value is true. Otherwise, this attribute is not required. For details about the image OSs supported by high-performance computing ECSs, see Table 3.

    __support_xen_gpu_type

    String

    Specifies whether the image is supported by GPU ECSs on Xen. See Table 2 for its value. For the OSs supported by GPU-accelerated ECSs, see Table 3. If the image does not support GPU-optimized ECSs on the Xen platform, this attribute is not required. This attribute cannot co-exist with __support_xen and __support_kvm.

    __support_kvm_gpu_type

    String

    Specifies whether the image supports GPU-optimized ECSs on the KVM platform. See Table 2 for its value. If the image does not support GPU-optimized ECSs on the KVM platform, this attribute is not required. This attribute cannot co-exist with __support_xen and __support_kvm.

    __support_xen_hana

    String

    Specifies whether the image supports HANA ECSs on the Xen platform. If yes, the value is true. Otherwise, this attribute is not required.

    This attribute cannot co-exist with __support_xen and __support_kvm.

    __support_kvm_infiniband

    String

    Specifies whether the image supports ECSs with the InfiniBand NIC on the KVM platform. If yes, the value is true. Otherwise, this attribute is not required.

    This attribute cannot co-exist with __support_xen.

    __root_origin

    String

    Indicates that the image is created from an external image file. Example value: file

    __sequence_num

    String

    Specifies the ECS system disk slot number corresponding to the image.

    Example value: 0

    images

    List (Image)

    Specifies the resource type.

    first

    String

    Specifies the URL of the first page of images.

    next

    String

    Specifies the URL of the next page of images. When the last page of images is queried, there is no parameter next.

    schema

    String

    Specifies the URL for the schema describing a list of images.

  • Example response
    STATUS CODE 200
    {
      "schema": "/v2/schemas/images",
      "next": "/v2/images?__isregistered=true&marker=0328c25e-c840-4496-81ac-c4e01b214b1f&__imagetype=gold&limit=2",
      "images": [
        {
          "schema": "/v2/schemas/image",
          "min_disk": 100,
          "created_at": "2018-09-06T14:03:27Z",
          "__image_source_type": "uds",
          "container_format": "bare",
          "file": "/v2/images/bc6bed6e-ba3a-4447-afcc-449174a3eb52/file",
          "updated_at": "2018-09-06T15:17:33Z",
          "protected": true,
          "checksum": "d41d8cd98f00b204e9800998ecf8427e",
          "__support_kvm_fpga_type": "VU9P",
          "id": "bc6bed6e-ba3a-4447-afcc-449174a3eb52",
          "__isregistered": "true",
          "min_ram": 2048,
          "__lazyloading": "true",
          "owner": "1bed856811654c1cb661a6ca845ebc77",
          "__os_type": "Linux",
          "__imagetype": "gold",
          "visibility": "public",
          "virtual_env_type": "FusionCompute",
          "tags": [],
          "__platform": "CentOS",
          "size": 0,
          "__os_bit": "64",
          "__os_version": "CentOS 7.3 64bit",
          "name": "CentOS 7.3 64bit vivado",
          "self": "/v2/images/bc6bed6e-ba3a-4447-afcc-449174a3eb52",
          "disk_format": "zvhd2",
          "virtual_size": null,
          "status": "active"
        },
        {
          "schema": "/v2/schemas/image",
          "min_disk": 100,
          "created_at": "2018-09-06T14:03:05Z",
          "__image_source_type": "uds",
          "container_format": "bare",
          "file": "/v2/images/0328c25e-c840-4496-81ac-c4e01b214b1f/file",
          "updated_at": "2018-09-25T14:27:40Z",
          "protected": true,
          "checksum": "d41d8cd98f00b204e9800998ecf8427e",
          "__support_kvm_fpga_type": "VU9P_COMMON",
          "id": "0328c25e-c840-4496-81ac-c4e01b214b1f",
          "__isregistered": "true",
          "min_ram": 2048,
          "__lazyloading": "true",
          "owner": "1bed856811654c1cb661a6ca845ebc77",
          "__os_type": "Linux",
          "__imagetype": "gold",
          "visibility": "public",
          "virtual_env_type": "FusionCompute",
          "tags": [],
          "__platform": "CentOS",
          "size": 0,
          "__os_bit": "64",
          "__os_version": "CentOS 7.3 64bit",
          "name": "CentOS 7.3 64bit with sdx",
          "self": "/v2/images/0328c25e-c840-4496-81ac-c4e01b214b1f",
          "disk_format": "zvhd2",
          "virtual_size": null,
          "status": "active"
        }
      ],
      "first": "/v2/images?__isregistered=true&__imagetype=gold&limit=2"
    }
    

Returned Values

  • Normal

    200

  • Abnormal

    Returned Value

    Description

    400 Bad Request

    Request error. For details about the returned error code, see Error Codes.

    401 Unauthorized

    Authentication failed.

    403 Forbidden

    You do not have the rights to perform the operation.

    404 Not Found

    The requested resource was not found.

    500 Internal Server Error

    Internal service error.

    503 Service Unavailable

    The service is unavailable.