增强列表操作的分页键

https://blueprints.launchpad.net/cinder/+spec/extend-limit-implementations

目前，分页键（如 limit、marker、排序键和排序方向）以及 next 链接生成，已经针对卷列表操作实现，但其他列表操作中不可用。此蓝图为快照、卷迁移、一致性组、一致性组快照和备份等其他条目实现分页键和 next 链接生成。

问题描述

上述部分中提到的分页键已经在卷的列表操作中实现。此功能可以扩展到其他 cinder 概念。之所以选择快照、卷迁移、一致性组、一致性组快照和备份作为目标，是因为这些实体查询频率相对较高，并且与类型、可用区等其他实体相比，更有可能达到大量数据。

next 链接生成已经在卷列表中可用，因此将其实现于其他 cinder 概念中非常简单。请参考 cinder.api.common.ViewBuilder 类中的 _get_collection_links 函数。

用例

假设最大页面大小为 1000，并且存在超过 1000 个卷快照。如果未为快照实现分页键 marker，则用户可以通过 API 查询的最大快照数量为 1000。查询超过 1000 个快照的唯一方法是增加默认的最大页面大小，这限制了 cinder 列表操作。如果未生成 next 链接，则无法检索超过最大页面大小的项目。即使在这种情况下生成了 next 链接，它仍然会返回与先前请求相同的结果，而没有考虑 key marker。总之，对于 cinder 实体，分页键和 next 链接生成都是必要的。

提议的变更

该更改依赖于一些工作项，这些工作项已放在“Dependencies”（依赖项）部分中。

快照、卷迁移、一致性组、一致性组快照和备份的列表 API 将支持以下参数

• limit：用于确定响应中返回的项目数量的键

• marker：用于确定查询开始的项目键

• sort：这是一个逗号分隔的排序键列表。排序方向可以可选地附加到每个排序键，并用“:”字符分隔

多个排序键和排序方向将像卷在补丁“GET volumes API sorting REST/volume/DB updates”（GET 卷 API 排序 REST/volume/DB 更新）中所做的那样实现，https://review.openstack.org/#/c/141915/。

该更改符合补丁“CLI Sorting Argument Guidelines”（CLI 排序参数指南）中定义的客户端排序参数语法，https://review.openstack.org/#/c/145544/。

调用者可以在请求中指定这些参数来查询项目的列表，例如 /snapshots?limit=5&marker=snapshot_id&sort=key1:asc,key2:desc,key3:asc

如果有更多项目可用于在后续请求中查询，则应为快照、卷迁移、一致性组、一致性组快照和备份正确生成 next 链接。

备选方案

我们有可能定义不同的分页键，而不是 limit、marker、排序信息来实现 Cinder 中的其他项目的分页。

但是，为了保持代码更改的一致性，最好遵循卷列表所采用的模式。

另一种选择是 cinder 坚持不为除卷之外的其他实体提供分页。但是，默认的最大页面大小 1000 可能会被某些实体（如快照）在生产环境中超过。这将导致其他实体将来出现问题。

数据模型影响

无

REST API 影响

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

• /v2/{tenant_id}/{items}

• /v2/{tenant_id}/{items}/detail

{items} 将被替换为以下适当的实体

• 对于快照

  • /v2/{tenant_id}/snapshots

  • /v2/{tenant_id}/snapshots/detail

• 对于卷迁移

  • /v2/{tenant_id}/os-volume-transfer

  • /v2/{tenant_id}/os-volume-transfer/detail

• 对于一致性组

  • /v2/{tenant_id}/consistencygroups

  • /v2/{tenant_id}/consistencygroups/detail

• 对于一致性组快照

  • /v2/{tenant_id}/cgsnapshots

  • /v2/{tenant_id}/cgsnapshots/detail

• 对于备份

  • /v2/{tenant_id}/backups

  • /v2/{tenant_id}/backups/detail

现有的 API 需要支持上述 cinder 概念的以下新请求参数

参数	风格	类型	描述
limit	query	integer	用于确定响应中返回的项目数量的键
marker	query	string	用于确定查询开始的项目键
sort	query	list	一个逗号分隔的排序键列表，排序方向可以可选地附加到每个排序键

