Resource retrieving: add changes-before filter
This adds the changes-before filter to the servers, os-instance-actions and os-migrations APIs for filtering resources which were last updated before or equal to the given time. The changes-before filter, like the changes-since filter, will return deleted server resources. Part of bp support-to-query-nova-resources-filter-by-changes-before Change-Id: If91c179e3823c8b0da744a9363906b0f7b05c326
This commit is contained in:
zhangbailin
committed by
Matt Riedemann
Matt Riedemann
parent
82270cc261
commit
28c1075b59
@@ -1,32 +1,81 @@
|
||||
==================================================
|
||||
Efficient polling with the changes-since parameter
|
||||
==================================================
|
||||
=================
|
||||
Efficient polling
|
||||
=================
|
||||
|
||||
The REST API allows you to poll for the status of certain operations by
|
||||
performing a **GET** on various elements. Rather than re-downloading and
|
||||
re-parsing the full status at each polling interval, your REST client
|
||||
may use the ``changes-since`` parameter to check for changes since a
|
||||
previous request.
|
||||
re-parsing the full status at each polling interval, your REST client may
|
||||
use the ``changes-since`` and/or ``changes-before`` parameters to check
|
||||
for changes within a specified time.
|
||||
|
||||
The ``changes-since`` time is specified as an `ISO
|
||||
8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ dateTime
|
||||
The ``changes-since`` time or ``changes-before`` time is specified as
|
||||
an `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ dateTime
|
||||
(2011-01-24T17:08Z). The form for the timestamp is **CCYY-MM-DDThh:mm:ss**.
|
||||
An optional time zone may be written in by appending the form ±hh:mm
|
||||
which describes the timezone as an offset from UTC. When the timezone is
|
||||
not specified (2011-01-24T17:08), the UTC timezone is assumed.
|
||||
|
||||
If nothing has changed since the ``changes-since`` time, an empty list is
|
||||
returned. If data has changed, only the items changed since the
|
||||
specified time are returned in the response. For example, performing a
|
||||
**GET** against::
|
||||
The following situations need to be considered:
|
||||
|
||||
https://api.servers.openstack.org/v2.1/servers?changes-since=2015-01-24T17:08Z
|
||||
* If nothing has changed since the ``changes-since`` time, an empty list is
|
||||
returned. If data has changed, only the items changed since the specified
|
||||
time are returned in the response. For example, performing a
|
||||
**GET** against::
|
||||
|
||||
would list all servers that have changed since Mon, 24 Jan 2015 17:08:00 UTC.
|
||||
https://api.servers.openstack.org/v2.1/servers?changes-since=2015-01-24T17:08Z
|
||||
|
||||
would list all servers that have changed since Mon, 24 Jan 2015 17:08:00
|
||||
UTC.
|
||||
|
||||
* If nothing has changed earlier than or equal to the ``changes-before``
|
||||
time, an empty list is returned. If data has changed, only the items
|
||||
changed earlier than or equal to the specified time are returned in the
|
||||
response. For example, performing a **GET** against::
|
||||
|
||||
https://api.servers.openstack.org/v2.1/servers?changes-before=2015-01-24T17:08Z
|
||||
|
||||
would list all servers that have changed earlier than or equal to
|
||||
Mon, 24 Jan 2015 17:08:00 UTC.
|
||||
|
||||
* If nothing has changed later than or equal to ``changes-since``, or
|
||||
earlier than or equal to ``changes-before``, an empty list is returned.
|
||||
If data has changed, only the items changed between ``changes-since``
|
||||
time and ``changes-before`` time are returned in the response.
|
||||
For example, performing a **GET** against::
|
||||
|
||||
https://api.servers.openstack.org/v2.1/servers?changes-since=2015-01-24T17:08Z&changes-before=2015-01-25T17:08Z
|
||||
|
||||
would list all servers that have changed later than or equal to Mon,
|
||||
24 Jan 2015 17:08:00 UTC, and earlier than or equal to Mon, 25 Jan 2015
|
||||
17:08:00 UTC.
|
||||
|
||||
Microversion change history for servers, instance actions and migrations
|
||||
regarding ``changes-since`` and ``changes-before``:
|
||||
|
||||
* The `2.21 microversion`_ allows reading instance actions for a deleted
|
||||
server resource.
|
||||
* The `2.58 microversion`_ allows filtering on ``changes-since`` when listing
|
||||
instance actions for a server.
|
||||
* The `2.59 microversion`_ allows filtering on ``changes-since`` when listing
|
||||
migration records.
|
||||
* The `2.66 microversion`_ adds the ``changes-before`` filter when listing
|
||||
servers, instance actions and migrations.
|
||||
|
||||
The ``changes-since`` filter nor the ``changes-before`` filter
|
||||
change any read-deleted behavior in the os-instance-actions or
|
||||
os-migrations APIs. The os-instance-actions API with the 2.21 microversion
|
||||
allows retrieving instance actions for a deleted server resource.
|
||||
The os-migrations API takes an optional ``instance_uuid`` filter parameter
|
||||
but does not support returning deleted migration records.
|
||||
|
||||
To allow clients to keep track of changes, the ``changes-since`` filter
|
||||
displays items that have been *recently* deleted. Both images and
|
||||
servers contain a ``DELETED`` status that indicates that the resource
|
||||
has been removed. Implementations are not required to keep track of
|
||||
deleted resources indefinitely, so sending a ``changes-since`` time in the
|
||||
distant past may miss deletions.
|
||||
and ``changes-before`` filter displays items that have been *recently*
|
||||
deleted. Servers contain a ``DELETED`` status that indicates that the
|
||||
resource has been removed. Implementations are not required to keep track
|
||||
of deleted resources indefinitely, so sending a ``changes-since`` time or
|
||||
a ``changes-before`` time in the distant past may miss deletions.
|
||||
|
||||
.. _2.21 microversion: https://docs.openstack.org/nova/latest/reference/api-microversion-history.html#id19
|
||||
.. _2.58 microversion: https://docs.openstack.org/nova/latest/reference/api-microversion-history.html#id53
|
||||
.. _2.59 microversion: https://docs.openstack.org/nova/latest/reference/api-microversion-history.html#id54
|
||||
.. _2.66 microversion: https://docs.openstack.org/nova/latest/reference/api-microversion-history.html#id59
|
||||
|
||||
@@ -132,9 +132,9 @@ 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.
|
||||
``flavor``, ``ip``, ``changes-since``, ``changes-before``, ``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
|
||||
@@ -197,11 +197,14 @@ For different user roles, the user has different query options set:
|
||||
]
|
||||
}
|
||||
|
||||
There are also some speical query options:
|
||||
There are also some special query options:
|
||||
|
||||
- ``changes-since`` returns the servers updated after the given time.
|
||||
Please see: :doc:`polling_changes-since_parameter`
|
||||
|
||||
- ``changes-before`` returns the servers updated before the given time.
|
||||
Please see: :doc:`polling_changes-since_parameter`
|
||||
|
||||
- ``deleted`` returns (or excludes) deleted servers
|
||||
|
||||
- ``soft_deleted`` modifies behavior of 'deleted' to either include or exclude
|
||||
@@ -212,7 +215,7 @@ There are also some speical query options:
|
||||
|
||||
.. code::
|
||||
|
||||
**Example: User query server with special keys changes-since**
|
||||
**Example: User query server with special keys changes-since or changes-before**
|
||||
|
||||
Precondition:
|
||||
GET /servers/detail
|
||||
@@ -221,13 +224,13 @@ There are also some speical query options:
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"name": "t1"
|
||||
"updated": "2015-12-15T15:55:52Z"
|
||||
"name": "t1",
|
||||
"updated": "2015-12-15T15:55:52Z",
|
||||
...
|
||||
},
|
||||
{
|
||||
"name": "t2",
|
||||
"updated": "2015-12-17T15:55:52Z"
|
||||
"updated": "2015-12-17T15:55:52Z",
|
||||
...
|
||||
}
|
||||
]
|
||||
@@ -239,11 +242,40 @@ There are also some speical query options:
|
||||
{
|
||||
{
|
||||
"name": "t2",
|
||||
"updated": "2015-12-17T15:55:52Z"
|
||||
"updated": "2015-12-17T15:55:52Z",
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
GET /servers/detail?changes-before='2015-12-16T15:55:52Z'
|
||||
|
||||
Response:
|
||||
{
|
||||
{
|
||||
"name": "t1",
|
||||
"updated": "2015-12-15T15:55:52Z",
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
GET /servers/detail?changes-since='2015-12-10T15:55:52Z'&changes-before='2015-12-28T15:55:52Z'
|
||||
|
||||
Response:
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"name": "t1",
|
||||
"updated": "2015-12-15T15:55:52Z",
|
||||
...
|
||||
},
|
||||
{
|
||||
"name": "t2",
|
||||
"updated": "2015-12-17T15:55:52Z",
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
There are two kinds of matching in query options: Exact matching and
|
||||
regex matching.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user