在共享列表 API 中显示资源总数信息¶

https://blueprints.launchpad.net/manila/+spec/add-amount-info-in-list-api

此蓝图建议在 Manila 的 /shares 和 /shares/detail API 中添加总数信息。

问题描述¶

通常需要在 Web 门户的摘要部分显示用户或租户拥有的资源数量，但我们现在无法获取此信息。为了向最终用户显示这种总数，许多云需要收集所有资源。

用例¶

管理员或用户需要在返回分页列表时，无需检索和累加所有资源就能知道他们拥有的资源总数。

提议的变更¶

根据 openstack API-WG [1] 的建议，它提供了在项目公共 REST API 中返回资源集合总大小的指导。

因此，此蓝图建议在我们的 /shares 和 /shares/detail API 中添加新的属性 count，以便在 /shares 和 /shares/detail API 响应中包含总数信息。如果我们默认将 count 属性添加到我们的响应体中，如果资源数量很多，可能会对性能产生影响。考虑到并非每个请求都需要此信息，因此需要额外的查询参数来启用资源列表时的计数功能。

备选方案¶

针对此需求，有几种替代解决方案，我们在此列出并比较它们。

在响应头中添加数量信息
```
X-resource-count: 200
```

缺点是它会给 API 客户带来一些负担，我们没有在响应头中添加有用内容的先例。此外，它使文档编写更加困难。

为每个资源添加显式 API

POST: /v2/{tenant_id}/{resources}/action {os-count}

此更改涉及大量的修改并创建多个新的 API。为如此简单的 API 更改添加如此多的 API 是过度设计。

为不同的资源创建一个新的 API

POST: /V3/{tenant_id}/action {os-count}
BODY:
    {
        "resource": "share",
        "user": "user_1",
        "other_filter": "other_value"
    }

对于此更改，如果最终用户想要知道列出资源时的资源总数，则需要进行额外的 API 请求。

数据模型影响¶

无

REST API 影响¶

此更改需要 Microversion 升级。

在共享列表 API 的查询字符串中添加“with_count”参数，用于指示是否应该从 GET REST API 请求返回资源的计数。任何等于 True 的值都表示应返回计数。相反，任何等于 False 的值都表示不应返回计数。

列出共享

URL: /v2/{tenant_id}/shares?with_count=true
方法：POST

JSON body

{
    'shares': [{
        'name': 'test',
        ...
    }]
    'count': <int_count>,
}

列出带有详细信息的共享

URL: /v2/{tenant_id}/shares/detail?with_count=true
方法：POST

JSON body

{
    'shares': [{
        'name': 'test',
        ...
    }]
    'count': <int_count>,
}

客户端影响¶

共享列表命令将升级以支持此功能。

安全影响¶

无

通知影响¶

无

其他最终用户影响¶

无

性能影响¶

由于如果使用 with_count 选项请求列表 API，我们将添加额外的 COUNT() 语句，因此这些 API 的性能会受到影响，尤其是在数据库中数据很多时。

其他部署者影响¶

无

开发人员影响¶

无

实现¶

负责人¶

主要负责人: zhongjun(jun.zhongjun2@gmail.com)

工作项¶

在共享列表 API 中添加 with_count 选项支持。
添加相关的单元测试用例。
更新 manila-client。
更新 manila-ui。

依赖项¶

无

测试¶

添加单元测试和 tempest 测试以覆盖此更改。

文档影响¶

更新 API 文档。

参考资料¶

[1]: https://specs.openstack.org/openstack/api-wg/guidelines/counting.html

在共享列表 API 中显示资源的总体计数信息

manila-specs 0.0.1.dev209

页面内容