Glance 排序增强¶

https://blueprints.launchpad.net/glance/+spec/glance-sorting-enhancements

目前，Glance 的排序支持允许调用者指定多个排序键和一个排序方向。此蓝图增强了 /images 和 /images/detail API 的排序支持，以便可以在请求中提供多个排序键和排序方向。

问题描述¶

目前不支持基于多个排序方向检索镜像数据；支持多个排序键和一个方向，并且默认按 “created_at” 键降序排序。

为了以任何排序顺序和方向检索数据，REST API 需要接受多个排序键和方向。

用例：一个 UI 显示一个表格，该表格仅显示从服务器检索到的数据页面。此表格中的项目需要首先按状态排序，然后按显示名称排序。为了以这种顺序检索数据，API 必须接受多个排序键/方向。

提议的变更¶

/images 和 /images/detail API 将符合 API 工作组的指南 [1]，用于排序并支持请求中的以下参数

sort: 逗号分隔的排序键列表，每个键可以选择性地附加 <:dir>，其中 ‘dir’ 是相应排序键的方向（支持的值为 ‘asc’ 表示升序，‘desc’ 表示降序）。

例如

/images?sort=status:asc,name:asc,created_at:desc

注意：“created_at” 和 “id” 排序键始终附加在键列表的末尾，如果它们尚未在请求中指定。

数据库层已经支持多个排序键和方向。此蓝图将更新 API 层以从 API 请求中检索排序信息，并将该信息传递到数据库层。

所有排序都在 glance.db.sqlalchemy.api._paginate_query 函数中处理。此函数接受一个 ORM 模型类作为参数，并且唯一的有效排序键是给定模型类上的属性。因此，有效的排序键是：‘name’、‘status’、‘container_format’、‘disk_format’、‘size’、‘id’、‘created_at’、‘updated_at’。

备选方案¶

可以使用重复的 ‘sort_key’ 和 ‘sort_dir’ 查询参数传递多个排序键和方向。例如

/images?sort_key=status&sort_dir=asc&sort_key=name&sort_dir=asc&
sort_key=created_at&sort_dir=desc

为了为用户提供使用经典熟悉语法的能力，并确保顺利过渡到新的语法，也应实现经典语法。

数据模型影响¶

无

REST API 影响¶

以下现有的 v2 GET API 将支持新的排序参数

/v2/images
/v2/images/detail

请注意，此蓝图描述的设计可以应用于其他 GET REST API，但此蓝图的范围仅限于上述列出的那些。一旦此设计最终确定，就可以将相同的方法应用于其他 API。

现有的 API 文档需要更新，以包含以下新的请求参数

参数	风格	类型	描述
sort	query	string	逗号分隔的排序键列表和可选的排序方向，形式为 key<:dir>，其中 ‘dir’ 要么是 ‘asc’ 表示升序，要么是 ‘desc’ 表示降序。默认值为 ‘created_at’ 和 ‘id’ 键降序。

目前，images 查询支持 ‘sort_key’ 和 ‘sort_dir’ 参数；这些将被弃用。如果同时指定了新的 ‘sort’ 参数和弃用的 ‘sort_key’ 或 ‘sort_dir’ 参数，API 将引发 “BadRequest” 错误响应（代码 400）。

API 响应格式或返回代码不会被修改，只会修改返回的镜像的顺序。

如果指定了无效的排序键或排序方向，将返回 “BadRequest” 错误响应（代码 400），并附带类似于“无效输入：无效的排序键”或“无效输入：无效的排序方向”的消息。

安全影响¶

无

通知影响¶

无

其他最终用户影响¶

python-glanceclient 应更新为接受排序键和排序方向，使用跨项目规范 [2] 中提出的 ‘sort’ 参数。

性能影响¶

无

其他部署者影响¶

排序键的选择不会影响数据检索性能。因此，应允许用户以他们需要的方式检索数据，以便创建他们的视图（请参阅问题描述中的用例）。

开发人员影响¶

无

实现¶

负责人¶

主要负责人: mfedosin
其他贡献者: 无

评审人员¶

ativelkov

icordasc

nikhil-komawar

工作项¶

理想情况下，处理排序参数的逻辑应在所有组件中通用，并在 oslo 中完成；nova 中也正在提出一个类似的蓝图：https://blueprints.launchpad.net/nova/+spec/nova-pagination

因此，我看到以下工作项目

更新现有的 API 以检索排序信息并传递到 DB 层 (https://review.openstack.org/#/c/148326/);
使用新的语法扩展 API 以支持多个排序键和方向 (https://review.openstack.org/#/c/148512/);
更新 python-glanceclient 以接受和处理使用经典和新排序语法中的多个排序键和方向 (https://review.openstack.org/#/c/120777/, https://review.openstack.org/#/c/148688/, https://review.openstack.org/#/c/148981/);
为新的更改实施完整的测试覆盖。

依赖项¶

CLI 排序参数指南跨项目规范 [2];
nova 中提出的相关（但独立）的更改 [3]。

测试¶

需要创建单元和 Tempest 测试来确保数据以指定的排序顺序检索。测试还应验证默认排序键（“created_at”和“id”）始终附加到用户提供的键（如果用户尚未指定它们）。

文档影响¶

/images 和 /images/detail API 文档需要更新为

反映新的排序参数并解释这些参数将影响数据返回的顺序。
解释默认排序键将始终添加到排序键列表的末尾。

Glance 排序增强