添加一个 v2 API 端点来检索 DataFrame 对象

https://storyboard.openstack.org/#!/story/2005890

CloudKitty 需要在其 v2 API 中添加一个端点来检索 DataFrame 对象。本规范旨在定义需要做什么以及原因。本文档中的所有内容均可讨论，同样适用于相关的 storyboard 和 gerrit。

问题描述

现在已经存在一个可用的端点，绑定在 POST /v2/dataframes 上，允许我们将 DataFrame 对象推送到 CloudKitty 存储后端。我们还需要一个 v2 API 端点来从后端检索这些对象。

此功能也在 v1 API 上可用，地址为 GET /v1/storage/dataframes。因此，有必要将其包含在 v2 API 中。

提议的变更

提议的端点将支持分页，一个字典形式的过滤器，以及一个 begin 和一个 end 参数，作为 ISO 8601 字符串，支持时区偏移，例如 2019-08-29T07:18:40+00:00。

它将在 GET /v2/dataframes 上可用。

示例

  • 获取 image.size 指标类型，针对项目 X 和用户 Y 的特定周期的所有 dataframe

    这将导致以下 HTTP 请求

    GET /v2/dataframes?filter=type:image.size&filter=project_id:X&filter=user_id:Y&begin=2019-05-01T00:00:00&end=2019-05-07T00:00:00

此功能也将提供给 CloudKitty 客户端库和 CLI。

备选方案

无。

数据模型影响

无。

REST API 影响

这将在 /v2/dataframes 上添加一个端点，并支持 GET HTTP 方法。

该端点将支持以下查询参数

  • offset：(可选，默认为 0) 应返回的第一个元素的偏移量。

  • limit：(可选，默认为 100) 要返回的最大结果数。

  • filter：(可选) 应用的元数据过滤器字典。

  • begin：(可选，默认为当月第一天午夜) 请求应应用的周期的开始时间。

  • end：(可选，默认为下个月第一天午夜) 请求应应用的周期的结束时间。

对该端点发起的 GET 请求将返回以下格式的 JSON 对象

{
    "total": 2,
    "dataframes": [
        {
            "usage": {
                "volume.size": [
                    {
                        "vol": {
                            "unit": "GiB",
                            "qty": 1.9
                        },
                        "rating": {
                            "price": 3.8
                        },
                        "groupby": {
                            "project_id": "8ace6f139a1742548e09f1e446bc9737",
                            "user_id": "b28fd3f448c34c17bf70e32886900eed",
                            "id": "be966c6d-78a0-42cf-bab9-e833ed996dee"
                        },
                        "metadata": {
                            "volume_type": ""
                        }
                    }
                ]
            },
            "period": {
                "begin": "2019-08-01T01:00:00+00:00",
                "end": "2019-08-01T02:00:00+00:00"
            }
        },
        {
            "usage": {
                "image.size": [
                    {
                        "vol": {
                            "unit": "MiB",
                            "qty": 3.55339050293
                        },
                        "rating": {
                            "price": 1.77669525146
                        },
                        "groupby": {
                            "project_id": "5994682e63af4aa8873d247aa28b876e",
                            "user_id": "b28fd3f448c34c17bf70e32886900eed",
                            "id": "f7541950-96d5-4e89-ac76-9d4eacf59b83"
                        },
                        "metadata": {
                            "container_format": "foo",
                            "disk_format": "bar"
                        }
                    }
                ]
            },
            "period": {
                "begin": "2019-08-01T02:00:00+00:00",
                "end": "2019-08-01T03:00:00+00:00"
            }
        }
    ]
}

对该端点发起的 GET 请求的预期 HTTP 成功响应代码是 200 OK。

对该端点发起的 GET 请求的预期 HTTP 错误响应代码是

  • 400 错误请求：请求格式错误。

  • 403 Forbidden：用户没有检索 dataframe 的必要权限。

  • 404 Not Found：未找到与提供的参数匹配的 dataframe。

该端点将针对管理员以及请求的 dataframe 的租户/项目所有者进行授权（关于指定的 project_id 过滤器）。

安全影响

任何访问此端点用户都将能够检索 CloudKitty 评级的数据信息。因此，应谨慎地将访问此端点的权限授予非管理员用户。

通知影响

无。

其他最终用户影响

客户端也将更新，以便包含一个函数和一个 CLI 命令，允许检索 DataFrame 对象。

性能影响

无。

其他部署者影响

对于管理员和部署者来说，检索 Dataframe 将会更容易。

开发人员影响

无。

实现

负责人

主要负责人

<jferrieu>

工作项

  • 使用单元测试实现 API 端点

  • 添加 tempest 测试

  • 使用单元测试和功能测试支持客户端中的此端点。

依赖项

无。

测试

将添加该端点的 tempest 测试。

文档影响

该端点将被添加到 API 参考中。

参考资料