diff options
Diffstat (limited to 'api-guide')
| -rw-r--r-- | api-guide/source/server_concepts.rst | 128 |
1 files changed, 68 insertions, 60 deletions
diff --git a/api-guide/source/server_concepts.rst b/api-guide/source/server_concepts.rst index c81e22cfda..231c895d61 100644 --- a/api-guide/source/server_concepts.rst +++ b/api-guide/source/server_concepts.rst @@ -122,29 +122,25 @@ operations on the server. Server query ~~~~~~~~~~~~ -Nova allows both general user and administrator to filter the server -query result by using query options. - -For general user, ``reservation_id``, ``name``, ``status``, ``image``, -``flavor``, ``ip``, ``changes-since``, ``ip6 (microversion 2.5)`` are -supported options to be used. The other options will be ignored by nova -silently only with a debug log. - -For administrator, there are more fields can be used. The ``all_tenants`` -option allows the servers owned by all tenants to be reported (otherwise -only the servers associated with the calling tenant are included in -the response). Additionally, the filter is applied to the database schema -definition of ``class Instance``, e.g there is a field named 'locked' in -the schema then the filter can use 'locked' as search options to filter -servers. - -Also, there are some special options such as ``changes-since`` can -be used and interpreted by nova. - -- **General user & Administrator supported options** - General user supported options are listed above and administrator can - use almost all the options except the options parameters for sorting - and pagination. +There are two APIs for querying servers ``GET /servers`` and +``GET /servers/detail``. Both of those APIs support filtering the query result +by using query options. + +For different user roles, the user has different query options set: + +- For general user, there is limited set of attributes of the servers can be + used as query option. ``reservation_id``, ``name``, ``status``, ``image``, + ``flavor``, ``ip``, ``changes-since``, ``ip6``, ``tags``, ``tags-any``, + ``not-tags``, ``not-tags-any`` are supported options to be used. Other + options will be ignored by nova silently. + +- For administrator, most of the server attributes can be used as query + options. Before the Ocata release, the fields in the database schema of + server are exposed as query options, which may lead to unexpected API + change. After the Ocata release, the definition of the query options and + the database schema are decoupled. That is also the reason why the naming of + the query options are different from the attribute naming in the servers API + response. .. code:: @@ -166,8 +162,6 @@ be used and interpreted by nova. **Example: General user query server with administrator only options** -.. code:: - Request with non-administrator context: GET /servers/detail?locked=1 Note that 'locked' is not returned through API layer @@ -188,8 +182,6 @@ be used and interpreted by nova. **Example: Administrator query server with administrator only options** -.. code:: - Request with administrator context: GET /servers/detail?locked=1 @@ -203,18 +195,60 @@ be used and interpreted by nova. ] } -- **Exact matching and regex matching of the search options** +There are also some speical query options: - Depending on the name of a filter, matching for that filter is performed - using either exact matching or as regular expression matching. - ``project_id``, ``user_id``, ``image_ref``, ``vm_state``, - ``instance_type_id``, ``uuid``, ``metadata``, ``host``, ``system_metadata`` - are the options that are applied by exact matching when filtering. +- ``changes-since`` returns the servers updated after the given time. + Please see: :doc:`polling_changes-since_parameter` - **Example: User query server using exact matching on host** +- ``deleted`` returns (or excludes) deleted servers + +- ``soft_deleted`` modifies behavior of ‘deleted’ to either include or exclude + instances whose vm_state is SOFT_DELETED + +- ``all_tenants`` is an administrator query option, which allows the + administrator to query the servers in any tenant. .. code:: + **Example: User query server with special keys changes-since** + + Precondition: + GET /servers/detail + + Response: + { + "servers": [ + { + "name": "t1" + "updated": "2015-12-15T15:55:52Z" + ... + }, + { + "name": "t2", + "updated": "2015-12-17T15:55:52Z" + ... + } + ] + } + + GET /servers/detail?changes-since='2015-12-16T15:55:52Z' + + Response: + { + { + "name": "t2", + "updated": "2015-12-17T15:55:52Z" + ... + } + } + +There are two kinds of matching in query options: Exact matching and +regex matching. + +.. code:: + + **Example: User query server using exact matching on host** + Precondition: Request with administrator context: GET /servers/detail @@ -253,8 +287,6 @@ be used and interpreted by nova. **Example: Query server using regex matching on name** -.. code:: - Precondition: Request with administrator context: GET /servers/detail @@ -307,8 +339,6 @@ be used and interpreted by nova. **Example: User query server using exact matching on host and regex matching on name** -.. code:: - Precondition: Request with administrator context: GET /servers/detail @@ -350,28 +380,6 @@ be used and interpreted by nova. ] } -- **Special keys are used to tweak the query** - ``changes-since`` returns instances updated after the given time, - ``deleted`` return (or exclude) deleted instances and ``soft_deleted`` - modify behavior of 'deleted' to either include or exclude instances whose - vm_state is SOFT_DELETED. Please see: :doc:`polling_changes-since_parameter` - - **Example: User query server with special keys changes-since** - -.. code:: - - Precondition: - GET /servers/detail - - Response: - { - "servers": [ - { - "name": "t1" - "updated": "2015-12-15T15:55:52Z" - ... - }, - { "name": "t2", "updated": "2015-12-17T15:55:52Z" ... |