• Bare Metal Server

bms
  1. Help Center
  2. Bare Metal Server
  3. API Reference
  4. API
  5. BMS Lifecycle Management (Native OpenStack APIs)
  6. Querying BMSs (Native OpenStack API)

Querying BMSs (Native OpenStack API)

Function

This interface is used query BMSs using search criteria and to display the BMSs in a list. The interface version is v2.1. Querying with the micro version number is supported. Add a group of key-value pairs to the request header. The key is fixed at X-OpenStack-Nova-API-Version, and the value is the microversion number, for example 2.26 indicating that the microversion number is 2.26.

Constraints

  • The query result returned by this interface includes both ECSs and BMSs. You need to filter out the BMSs using the flavor used to create the BMSs or the tags added to the BMSs during BMS creation.
  • If the image is used as the search criteria, other search criteria and pagination criteria are not supported. If both the image and other search criteria are used, the BMSs are filtered out by image. If the image is not used as the search criteria, this interface has no restrictions.

URI

GET /v2.1/{project_id}/servers

Table 1 lists the parameters.

Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

Table 2 lists the optional parameters that can be used to query BMSs.

Table 2 Optional parameters that can be used to query BMSs

Parameter

Type

Mandatory

Description

image

String

No

Specifies the image ID.

flavor

String

No

Specifies the flavor ID.

name

String

No

Specifies the BMS name. This parameter supports fuzzy matching.

For example, regular expression ?name=bob will return both bob and bobb. To obtain only bob, you can use a regular expression matching the basic database syntax, such as MySQL or PostgreSQL (official website: https://www.postgresql.org/docs/9.2/static/functions-matching.html).

status

String

No

Specifies the BMS status. Only the administrators can use the deleted state to filter out deleted BMSs.

changes-since

String

No

Filters out the BMSs that have been updated since the changes-since time. The parameter is in ISO 8601 time format, for example, 2013-06-09T06:42:18Z.

all_tenants

Int

No

Specifies whether to query the BMSs of all tenants. This parameter is available only to administrators. The value can be 0 (do not query the BMSs of all tenants) or 1 (query the BMSs of all tenants).

ip

String

No

Specifies the IP address. This parameter supports fuzzy matching.

deleted

boolean

No

Filters out all deleted BMSs. This parameter is available only to administrators.

tags

String

No

Specifies the tag list. Returns BMSs that match all tags. Use commas (,) to separate multiple tags.

Added in micro version 2.26.

tags-any

String

No

Specifies the tag list. Returns BMSs that match any tag. Use commas (,) to separate multiple tags.

Added in micro version 2.26.

not-tags

String

No

Specifies the tag list. Returns BMSs that do not match all tags. Use commas (,) to separate multiple tags.

Added in micro version 2.26.

not-tags-any

String

No

Specifies the tag list. Returns BMSs that do not match any of the tags. Use commas (,) to separate multiple tags.

Added in micro version 2.26.

sort_key

String

No

Specifies the BMS sorting attribute, which can be the BMS UUID (uuid), BMS status (vm_state), BMS name (display_name), BMS task status (task_state), power status (power_state), creation time (created_at), last time when the BMS is updated (updated_at), and availability zone (availability_zone). You can specify multiple sort_key and sort_dir pairs.

sort_dir

String

No

Specifies the sorting direction.

  • asc: The query results are displayed in ascending order.
  • desc (default value): The query results are displayed in descending order.

Request Message

N/A

Response Message

  • Response parameters

    Parameter

    Type

    Description

    servers

    List data structure [2]

    Specifies the BMS list.

    [2] servers field data structure description

    Parameter

    Type

    Description

    name

    String

    Specifies the BMS name.

    id

    String

    Specifies the unique ID of the BMS.

    links

    List data structure [3]

    Specifies the shortcut links of the BMS.

    [3] links field data structure description

    Parameter

    Type

    Description

    rel

    String

    Specifies the shortcut link marker name.

    href

    String

    Specifies the corresponding shortcut link.

  • Example response
    {
        "servers": [
            {
                "name": "bms",
                "links": [
                    {
                        "rel": "self",
                        "href": "https://openstack.example.com/v2.1/c685484a8cc2416b97260938705deb65/servers/820abbd0-2d8b-4bc5-ae46-69cacfd4fbaa"
                    },
                    {
                        "rel": "bookmark",
                        "href": "https://openstack.example.com/c685484a8cc2416b97260938705deb65/servers/820abbd0-2d8e-4bc5-ae46-69cacfd4fbaa"
                    }
                ],
                "id": "820abbd0-2d8e-4bc5-ae46-69cacfd4fbaa"
            }
        ]
    }

Returned Values

See section Common Returned Values.