如果指定了无效的分页键，则将返回“badRequest”错误响应（代码 400）。

• 对于 limit 键，它返回消息，如“Invalid input received: Invalid limit key”（接收到无效输入：无效的 limit 键）。

• 对于 marker 键，它返回消息，如“Invalid input received: Invalid marker key”（接收到无效输入：无效的 marker 键）。

• 对于排序信息，它返回消息，如“Invalid input received: Invalid sort key”（接收到无效输入：无效的排序键）或“Invalid input received: Invalid sort direction”（接收到无效输入：无效的排序方向），具体取决于不同的情况。

如果需要，next 链接将放在从 cinder 返回的响应中。

• 对于快照，它回复

  {
      "snapshots": [<List of snapshots>],
      "snapshots_links": [{'href': '<next_link>', 'rel': 'next'}]
  }
  

• 对于卷迁移，它回复

  {
      "transfers": [<List of transfers>],
      "transfers_links": [{'href': '<next_link>', 'rel': 'next'}]
  }
  

• 对于一致性组，它回复

  {
      "consistencygroups": [<List of consistencygroups>],
      "consistencygroups_links": [{'href': '<next_link>', 'rel': 'next'}]
  }
  

• 对于一致性组快照，它回复

  {
      "cgsnapshots": [<List of cgsnapshots>],
      "cgsnapshots_links": [{'href': '<next_link>', 'rel': 'next'}]
  }
  

• 对于备份，它回复

  {
    "backups": [<List of backups>],
    "backups_links": [{'href': '<next_link>', 'rel': 'next'}]
  }
  

安全影响

无

通知影响

无

其他最终用户影响

应更新 cinderclient 以接受 limit、marker、排序信息，用于快照、卷迁移、一致性组、一致性组快照和备份。

用户将能够指定分页键，如 limit、marker、排序信息来列出快照、卷迁移、一致性组、一致性组快照和备份。

性能影响

无

其他部署者影响

部署者应注意，标志 osapi_max_limit 可以设置集合资源在单个响应中返回的最大项目数量，但它将不再限制 cinderclient 请求返回的项目数量。

在为 cinder 实体实现分页键和 next 链接生成后，cinderclient 请求可以检索的项目数量超过标志 osapi_max_limit 设置的数量，因为它可以通过带有 marker 键的 next 链接多次获取项目，直到返回所有项目（如果没有设置 limit 键）或项目数量等于 limit（如果设置了 limit 键）。

开发人员影响

无

实现

负责人

主要负责人

Vincent Hou (sbhou@cn.ibm.com)

其他贡献者

无

工作项

由于 next 链接生成的逻辑代码在一个公共类中完成。我们不再需要重复这项工作。

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

• 添加代码以调用公共函数来处理快照、卷迁移、一致性组、一致性组快照和备份的 limit、marker 和 sort 参数。

• 添加代码以使用分页键对快照、卷迁移、一致性组、一致性组快照和备份执行数据库查询。

• 在 cinderclient 中添加对快照、卷迁移、一致性组、一致性组快照和备份的分页键的支持。

• 修改现有的 API 以支持将 limit、marker 和 sort 信息从 API 层传递到数据库层。

• 单元测试以确保快照、卷迁移、一致性组、一致性组快照和备份支持分页键 limit、marker 和 sort 信息，并在必要时提供 next 链接生成。

依赖项

• Cinder pagination：https://blueprints.launchpad.net/cinder/+spec/cinder-pagination，已接受

• GET volumes API sorting REST/volume/DB updates：https://review.openstack.org/#/c/141915/，进行中

• CLI Sorting Argument Guidelines：https://review.openstack.org/#/c/145544/，已接受

• Server sorting guidelines：https://review.openstack.org/#/c/145579，已合并

测试

需要创建单元测试和 Tempest 测试，以确保快照、卷迁移、一致性组、一致性组快照和备份支持分页键 limit、marker 和 sort 信息，并在必要时提供 next 链接生成。

文档影响

需要更新 API 文档，以接受 limit、marker、排序键和排序方向，用于快照、卷迁移、一致性组、一致性组快照和备份，就像卷一样。

参考资料

无