• Native OpenStack API

noa
  1. Help Center
  2. Native OpenStack API
  3. API Reference
  4. Nova
  5. ECSs
  6. Querying ECSs

Querying ECSs

Function Description

This interface is used to query ECSs meeting the search criteria from the database.

Interface Format

Method

URI

Description

GET

/v2/{tenant_id}/servers

/v2.1/{tenant_id}/servers

Queries all ECSs of the tenant who sends the request.

Restrictions

When the image parameter is used as a filter condition, other filter conditions and pagination conditions are not supported. The image parameter prevails if several conditions are specified. When the image parameter is not taken as the filter condition, the interface function is not restricted.

Expanded Interface

N/A

Request Parameter

The query results are displayed in ascending or descending order by page. For details about the paging parameters, see the OpenStack API Complete Reference.

You can set image, flavor, name, status, changes-since, all_tenants, and ip as URI parameters to filter query results. An example of setting the parameters as URI parameters is as follows:

/v2/{tenant_id}/servers?flavor={flavorRef}&status={status}

When the image parameter is taken as the filter condition, you need to pay attention to restrictions.

Parameter

Type

Mandatory

Description

image

String

No

Specifies the image ID.

flavor

String

No

Specifies the flavor ID.

name

String

No

Specifies the ECS name. This parameter supports fuzzy matching.

status

String

No

Specifies the ECS status. Only the administrators can use the deleted state to filter out deleted ECSs.

changes-since

String

No

Filters out the ECSs that have been updated since the changes-since time. The value is in ISO8601 format, such as 2013-06-09T06:42:18Z.

all_tenants

Int

No

Specifies whether to query ECSs of all tenants.

Only administrators can set the parameter. The value can be 0 (do not query the ECSs of all tenants) or 1 (query the ECSs of all tenants).

ip

String

No

Specifies the IP address. You can query ECSs using fuzzy query.

availability_zone

String

No

Specifies the AZ, which is queried using fuzzy match.

ip6

String

No

Specifies to filter ECSs by IPv6 address.

This field is newly added in version 2.5.

not-tags

String

No

Specifies to filter ECSs by tag. ECSs not meeting all the tag requirements will be displayed.

This field is newly added in version 2.26.

not-tags-any

String

No

Specifies to filter ECSs by tag. ECSs not meeting any tag requirement will be displayed.

This field is newly added in version 2.26.

tags

String

No

Specifies to filter ECSs by tag. ECSs meeting all the tag requirements will be displayed.

This field is newly added in version 2.26.

tags-any

String

No

Specifies to filter ECSs by tag. ECSs meeting any tag requirement will be displayed.

This field is newly added in version 2.26.

Response Parameter

Parameter

Type

Mandatory

Description

ECS information

Dict ('servers',list<dict>)

Yes

The key is servers, and the value is a list. Items in the list indicate the ECS details. For details, see the following table.

Parameter

Type

Mandatory

Description

id

UUID

Yes

Specifies the ECS UUID.

links

List(Dict)

Yes

Provides the shortcut link to the ECS.

name

String

Yes

Specifies the ECS name.

Table 1 links parameters

Parameter

Type

Mandatory

Description

href

String

Yes

Specifies the URL.

ref

String

Yes

The value can be:

  • self: A self link contains the versioned link to the resource. Use these links when the link is followed immediately.
  • bookmark: A bookmark link provides a permanent link to a resource, which is suitable for long-term storage.

Request Example

GET /v2/9c53a566cb3443ab910cf0daebca90c4/servers?flavor="2"&status="active"

GET /v2.1/9c53a566cb3443ab910cf0daebca90c4/servers?flavor="2"&status="active"

Response Example

 {
    "servers": [
        {
            "id": "80402c14-9788-4b5c-b9d1-46fbd2d74c8a",
            "links": [
                {
                    "href": "http://192.168.82.222:8774/v2/9c53a566cb3443ab910cf0daebca90c4/servers/80402c14-9788-4b5c-b9d1-46fbd2d74c8a",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.82.222:8774/9c53a566cb3443ab910cf0daebca90c4/servers/80402c14-9788-4b5c-b9d1-46fbd2d74c8a",
                    "rel": "bookmark"
                }
            ],
            "name": "wjvm4"
        },
        {
            "id": "d8b1f52e-65ec-43ca-a73a-c10a509a4ee3",
            "links": [
                {
                    "href": "http://192.168.82.222:8774/v2/9c53a566cb3443ab910cf0daebca90c4/servers/d8b1f52e-65ec-43ca-a73a-c10a509a4ee3",
                    "rel": "self"
                },
                {
                    "href": "http://192.168.82.222:8774/9c53a566cb3443ab910cf0daebca90c4/servers/d8b1f52e-65ec-43ca-a73a-c10a509a4ee3",
                    "rel": "bookmark"
                }
            ],
            "name": "wjvm3"
        }
    ]
}

Returned Values

See section General Request Returned Values.

Error Code

Table 2 Task error code

Error Code

Description

403

Only administrators may list deleted instances.

This error occurs because a non-administrator user queries the deleted ECSs.