• Native OpenStack API

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

Querying ECSs

Function

This API is used to query ECSs.

URI

GET /v2.1/{project_id}/servers{?changes-since,image,flavor,name,status,limit,marker,not-tags,reservation_id}

Table 1 describes the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

Request

Request parameters

Table 2 describes the request parameters.

Table 2 Request parameters

Parameter

Mandatory

Type

Description

changes-since

No

String:DateTime

Specifies the timestamp when the ECS status was updated last time. The format complies with ISO 8601 standards, for example:

CCYY-MM-DDThh:mm:ss+/-hh:mm

NOTE:

ECSs in deleted state can be queried.

image

No

String

Specifies the image ID.

When image is used as a filter criterion, other filter criteria and paging criteria are not supported. If both the image and other filter criteria are specified, the image filter criterion prevails. If the query criteria do not contain the image filter criterion, API functions are not restricted.

ip

No

String

Indicates the IPv4 address filtering result.

flavor

No

String

Specifies the ECS ID.

name

No

String

Specifies the ECS name.

status

No

String

Specifies the ECS status.

Options:

ACTIVE, BUILD, DELETED, ERROR, HARD_REBOOT, MIGRATING, PAUSED, REBOOT, REBUILD, RESIZE, REVERT_RESIZE, SHUTOFF, SHELVED, SHELVED_OFFLOADED, SOFT_DELETED, SUSPENDED, and VERIFY_RESIZE

In microversion 2.37, the system will return an empty list for the status field out of the preceding options. In microversion 2.38 and later, the system will return error 404.

host

No

String

Specifies the host name.

limit

No

Integer

Specifies the upper limit on the number of returned results.

marker

No

String

Specifies the marker that points to the ECS ID. The query will start from its next ID.

tags

No

String

This field is limited in microversion 2.26.

not-tags

No

String

This field is limited in microversion 2.26.

Queries ECSs with tags not containing the specified value. The value is the tag key.

For details about key rules, see Tag Types.

NOTE:

Tag functions have been upgraded on the public cloud. If the tags added before the function upgrade are in the format of "Key.Value", query tags using "Key".

For example, an existing tag is a.b. After the tag function upgrade, query the tag using "not-tags=a".

reservation_id

No

String

Specifies the ID returned when ECSs are created in a batch. This parameter is used to query ECSs created in a batch.

sort_key

No

String

Sorts query results by ECS attribute. The default sorting order is the reverse order of created_at.

Response

Response parameters

Table 3 describes the response parameters.

Table 3 Response parameters

Parameter

Type

Description

servers

List data structure

Specifies the ECSs to be queried. For details, see Table 4.

Table 4 servers field description

Parameter

Type

Description

name

String

Specifies the ECS name.

id

String

Specifies an ECS uniquely.

links

List data structure

Specifies ECS shortcut links. For details, see Table 5.

Table 5 links field description

Parameter

Type

Description

rel

String

Specifies the shortcut link marker name.

href

String

Specifies the shortcut link.

Examples

  • Example response
    {
        "servers": [
            {
                "id": "616fb98f-46ca-475e-917e-2563e5a8cd19", 
                "links": [
                    {
                        "href": "http://openstack.example.com/v2/openstack/servers/616fb98f-46ca-475e-917e-2563e5a8cd19", 
                        "rel": "self"
                    }, 
                    {
                        "href": "http://openstack.example.com/openstack/servers/616fb98f-46ca-475e-917e-2563e5a8cd19", 
                        "rel": "bookmark"
                    }
                ], 
                "name": "new-server-test"
            }
        ]
    }

Returned Values

See General Request Returned Values.