块存储 API V3 (当前)

注意

大多数 API 方法的 URL 都包含一个 {project_id} 占位符，代表调用者的项目 ID。 从 v3.67 开始，`project_id` 在 URL 中是可选的，以下两种方式等价：

  • GET /v3/{project_id}/volumes

  • GET /v3/volumes

在这两种情况下，API 方法实际使用的项目 ID 都是调用者 Keystone 上下文中的项目 ID。 因此，在 URL 中包含项目 ID 是多余的。

v3.67 微版本仅用作一个指示，表明 API 接受不带 `{project_id}` 段的 URL，这适用于所有请求，无论请求中的微版本是什么。 例如，提供 v3.67 或更高版本的 API 节点将接受不带 `{project_id}` 段的 URL，即使请求是针对 v3.0 的。 同样，它也会接受包含 `{project_id}` 段的 URL，即使请求是针对 v3.67 的。

API 版本

GET
/

列出所有 API 版本

列出块存储 API 所有版本的信息。

响应代码

成功

代码

原因
300 - 多重选择

资源对应于多个表示形式。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。
405 - 方法不允许

该方法对于此端点和资源无效。
404 - Not Found

找不到请求的资源。
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。
500 - 内部服务器错误

服务出现问题，导致无法满足请求。
503 - 服务不可用

服务现在无法处理请求。

请求

响应

示例：列出 API 版本：JSON 请求

{
    "versions": [
        {
            "id": "v3.0",
            "links": [
                {
                    "href": "https://docs.openstack.org/",
                    "rel": "describedby",
                    "type": "text/html"
                },
                {
                    "href": "http://127.0.0.1:45697/v3/",
                    "rel": "self"
                }
            ],
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=3"
                }
            ],
            "min_version": "3.0",
            "status": "CURRENT",
            "updated": "2022-08-31T00:00:00Z",
            "version": "3.71"
        }
    ]
}

API 版本详细信息

GET
/v3/

显示 API v3 详细信息

显示块存储 API v3 的详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
403 - 禁止

策略不允许当前用户执行此操作。

请求

响应参数

名称

入参

类型

描述

status

body

字符串

此 API 版本的状态。它可以是以下之一：

  • CURRENT：这是要使用的 API 的首选版本

  • DEPRECATED：这是 API 的已弃用版本，计划将其删除

updated

body

字符串

这是一个固定的字符串，API 版本会进行更新。

links

body

数组

指向相关资源的链接。

min_version

body

字符串

如果此版本的 API 支持微版本，则支持的最小微版本。如果不支持微版本，则为空字符串。

版本

body

字符串

如果此版本的 API 支持微版本，则支持的最高微版本。如果不支持微版本，则为空字符串。

media-types

body

数组

媒体类型。它是一个固定字典的数组。

注意

此字段是遗留字段，不提供任何有用信息。它将被弃用并移除。

id

body

字符串

版本的一个常用名称。仅供参考，不具有实际语义意义。

响应示例

{
    "versions": [
        {
            "id": "v3.0",
            "links": [
                {
                    "href": "https://docs.openstack.org/",
                    "rel": "describedby",
                    "type": "text/html"
                },
                {
                    "href": "http://127.0.0.1:44895/v3/",
                    "rel": "self"
                }
            ],
            "media-types": [
                {
                    "base": "application/json",
                    "type": "application/vnd.openstack.volume+json;version=3"
                }
            ],
            "min_version": "3.0",
            "status": "CURRENT",
            "updated": "2023-08-31T00:00:00Z",
            "version": "3.71"
        }
    ]
}

API 扩展 (extensions)

GET
/v3/{project_id}/extensions

列出已知的 API 扩展

列出块存储 API 扩展。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
300 - 多重选择

资源对应于多个表示形式。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

响应参数

名称

入参

类型

描述

updated

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

description

body

字符串

扩展描述。

links

body

数组

卷迁移的链接。

alias

body

字符串

扩展的别名。例如，“FOXNSOX”、“os-availability-zone”、“os-extended-quotas”、“os-share-unmanage”或“os-used-limits”。

name (可选)

body

字符串

对象名称。

响应示例

{
    "extensions": [
        {
            "alias": "os-hosts",
            "description": "Admin-only host administration.",
            "links": [],
            "name": "Hosts",
            "updated": "2011-06-29T00:00:00+00:00"
        },
        {
            "alias": "os-vol-tenant-attr",
            "description": "Expose the internal project_id as an attribute of a volume.",
            "links": [],
            "name": "VolumeTenantAttribute",
            "updated": "2011-11-03T00:00:00+00:00"
        },
        {
            "alias": "os-quota-sets",
            "description": "Quota management support.",
            "links": [],
            "name": "Quotas",
            "updated": "2011-08-08T00:00:00+00:00"
        },
        {
            "alias": "os-availability-zone",
            "description": "Describe Availability Zones.",
            "links": [],
            "name": "AvailabilityZones",
            "updated": "2013-06-27T00:00:00+00:00"
        },
        {
            "alias": "os-volume-encryption-metadata",
            "description": "Volume encryption metadata retrieval support.",
            "links": [],
            "name": "VolumeEncryptionMetadata",
            "updated": "2013-07-10T00:00:00+00:00"
        },
        {
            "alias": "backups",
            "description": "Backups support.",
            "links": [],
            "name": "Backups",
            "updated": "2012-12-12T00:00:00+00:00"
        },
        {
            "alias": "os-snapshot-actions",
            "description": "Enable snapshot manager actions.",
            "links": [],
            "name": "SnapshotActions",
            "updated": "2013-07-16T00:00:00+00:00"
        },
        {
            "alias": "os-volume-actions",
            "description": "Enable volume actions.",
            "links": [],
            "name": "VolumeActions",
            "updated": "2012-05-31T00:00:00+00:00"
        },
        {
            "alias": "os-snapshot-manage",
            "description": "Allows existing backend storage to be 'managed' by Cinder.",
            "links": [],
            "name": "SnapshotManage",
            "updated": "2014-12-31T00:00:00+00:00"
        },
        {
            "alias": "os-volume-unmanage",
            "description": "Enable volume unmanage operation.",
            "links": [],
            "name": "VolumeUnmanage",
            "updated": "2012-05-31T00:00:00+00:00"
        },
        {
            "alias": "consistencygroups",
            "description": "consistency groups support.",
            "links": [],
            "name": "Consistencygroups",
            "updated": "2014-08-18T00:00:00+00:00"
        },
        {
            "alias": "os-vol-host-attr",
            "description": "Expose host as an attribute of a volume.",
            "links": [],
            "name": "VolumeHostAttribute",
            "updated": "2011-11-03T00:00:00+00:00"
        },
        {
            "alias": "encryption",
            "description": "Encryption support for volume types.",
            "links": [],
            "name": "VolumeTypeEncryption",
            "updated": "2013-07-01T00:00:00+00:00"
        },
        {
            "alias": "os-vol-image-meta",
            "description": "Show image metadata associated with the volume.",
            "links": [],
            "name": "VolumeImageMetadata",
            "updated": "2012-12-07T00:00:00+00:00"
        },
        {
            "alias": "os-types-manage",
            "description": "Types manage support.",
            "links": [],
            "name": "TypesManage",
            "updated": "2011-08-24T00:00:00+00:00"
        },
        {
            "alias": "capabilities",
            "description": "Capabilities support.",
            "links": [],
            "name": "Capabilities",
            "updated": "2015-08-31T00:00:00+00:00"
        },
        {
            "alias": "cgsnapshots",
            "description": "cgsnapshots support.",
            "links": [],
            "name": "Cgsnapshots",
            "updated": "2014-08-18T00:00:00+00:00"
        },
        {
            "alias": "os-types-extra-specs",
            "description": "Type extra specs support.",
            "links": [],
            "name": "TypesExtraSpecs",
            "updated": "2011-08-24T00:00:00+00:00"
        },
        {
            "alias": "os-used-limits",
            "description": "Provide data on limited resources that are being used.",
            "links": [],
            "name": "UsedLimits",
            "updated": "2013-10-03T00:00:00+00:00"
        },
        {
            "alias": "os-vol-mig-status-attr",
            "description": "Expose migration_status as an attribute of a volume.",
            "links": [],
            "name": "VolumeMigStatusAttribute",
            "updated": "2013-08-08T00:00:00+00:00"
        },
        {
            "alias": "os-volume-type-access",
            "description": "Volume type access support.",
            "links": [],
            "name": "VolumeTypeAccess",
            "updated": "2014-06-26T00:00:00Z"
        },
        {
            "alias": "os-extended-services",
            "description": "Extended services support.",
            "links": [],
            "name": "ExtendedServices",
            "updated": "2014-01-10T00:00:00-00:00"
        },
        {
            "alias": "os-extended-snapshot-attributes",
            "description": "Extended SnapshotAttributes support.",
            "links": [],
            "name": "ExtendedSnapshotAttributes",
            "updated": "2012-06-19T00:00:00+00:00"
        },
        {
            "alias": "os-snapshot-unmanage",
            "description": "Enable volume unmanage operation.",
            "links": [],
            "name": "SnapshotUnmanage",
            "updated": "2014-12-31T00:00:00+00:00"
        },
        {
            "alias": "qos-specs",
            "description": "QoS specs support.",
            "links": [],
            "name": "Qos_specs_manage",
            "updated": "2013-08-02T00:00:00+00:00"
        },
        {
            "alias": "os-quota-class-sets",
            "description": "Quota classes management support.",
            "links": [],
            "name": "QuotaClasses",
            "updated": "2012-03-12T00:00:00+00:00"
        },
        {
            "alias": "os-volume-transfer",
            "description": "Volume transfer management support.",
            "links": [],
            "name": "VolumeTransfer",
            "updated": "2013-05-29T00:00:00+00:00"
        },
        {
            "alias": "os-volume-manage",
            "description": "Allows existing backend storage to be 'managed' by Cinder.",
            "links": [],
            "name": "VolumeManage",
            "updated": "2014-02-10T00:00:00+00:00"
        },
        {
            "alias": "os-admin-actions",
            "description": "Enable admin actions.",
            "links": [],
            "name": "AdminActions",
            "updated": "2012-08-25T00:00:00+00:00"
        },
        {
            "alias": "os-services",
            "description": "Services support.",
            "links": [],
            "name": "Services",
            "updated": "2012-10-28T00:00:00-00:00"
        },
        {
            "alias": "scheduler-stats",
            "description": "Scheduler stats support.",
            "links": [],
            "name": "Scheduler_stats",
            "updated": "2014-09-07T00:00:00+00:00"
        },
        {
            "alias": "OS-SCH-HNT",
            "description": "Pass arbitrary key/value pairs to the scheduler.",
            "links": [],
            "name": "SchedulerHints",
            "updated": "2013-04-18T00:00:00+00:00"
        }
    ]
}

卷类型 (types)

要创建一个具有多个存储后端的环境，您必须指定一个卷类型。API 将块存储卷后端作为 `cinder-volume` 的子进程生成，并通过唯一队列对其进行键控。API 将后端命名为 `cinder-volume.HOST.BACKEND`。例如，`cinder-volume.ubuntu.lvmdriver`。当您创建卷时，调度器会选择一个合适的后端来处理该卷类型的请求。

有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

PUT
/v3/{project_id}/types/{volume_type_id}

更新卷类型

更新卷类型。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

volume_type

body

对象

一个 `volume_type` 对象。

name (可选)

body

字符串

卷类型的名称。

description (可选)

body

字符串

卷类型的描述。

is_public (可选)

body

布尔值

卷类型是否公开可见。请参阅 有效的布尔值。

请求示例

{
    "volume_type": {
        "name": "vol-type-001",
        "description": "volume type 0001",
        "is_public": true
    }
}

响应参数

名称

入参

类型

描述

volume_type

body

对象

一个 `volume_type` 对象。

is_public

body

布尔值

卷类型是否公开可见。

extra_specs (可选)

body

对象

键值对，包含与卷类型相关的其他规范。例如，根据使用的存储驱动程序，可能包括功能、容量、压缩等。

description

body

字符串

卷类型的描述。

name

body

字符串

卷类型的名称。

id

路径

字符串

现有卷类型的 UUID。

响应示例

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "vol-type-001",
        "description": "volume type 0001",
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
POST
/v3/{project_id}/types/{volume_type_id}/extra_specs

创建或更新卷类型的额外规范

向卷类型添加新的额外规范，或更新分配给卷类型的额外规范。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

extra_specs

body

对象

包含卷类型规范的键值对集合。

请求示例

{
    "extra_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}

响应参数

名称

入参

类型

描述

extra_specs

body

对象

包含卷类型规范的键值对集合。

响应示例

{
    "extra_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
GET
/v3/{project_id}/types/{volume_type_id}/extra_specs

显示卷类型的全部额外规范

显示分配给卷类型的全部额外规范。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

响应参数

名称

入参

类型

描述

extra_specs

body

对象

包含卷类型规范的键值对集合。

响应示例

{
    "extra_specs": {
        "capabilities": "gpu"
    }
}
GET
/v3/{project_id}/types/{volume_type_id}/extra_specs/{key}

显示卷类型的额外规范

显示分配给卷类型的特定额外规范。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

key

路径

字符串

卷类型额外规范的键名。

响应示例

{
    "capabilities": "gpu"
}
PUT
/v3/{project_id}/types/{volume_type_id}/extra_specs/{key}

更新卷类型的额外规范

更新分配给卷类型的特定额外规范。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

key

路径

字符串

卷类型额外规范的键名。

请求示例

{
    "key1": "value1"
}

响应示例

{
    "key1": "value1"
}
DELETE
/v3/{project_id}/types/{volume_type_id}/extra_specs/{key}

删除卷类型的额外规范

删除分配给卷类型的特定额外规范。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

key

路径

字符串

卷类型额外规范的键名。
GET
/v3/{project_id}/types/{volume_type_id}

显示卷类型详细信息

显示卷类型的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

响应参数

名称

入参

类型

描述

volume_type

body

对象

一个 `volume_type` 对象。

is_public

body

布尔值

卷类型是否公开可见。

extra_specs (可选)

body

对象

键值对，包含与卷类型相关的其他规范。例如，根据使用的存储驱动程序，可能包括功能、容量、压缩等。

description

body

字符串

卷类型的描述。

name

body

字符串

卷类型的名称。

id

body

字符串

卷类型的 UUID。

os-volume-type-access:is_public

body

布尔值

卷类型是否公开可见。

qos_specs_id (可选)

body

字符串

QoS 规范的 ID。

响应示例

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "qos_specs_id": null,
        "name": "vol-type-001",
        "description": "volume type 0001",
        "os-volume-type-access:is_public": true,
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
GET
/v3/{project_id}/types/default

显示默认卷类型

显示默认卷类型的详细信息，即，如果您在“创建卷”请求中未指定卷类型，则将使用的卷类型。这可能是以下之一：

  • 您项目的默认卷类型 _(自微版本 3.62 起)_

  • 由操作员配置的安装默认卷类型

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
404 - Not Found

找不到请求的资源。
500 - 内部服务器错误

服务出现问题，导致无法满足请求。

错误条件

在块存储服务的 Train 版本之前的版本中，只能收到 404 (未找到) 响应，因为自 Train 版本以来，已配置的默认卷类型是必需的。

如果您收到 500 (内部错误响应)，则表示操作员未正确配置默认卷类型。请联系您的云提供商。

  • 当默认卷类型配置错误时，不包含卷类型的“创建卷”请求将失败。

  • 解决方法是在请求中包含卷类型。您可以通过“列出所有卷类型”来确定要使用的卷类型。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

响应参数

名称

入参

类型

描述

volume_type

body

对象

一个 `volume_type` 对象。

is_public

body

布尔值

卷类型是否公开可见。

extra_specs (可选)

body

对象

键值对，包含与卷类型相关的其他规范。例如，根据使用的存储驱动程序，可能包括功能、容量、压缩等。

description

body

字符串

卷类型的描述。

name

body

字符串

卷类型的名称。

qos_specs_id (可选)

body

字符串

QoS 规范的 ID。

响应示例

{
    "volume_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "qos_specs_id": null,
        "name": "vol-type-001",
        "description": "volume type 0001",
        "is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}
DELETE
/v3/{project_id}/types/{volume_type_id}

删除卷类型

删除卷类型。

给操作员的说明： 自 Train 版本以来，不允许使用无类型卷，并且每个部署都需要一个已配置的默认卷类型。尝试删除已配置的默认卷类型将失败。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。
GET
/v3/{project_id}/types

列出所有卷类型

列出卷类型。

要确定其中哪一个是默认类型（如果您在“创建卷”请求中未指定），请使用“显示默认卷类型”请求。

给用户的说明： 列表中可能有一个名为 `__DEFAULT__` 的卷类型。除非必要或操作员指示，否则请尽量不要在“创建卷”请求中使用此卷类型。如果您想创建 *您的* 默认卷类型的卷，只需在“创建卷”请求中省略 `volume_type` 参数即可。

给操作员的说明： `__DEFAULT__` 卷类型是在 Train 版本中引入的，作为占位符以防止创建无类型卷。在适当的条件下，它可以从您的部署中移除。有关详细信息，请参阅 Cinder 管理员指南 中的“默认卷类型”部分。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

is_public (可选)

查询

布尔值

按公共可见性过滤卷类型。请参阅 有效的布尔值。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

volume_types

body

数组

卷类型列表。在具有多个存储后端的环境中，调度器会根据卷类型确定将卷发送到哪里。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

extra_specs (可选)

body

对象

键值对，包含与卷类型相关的其他规范。例如，根据使用的存储驱动程序，可能包括功能、容量、压缩等。

name

body

字符串

卷类型的名称。

is_public

body

布尔值

卷类型是否公开可见。

description

body

字符串

卷类型的描述。

id

body

字符串

卷类型的 UUID。

os-volume-type-access:is_public

body

布尔值

卷类型是否公开可见。

qos_specs_id (可选)

body

字符串

QoS 规范的 ID。

响应示例

{
    "volume_types": [
        {
            "description": "volume type 0002",
            "extra_specs": {
                "capabilities": "gpu"
            },
            "id": "ef512777-6552-4013-82f0-57a96e5804b7",
            "is_public": true,
            "name": "vol-type-002",
            "os-volume-type-access:is_public": true,
            "qos_specs_id": null
        },
        {
            "description": "volume type 0001",
            "extra_specs": {
                "capabilities": "gpu"
            },
            "id": "18947ff2-ad57-42b2-9350-34262e530203",
            "is_public": true,
            "name": "vol-type-001",
            "os-volume-type-access:is_public": true,
            "qos_specs_id": null
        },
        {
            "description": "Default Volume Type",
            "extra_specs": {},
            "id": "7a56b996-b73f-4233-9f00-dd6a68b49b27",
            "is_public": true,
            "name": "__DEFAULT__",
            "os-volume-type-access:is_public": true,
            "qos_specs_id": null
        }
    ]
}
POST
/v3/{project_id}/types

创建一个卷类型

创建一个卷类型。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type

body

对象

一个 `volume_type` 对象。

name

body

字符串

卷类型的名称。

os-volume-type-access:is_public (可选)

body

布尔值

卷类型是否公开可见。请参阅 有效的布尔值。

description (可选)

body

字符串

卷类型的描述。

extra_specs (可选)

body

对象

键值对，包含与卷类型相关的其他规范。例如，根据使用的存储驱动程序，可能包括功能、容量、压缩等。

请求示例

{
    "volume_type": {
        "name": "vol-type-001",
        "description": "volume type 0001",
        "os-volume-type-access:is_public": true,
        "extra_specs": {
            "capabilities": "gpu"
        }
    }
}

响应参数

名称

入参

类型

描述

volume_type

body

对象

一个 `volume_type` 对象。

is_public

body

布尔值

卷类型是否公开可见。

extra_specs (可选)

body

对象

键值对，包含与卷类型相关的其他规范。例如，根据使用的存储驱动程序，可能包括功能、容量、压缩等。

description

body

字符串

卷类型的描述。

name

body

字符串

卷类型的名称。

id

body

字符串

卷类型的 UUID。

os-volume-type-access:is_public

body

布尔值

卷类型是否公开可见。

响应示例

{
    "volume_type": {
        "name": "vol-type-001",
        "extra_specs": {
            "capabilities": "gpu"
        },
        "os-volume-type-access:is_public": true,
        "is_public": true,
        "id": "6d0ff92a-0007-4780-9ece-acfe5876966a",
        "description": "volume type 0001"
    }
}
GET
/v3/{project_id}/types/{volume_type_id}/encryption

显示加密类型

显示现有卷类型的加密类型。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

响应参数

名称

入参

类型

描述

volume_type_id

body

字符串

卷类型的 UUID。

encryption_id

body

字符串

加密的 UUID。

key_size (可选)

body

整数

加密密钥的大小（以位为单位）。通常为 256。默认值为 None。

provider

body

字符串

提供加密支持的类。

control_location (可选)

body

字符串

执行加密的逻辑服务。有效值为“front-end”或“back-end”。默认值为“front-end”。

cipher (可选)

body

字符串

加密算法或模式。例如，aes-xts-plain64。默认值为 None。

deleted

body

布尔值

资源是否已删除。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

deleted_at

body

字符串

删除资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果 `deleted_at` 日期和时间戳未设置，则其值为 `null`。

响应示例

{
    "volume_type_id": "2d29462d-76cb-417c-8a9f-fb23140f1577",
    "control_location": "front-end",
    "deleted": false,
    "created_at": "2016-12-28T02:32:25.000000",
    "updated_at": null,
    "encryption_id": "81e069c6-7394-4856-8df7-3b237ca61f74",
    "key_size": 256,
    "provider": "luks",
    "deleted_at": null,
    "cipher": "aes-xts-plain64"
}
GET
/v3/{project_id}/types/{volume_type_id}/encryption/{key}

显示加密规范项

显示现有卷类型的加密规范项。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

key

路径

字符串

卷类型加密规范的键名。

响应示例

{
    "cipher": "aes-xts-plain64"
}
DELETE
/v3/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

删除加密类型

删除现有卷类型的加密类型。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

encryption_id

路径

字符串

加密类型的 ID。
POST
/v3/{project_id}/types/{volume_type_id}/encryption

创建加密类型

为现有卷类型创建加密类型。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

encryption

body

对象

加密信息。

key_size (可选)

body

整数

加密密钥的大小（以位为单位）。通常为 256。默认值为 None。

provider

body

字符串

提供加密支持的类。选项包括：

  • luks - 依赖于 Linux Unified Key Setup (推荐)

  • plain - 依赖于 dm-crypt

control_location (可选)

body

字符串

执行加密的逻辑服务。有效值为“front-end”或“back-end”。默认值为“front-end”。

cipher (可选)

body

字符串

加密算法或模式。例如，aes-xts-plain64。默认值为 None。

请求示例

{
    "encryption":{
        "key_size": 256,
        "provider": "luks",
        "control_location":"front-end",
        "cipher": "aes-xts-plain64"
    }
}

响应参数

名称

入参

类型

描述

encryption

body

对象

加密信息。

volume_type_id

body

字符串

卷类型的 UUID。

encryption_id

body

字符串

加密的 UUID。

key_size (可选)

body

整数

加密密钥的大小（以位为单位）。通常为 256。默认值为 None。

provider

body

字符串

提供加密支持的类。

control_location (可选)

body

字符串

执行加密的逻辑服务。有效值为“front-end”或“back-end”。默认值为“front-end”。

cipher (可选)

body

字符串

加密算法或模式。例如，aes-xts-plain64。默认值为 None。

响应示例

{
    "encryption": {
        "volume_type_id": "2d29462d-76cb-417c-8a9f-fb23140f1577",
        "control_location": "front-end",
        "encryption_id": "81e069c6-7394-4856-8df7-3b237ca61f74",
        "key_size": 256,
        "provider": "luks",
        "cipher": "aes-xts-plain64"
    }
}
PUT
/v3/{project_id}/types/{volume_type_id}/encryption/{encryption_id}

更新加密类型

更新现有卷类型的加密类型。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

encryption_id

路径

字符串

加密类型的 ID。

encryption

body

对象

加密信息。

key_size (可选)

body

整数

加密密钥的大小（以位为单位）。通常为 256。默认值为 None。

provider (可选)

body

字符串

提供加密支持的类。选项包括：

  • luks - 依赖于 Linux Unified Key Setup (推荐)

  • plain - 依赖于 dm-crypt

control_location (可选)

body

字符串

执行加密的逻辑服务。有效值为“front-end”或“back-end”。默认值为“front-end”。

cipher (可选)

body

字符串

加密算法或模式。例如，aes-xts-plain64。默认值为 None。

请求示例

{
    "encryption":{
        "key_size": 64,
        "provider": "luks",
        "control_location":"back-end",
        "cipher": "aes-xts-plain64"
    }
}

响应参数

名称

入参

类型

描述

encryption

body

对象

加密信息。

key_size (可选)

body

整数

加密密钥的大小（以位为单位）。通常为 256。默认值为 None。

provider (可选)

body

字符串

提供加密支持的类。

control_location (可选)

body

字符串

执行加密的逻辑服务。有效值为“front-end”或“back-end”。默认值为“front-end”。

cipher (可选)

body

字符串

加密算法或模式。例如，aes-xts-plain64。默认值为 None。

响应示例

{
    "encryption":{
        "key_size": 64,
        "provider": "luks",
        "control_location":"back-end",
        "cipher": "aes-xts-plain64"
    }
}

卷类型访问 (types, action) (types, os-volume-type-access)

私有卷类型对项目的访问。

默认情况下，卷类型是公共的。要创建私有卷类型，在创建卷类型时将 `is_public` 布尔字段设置为 `false`。要控制对私有卷类型的访问，用户需要向卷类型添加项目或从中移除项目。没有项目的私有卷类型只能由具有管理员角色和上下文的用户访问。

POST
/v3/{project_id}/types/{volume_type}/action

向项目添加私有卷类型访问

将私有卷类型访问权限添加到项目。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type

路径

字符串

现有卷类型的 UUID。

addProjectAccess

body

对象

向项目添加卷类型访问。

project

body

字符串

项目 ID。要添加到此项目 ID 的卷类型访问。

请求示例

{
    "addProjectAccess": {
        "project": "6f70656e737461636b20342065766572"
    }
}
POST
/v3/{project_id}/types/{volume_type}/action

从项目中移除私有卷类型访问

从项目中移除私有卷类型访问。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type

路径

字符串

现有卷类型的 UUID。

removeProjectAccess

body

对象

从项目中移除卷类型访问。

project

body

字符串

项目 ID。要添加到此项目 ID 的卷类型访问。

请求示例

{
    "removeProjectAccess": {
        "project": "f270b245cb11498ca4031deb7e141cfa"
    }
}
GET
/v3/{project_id}/types/{volume_type}/os-volume-type-access

列出私有卷类型访问详细信息

列出具有对私有卷类型访问权限的项目 ID。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type

路径

字符串

现有卷类型的 UUID。

响应参数

名称

入参

类型

描述

volume_type_access

body

数组

包含卷类型列表，供项目访问。

project_id

body

字符串

项目的 UUID。

volume_type_id

body

字符串

卷类型的 UUID。

响应示例

{
    "volume_type_access": [
        {
            "project_id": "6f70656e737461636b20342065766572",
            "volume_type_id": "a5082c24-2a27-43a4-b48e-fcec1240e36b"
        }
    ]
}

默认卷类型 (default-types)

为各个项目管理默认卷类型。

默认情况下，不指定卷类型的卷创建请求会将已配置的系统默认卷类型分配给卷。您可以为任何项目设置不同的默认卷类型来覆盖此行为。

微版本 3.62 或更高版本可用。

注意：列表 API 的默认策略是系统管理员，因此您需要系统范围的令牌才能访问它。要获取系统范围的令牌，您需要运行以下命令：

openstack –os-system-scope all –os-project-name=’’ token issue

PUT
/v3/default-types/{project-id}

创建或更新默认卷类型

创建或更新项目的默认卷类型。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求参数

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_type

路径

字符串

现有卷类型的名称或 UUID。

请求示例

{
    "default_type": {
        "volume_type": "lvm_backend"
    }
}

响应参数

名称

入参

类型

描述

project_id

body

字符串

项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

响应示例

{
    "default_type": {
        "project_id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "volume_type_id": "40ec6e5e-c9bd-4170-8740-c1cd42d7eabb"
    }
}
GET
/v3/default-types/{project-id}

显示默认卷类型

显示项目的默认卷类型。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
404 - Not Found

找不到请求的资源。

请求参数

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

响应参数

名称

入参

类型

描述

project_id

body

字符串

项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

响应示例

{
    "default_type": {
        "project_id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "volume_type_id": "40ec6e5e-c9bd-4170-8740-c1cd42d7eabb"
    }
}
GET
/v3/default-types/

列出默认卷类型

获取所有默认卷类型的列表。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
404 - Not Found

找不到请求的资源。

响应参数

名称

入参

类型

描述

project_id

body

字符串

项目的 UUID。

volume_type_id

路径

字符串

现有卷类型的 UUID。

响应示例

{
    "default_types": [
        {
        "project_id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "volume_type_id": "40ec6e5e-c9bd-4170-8740-c1cd42d7eabb"
        },
        {
        "project_id": "dd46ea3e-6f3f-4e50-85fa-40c182e25d12",
        "volume_type_id": "9fb51b63-3cd4-493f-9380-53d8f0a04bd4"
        }
    ]
}
DELETE
/v3/default-types/{project-id}

删除默认卷类型

取消设置项目的默认卷类型。

此操作不会影响卷类型本身。它只是将卷类型从指定项目的默认卷类型中移除。

响应码

成功

代码

原因
204 - No Content

请求已满足，但服务未返回任何内容。
错误

代码

原因
404 - Not Found

找不到请求的资源。

请求参数

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

卷 (volumes)

卷是可分离的块存储设备，类似于 USB 硬盘驱动器。您可以将卷附加到实例，如果卷是适当的卷类型，则可以将一个卷附加到多个实例。

`snapshot_id` 和 `source_volid` 参数指定此卷源自的快照或卷的 ID。如果卷不是从快照或源卷创建的，则这些值为 null。

当您创建、列出、更新或删除卷时，可能的状态值为：

卷状态

状态

描述

creating

卷正在创建中。

available

卷已准备好附加到实例。

reserved

卷已预留用于附加或已放入库中。

attaching

卷正在附加到实例。

detaching

卷正在从实例分离。

in-use

卷已附加到实例。

maintenance

卷被锁定并正在迁移。

deleting

卷正在删除中。

awaiting-transfer

卷正在等待传输。

error

发生卷创建错误。

error_deleting

发生卷删除错误。

backing-up

卷正在备份中。

restoring-backup

正在将备份恢复到卷。

error_backing-up

发生备份错误。

error_restoring

发生备份恢复错误。

error_extending

尝试扩展卷时发生错误。

downloading

卷正在下载镜像。

uploading

卷正在上传到镜像。

retyping

卷正在更改类型为另一种卷类型。

extending

卷正在扩展中。
GET
/v3/{project_id}/volumes/detail

列出可访问的卷（含详细信息）

列出项目可以访问的所有块存储卷（含详细信息），自 v3.31 起，如果非管理员用户在 URL 中指定无效的过滤器，API 将返回错误请求。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

metadata (可选)

查询

对象

一个或多个元数据键值对，作为 URL 编码的字符串字典。

with_count (可选)

查询

布尔值

是否在 API 响应中显示 `count`，默认为 `False`。

版本 3.45 新增

created_at (可选)

查询

字符串

按资源创建时间过滤结果，并带时间比较运算符：gt/gte/eq/neq/lt/lte。日期时间戳格式为 ISO 8601：CCYY-MM-DDThh:mm:ss±hh:mm。如果包含 ±hh:mm 值，则返回时区作为 UTC 的偏移量。

版本 3.60 新增

updated_at (可选)

查询

字符串

按资源更新时间过滤结果，并带时间比较运算符：gt/gte/eq/neq/lt/lte。日期时间戳格式为 ISO 8601：CCYY-MM-DDThh:mm:ss±hh:mm。如果包含 ±hh:mm 值，则返回时区作为 UTC 的偏移量。

版本 3.60 新增

consumes_quota (可选)

查询

布尔值

按 `consumes_quota` 字段过滤结果。不使用配额的资源通常是用于执行操作的临时内部资源。默认不进行过滤。过滤此选项可能并非总能在云中实现，请参阅 资源过滤器 以确定此过滤器在您的云中是否可用。

版本 3.65 新增

响应参数

名称

入参

类型

描述

migration_status (可选)

body

字符串

卷迁移状态。仅限管理员。

attachments

body

数组

实例附加信息。如果此卷已附加到服务器实例，则 `attachments` 列表将包括已附加服务器的 UUID、附件 UUID、已附加主机的名称（如果存在）、卷 UUID、设备以及设备 UUID。否则，此列表为空。例如：

[
  {
    'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
    'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
    'attached_at': '2019-09-30T19:30:34.000000',
    'host_name': null,
    'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
    'device': '/dev/vda',
    'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
  }
]

links

body

数组

卷链接。

availability_zone (可选)

body

字符串

可用区的名称。

os-vol-host-attr:host (可选)

body

字符串

卷的当前后端。主机格式为 `host@backend#pool`。

encrypted

body

布尔值

如果为 true，则此卷已加密。

encryption_key_id (可选)

body

字符串

加密密钥的 UUID。仅对加密卷包含。

版本 3.64 新增

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

replication_status

body

字符串

卷复制状态。

snapshot_id (可选)

body

字符串

要从现有快照创建卷，请指定卷快照的 UUID。卷将在与快照相同的可用区域中以相同大小创建。

id

body

字符串

卷的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

user_id

body

字符串

用户的 UUID。

os-vol-tenant-attr:tenant_id

body

字符串

卷所属的项目 ID。

os-vol-mig-status-attr:migstat (可选)

body

字符串

此卷迁移的状态（None 表示当前没有正在进行的迁移）。

metadata

body

对象

一个 `metadata` 对象。包含一个或多个与卷关联的元数据键值对。

status

body

字符串

卷状态。

volume_image_metadata (可选)

body

对象

镜像元数据条目列表。仅对从镜像创建的卷，或从最初从镜像创建的卷的快照创建的卷包含。

description

body

字符串

卷描述。

multiattach

body

布尔值

如果为 true，则此卷可以附加到多个实例。

source_volid (可选)

body

字符串

源卷的 UUID。API 会创建一个与源卷大小相同的新卷，除非请求了更大的大小。

consistencygroup_id

body

字符串

一致性组的 UUID。

os-vol-mig-status-attr:name_id (可选)

body

字符串

此卷在后端上的名称所基于的卷 ID。

name

body

字符串

卷名称。

bootable

body

字符串

启用或禁用可启动属性。您可以从可启动卷启动实例。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volumes

body

数组

一个 `volume` 对象的列表。

volume_type

body

字符串

卷关联的卷类型名称。

volume_type_id

body

对象

卷关联的卷类型 ID。

版本 3.63 新增

group_id (可选)

body

字符串

组的 ID。

版本 3.13 新增

volumes_links (可选)

body

数组

卷链接。

provider_id (可选)

body

字符串

卷的提供商 ID。值要么是驱动程序设置的字符串，要么是 `null`（如果驱动程序不使用该字段或尚未创建它）。仅返回给管理员。

版本 3.21 新增

service_uuid

body

字符串

一个唯一的标识符，用于指示特定卷的卷服务是由哪个节点提供的。

版本 3.48 新增

shared_targets

body

布尔值

一个指示符，表示托管该卷的后端是否使用 `shared_targets`。默认值=True。

版本 3.48 新增

可用至版本 3.68

shared_targets

body

布尔值

一个指示符，表示连接该卷的主机是否应该在整个附加/分离过程中进行锁定。 `true` 表示仅当主机上的 iSCSI 启动器不支持手动扫描时，`false` 表示从不使用锁定，而 `null` 表示始终使用锁定。请查看 os-brick 的 `guard_connection` 上下文管理器。默认值=True。

版本 3.69 新增

cluster_name (可选)

body

字符串

卷后端的集群名称。

版本 3.61 新增

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

count (可选)

body

整数

应用分页之前的请求资源的 মোট 数量。

版本 3.45 新增

响应示例 (v3.65)

{
    "volumes": [
        {
            "attachments": [],
            "availability_zone": "nova",
            "bootable": "false",
            "consistencygroup_id": null,
            "created_at": "2018-11-28T06:25:15.288987",
            "description": null,
            "encrypted": false,
            "id": "cb49b381-9012-40cb-b8ee-80c19a4801b5",
            "links": [
                {
                    "href": "http://127.0.0.1:43543/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/cb49b381-9012-40cb-b8ee-80c19a4801b5",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:43543/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/cb49b381-9012-40cb-b8ee-80c19a4801b5",
                    "rel": "bookmark"
                }
            ],
            "metadata": {},
            "migration_status": null,
            "multiattach": false,
            "name": null,
            "os-vol-host-attr:host": null,
            "os-vol-mig-status-attr:migstat": null,
            "os-vol-mig-status-attr:name_id": null,
            "os-vol-tenant-attr:tenant_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
            "replication_status": null,
            "size": 10,
            "snapshot_id": null,
            "source_volid": null,
            "status": "creating",
            "updated_at": null,
            "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
            "volume_type": "__DEFAULT__",
            "volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
            "provider_id": null,
            "group_id": null,
            "service_uuid": null,
            "shared_targets": true,
            "cluster_name": null,
            "consumes_quota": true
        }
    ]
}
POST
/v3/{project_id}/volumes

创建卷

创建卷。

要创建可启动卷，请在请求正文的 `imageRef` 属性中包含要从中创建卷的镜像的 UUID。

自 Train 版本以来，每个卷都必须有一个卷类型。在 *创建卷* 请求中指定卷类型是 **可选** 的。如果您不指定，将为您提供一个默认卷类型。此类型可能因您所在的项目以及操作员如何配置块存储服务而异。请使用 *显示默认卷类型* 请求来确定您生效的默认卷类型。

先决条件

  • 您必须有足够的卷存储配额来创建请求大小的卷。

异步后置条件

  • 具有正确权限，您可以通过 API 调用将卷状态显示为 `available`。

  • 具有正确访问权限，您可以在 OpenStack 块存储管理的存储系统中看到创建的卷。

故障排除

  • 如果卷状态保持为 `creating` 或显示其他错误状态，则请求失败。确保您满足先决条件，然后调查存储后端。

  • 卷未在 OpenStack 块存储管理的存储系统中创建。

  • 存储节点需要有足够的可用存储空间来匹配卷创建请求的大小。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume

body

对象

一个 volume 对象。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

availability_zone (可选)

body

字符串

可用区的名称。

source_volid (可选)

body

字符串

源卷的 UUID。API 会创建一个与源卷大小相同的新卷，除非请求了更大的大小。

description (可选)

body

字符串

卷描述。

snapshot_id (可选)

body

字符串

要从现有快照创建卷，请指定卷快照的 UUID。卷将在与快照相同的可用区域中以相同大小创建。

backup_id (可选)

body

字符串

备份的 UUID。

版本 3.47 新增

name (可选)

body

字符串

卷名称。

imageRef (可选)

body

字符串

您要从中创建卷的镜像的 UUID。创建可启动卷所必需。

**版本 3.46 新增**：块存储服务将不再直接使用计算服务在请求实例快照时创建的零字节镜像，而是使用 `block_device_mapping` 镜像属性中包含的 `snapshot_id` 来查找卷快照，并使用该快照来创建卷。

volume_type (可选)

body

字符串

卷类型（名称或 ID）。要创建一个具有多个存储后端的环境，您必须指定一个卷类型。块存储卷后端作为 `cinder-volume` 的子进程生成，并按唯一队列进行键控。它们命名为 `cinder-volume.HOST.BACKEND`。例如，`cinder-volume.ubuntu.lvmdriver`。在创建卷时，调度器会根据卷类型选择一个合适的后端来处理请求。默认为 `None`。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

metadata (可选)

body

对象

要与新卷关联的一个或多个元数据键值对。

consistencygroup_id

body

字符串

一致性组的 UUID。

OS-SCH-HNT:scheduler_hints (可选)

body

对象

发送到调度器的字典数据。

请求示例

{
    "volume": {
        "size": 10,
        "availability_zone": null,
        "source_volid": null,
        "description": null,
        "multiattach": false,
        "snapshot_id": null,
        "backup_id": null,
        "name": null,
        "imageRef": null,
        "volume_type": null,
        "metadata": {},
        "consistencygroup_id": null
    },
    "OS-SCH-HNT:scheduler_hints": {
        "same_host": [
            "a0cf03a5-d921-4877-bb5c-86d26cf818e1",
            "8c19174f-4220-44f0-824a-cd1eeef10287"
        ]
    }
}

响应参数

名称

入参

类型

描述

migration_status (可选)

body

字符串

卷迁移状态。仅限管理员。

attachments

body

数组

实例附加信息。如果此卷已附加到服务器实例，则 `attachments` 列表将包括已附加服务器的 UUID、附件 UUID、已附加主机的名称（如果存在）、卷 UUID、设备以及设备 UUID。否则，此列表为空。例如：

[
  {
    'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
    'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
    'attached_at': '2019-09-30T19:30:34.000000',
    'host_name': null,
    'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
    'device': '/dev/vda',
    'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
  }
]

links

body

数组

卷链接。

availability_zone (可选)

body

字符串

可用区的名称。

encrypted

body

布尔值

如果为 true，则此卷已加密。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

replication_status

body

字符串

卷复制状态。

snapshot_id (可选)

body

字符串

要从现有快照创建卷，请指定卷快照的 UUID。卷将在与快照相同的可用区域中以相同大小创建。

id

body

字符串

卷的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

user_id

body

字符串

用户的 UUID。

metadata

body

对象

一个 `metadata` 对象。包含一个或多个与卷关联的元数据键值对。

status

body

字符串

卷状态。

description

body

字符串

卷描述。

multiattach

body

布尔值

如果为 true，则此卷可以附加到多个实例。

source_volid (可选)

body

字符串

源卷的 UUID。API 会创建一个与源卷大小相同的新卷，除非请求了更大的大小。

volume

body

对象

一个 volume 对象。

consistencygroup_id

body

字符串

一致性组的 UUID。

name

body

字符串

卷名称。

bootable

body

字符串

启用或禁用可启动属性。您可以从可启动卷启动实例。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_type

body

字符串

卷关联的卷类型名称。

volume_type_id

body

对象

卷关联的卷类型 ID。

版本 3.63 新增

group_id (可选)

body

字符串

组的 ID。

版本 3.13 新增

provider_id (可选)

body

字符串

卷的提供商 ID。值要么是驱动程序设置的字符串，要么是 `null`（如果驱动程序不使用该字段或尚未创建它）。仅返回给管理员。

版本 3.21 新增

service_uuid

body

字符串

一个唯一的标识符，用于指示特定卷的卷服务是由哪个节点提供的。

版本 3.48 新增

shared_targets

body

布尔值

一个指示符，表示托管该卷的后端是否使用 `shared_targets`。默认值=True。

版本 3.48 新增

可用至版本 3.68

shared_targets

body

布尔值

一个指示符，表示连接该卷的主机是否应该在整个附加/分离过程中进行锁定。 `true` 表示仅当主机上的 iSCSI 启动器不支持手动扫描时，`false` 表示从不使用锁定，而 `null` 表示始终使用锁定。请查看 os-brick 的 `guard_connection` 上下文管理器。默认值=True。

版本 3.69 新增

cluster_name (可选)

body

字符串

卷后端的集群名称。

版本 3.61 新增

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

响应示例 (v3.65)

{
    "volume": {
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "consistencygroup_id": null,
        "created_at": "2018-11-28T06:21:12.715987",
        "description": null,
        "encrypted": false,
        "id": "2b955850-f177-45f7-9f49-ecb2c256d161",
        "links": [
            {
                "href": "http://127.0.0.1:33951/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/2b955850-f177-45f7-9f49-ecb2c256d161",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:33951/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/2b955850-f177-45f7-9f49-ecb2c256d161",
                "rel": "bookmark"
            }
        ],
        "metadata": {},
        "migration_status": null,
        "multiattach": false,
        "name": null,
        "replication_status": null,
        "size": 10,
        "snapshot_id": null,
        "source_volid": null,
        "status": "creating",
        "updated_at": null,
        "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
        "volume_type": "__DEFAULT__",
        "group_id": null,
        "provider_id": null,
        "service_uuid": null,
        "shared_targets": true,
        "cluster_name": null,
        "volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
        "consumes_quota": true
    }
}
GET
/v3/{project_id}/volumes

列出可访问的卷

列出项目可以访问的所有块存储卷的摘要信息，自 v3.31 起，如果非管理员用户在 URL 中指定无效的过滤器，API 将返回错误请求。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

metadata (可选)

查询

对象

一个或多个元数据键值对，作为 URL 编码的字符串字典。

with_count (可选)

查询

布尔值

是否在 API 响应中显示 `count`，默认为 `False`。

版本 3.45 新增

created_at (可选)

查询

字符串

按资源创建时间过滤结果，并带时间比较运算符：gt/gte/eq/neq/lt/lte。日期时间戳格式为 ISO 8601：CCYY-MM-DDThh:mm:ss±hh:mm。如果包含 ±hh:mm 值，则返回时区作为 UTC 的偏移量。

版本 3.60 新增

consumes_quota (可选)

查询

布尔值

按 `consumes_quota` 字段过滤结果。不使用配额的资源通常是用于执行操作的临时内部资源。默认不进行过滤。过滤此选项可能并非总能在云中实现，请参阅 资源过滤器 以确定此过滤器在您的云中是否可用。

版本 3.65 新增

updated_at (可选)

查询

字符串

按资源更新时间过滤结果，并带时间比较运算符：gt/gte/eq/neq/lt/lte。日期时间戳格式为 ISO 8601：CCYY-MM-DDThh:mm:ss±hh:mm。如果包含 ±hh:mm 值，则返回时区作为 UTC 的偏移量。

版本 3.60 新增

响应参数

名称

入参

类型

描述

volumes

body

数组

一个 `volume` 对象的列表。

id

body

字符串

卷的 UUID。

links

body

数组

卷链接。

name

body

字符串

卷名称。

volumes_links (可选)

body

数组

卷链接。

count (可选)

body

整数

应用分页之前的请求资源的 মোট 数量。

版本 3.45 新增

响应示例

{
    "volumes": [
        {
            "id": "efa54464-8fab-47cd-a05a-be3e6b396188",
            "links": [
                {
                    "href": "http://127.0.0.1:37097/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/efa54464-8fab-47cd-a05a-be3e6b396188",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:37097/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/efa54464-8fab-47cd-a05a-be3e6b396188",
                    "rel": "bookmark"
                }
            ],
            "name": null
        }
    ]
}
GET
/v3/{project_id}/volumes/{volume_id}

显示卷的详细信息

显示卷的详细信息。

先决条件

  • 卷必须存在。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

响应参数

名称

入参

类型

描述

migration_status (可选)

body

字符串

卷迁移状态。仅限管理员。

attachments

body

数组

实例附加信息。如果此卷已附加到服务器实例，则 `attachments` 列表将包括已附加服务器的 UUID、附件 UUID、已附加主机的名称（如果存在）、卷 UUID、设备以及设备 UUID。否则，此列表为空。例如：

[
  {
    'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
    'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
    'attached_at': '2019-09-30T19:30:34.000000',
    'host_name': null,
    'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
    'device': '/dev/vda',
    'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
  }
]

links

body

数组

卷链接。

availability_zone (可选)

body

字符串

可用区的名称。

os-vol-host-attr:host (可选)

body

字符串

卷的当前后端。主机格式为 `host@backend#pool`。

encrypted

body

布尔值

如果为 true，则此卷已加密。

encryption_key_id (可选)

body

字符串

加密密钥的 UUID。仅对加密卷包含。

版本 3.64 新增

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

replication_status

body

字符串

卷复制状态。

snapshot_id (可选)

body

字符串

要从现有快照创建卷，请指定卷快照的 UUID。卷将在与快照相同的可用区域中以相同大小创建。

id

body

字符串

卷的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

user_id

body

字符串

用户的 UUID。

os-vol-tenant-attr:tenant_id

body

字符串

卷所属的项目 ID。

os-vol-mig-status-attr:migstat (可选)

body

字符串

此卷迁移的状态（None 表示当前没有正在进行的迁移）。

metadata

body

对象

一个 `metadata` 对象。包含一个或多个与卷关联的元数据键值对。

status

body

字符串

卷状态。

volume_image_metadata (可选)

body

对象

镜像元数据条目列表。仅对从镜像创建的卷，或从最初从镜像创建的卷的快照创建的卷包含。

description

body

字符串

卷描述。

multiattach

body

布尔值

如果为 true，则此卷可以附加到多个实例。

source_volid (可选)

body

字符串

源卷的 UUID。API 会创建一个与源卷大小相同的新卷，除非请求了更大的大小。

volume

body

对象

一个 volume 对象。

consistencygroup_id

body

字符串

一致性组的 UUID。

os-vol-mig-status-attr:name_id (可选)

body

字符串

此卷在后端上的名称所基于的卷 ID。

name

body

字符串

卷名称。

bootable

body

字符串

启用或禁用可启动属性。您可以从可启动卷启动实例。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_type

body

字符串

卷关联的卷类型名称。

volume_type_id

body

对象

卷关联的卷类型 ID。

版本 3.63 新增

service_uuid

body

字符串

一个唯一的标识符，用于指示特定卷的卷服务是由哪个节点提供的。

版本 3.48 新增

shared_targets

body

布尔值

一个指示符，表示托管该卷的后端是否使用 `shared_targets`。默认值=True。

版本 3.48 新增

可用至版本 3.68

shared_targets

body

布尔值

一个指示符，表示连接该卷的主机是否应该在整个附加/分离过程中进行锁定。 `true` 表示仅当主机上的 iSCSI 启动器不支持手动扫描时，`false` 表示从不使用锁定，而 `null` 表示始终使用锁定。请查看 os-brick 的 `guard_connection` 上下文管理器。默认值=True。

版本 3.69 新增

cluster_name (可选)

body

字符串

卷后端的集群名称。

版本 3.61 新增

provider_id (可选)

body

字符串

卷的提供商 ID。值要么是驱动程序设置的字符串，要么是 `null`（如果驱动程序不使用该字段或尚未创建它）。仅返回给管理员。

版本 3.21 新增

group_id (可选)

body

字符串

组的 ID。

版本 3.13 新增

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

响应示例 (v3.65)

{
    "volume": {
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "consistencygroup_id": null,
        "created_at": "2018-11-29T06:50:07.770785",
        "description": null,
        "encrypted": false,
        "id": "f7223234-1afc-4d19-bfa3-d19deb6235ef",
        "links": [
            {
                "href": "http://127.0.0.1:45839/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/f7223234-1afc-4d19-bfa3-d19deb6235ef",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:45839/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/f7223234-1afc-4d19-bfa3-d19deb6235ef",
                "rel": "bookmark"
            }
        ],
        "metadata": {},
        "migration_status": null,
        "multiattach": false,
        "name": null,
        "os-vol-host-attr:host": null,
        "os-vol-mig-status-attr:migstat": null,
        "os-vol-mig-status-attr:name_id": null,
        "os-vol-tenant-attr:tenant_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
        "replication_status": null,
        "size": 10,
        "snapshot_id": null,
        "source_volid": null,
        "status": "creating",
        "updated_at": null,
        "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
        "volume_type": "__DEFAULT__",
        "provider_id": null,
        "group_id": null,
        "service_uuid": null,
        "shared_targets": true,
        "cluster_name": null,
        "volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
        "consumes_quota": true
    }
}
PUT
/v3/{project_id}/volumes/{volume_id}

更新卷

更新卷。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

volume

body

对象

一个 volume 对象。

description (可选)

body

字符串

卷描述。

name (可选)

body

字符串

卷名称。

metadata (可选)

body

对象

与卷关联的一个或多个元数据键值对。

请求示例

{
    "volume": {
        "name": "vol-003",
        "description": "This is yet, another volume.",
        "metadata": {
            "name": "metadata0"
        }
    }
}

响应参数

名称

入参

类型

描述

migration_status (可选)

body

字符串

卷迁移状态。仅限管理员。

attachments

body

数组

实例附加信息。如果此卷已附加到服务器实例，则 `attachments` 列表将包括已附加服务器的 UUID、附件 UUID、已附加主机的名称（如果存在）、卷 UUID、设备以及设备 UUID。否则，此列表为空。例如：

[
  {
    'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
    'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
    'attached_at': '2019-09-30T19:30:34.000000',
    'host_name': null,
    'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
    'device': '/dev/vda',
    'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
  }
]

links

body

数组

卷链接。

availability_zone (可选)

body

字符串

可用区的名称。

encrypted

body

布尔值

如果为 true，则此卷已加密。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

replication_status

body

字符串

卷复制状态。

snapshot_id (可选)

body

字符串

要从现有快照创建卷，请指定卷快照的 UUID。卷将在与快照相同的可用区域中以相同大小创建。

id

body

字符串

卷的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

user_id

body

字符串

用户的 UUID。

metadata

body

对象

一个 `metadata` 对象。包含一个或多个与卷关联的元数据键值对。

status

body

字符串

卷状态。

description

body

字符串

卷描述。

multiattach

body

布尔值

如果为 true，则此卷可以附加到多个实例。

source_volid (可选)

body

字符串

源卷的 UUID。API 会创建一个与源卷大小相同的新卷，除非请求了更大的大小。

volume

body

对象

一个 volume 对象。

consistencygroup_id

body

字符串

一致性组的 UUID。

name

body

字符串

卷名称。

bootable

body

字符串

启用或禁用可启动属性。您可以从可启动卷启动实例。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_type

body

字符串

卷关联的卷类型名称。

volume_type_id

body

对象

卷关联的卷类型 ID。

版本 3.63 新增

group_id (可选)

body

字符串

组的 ID。

版本 3.13 新增

provider_id (可选)

body

字符串

卷的提供商 ID。值要么是驱动程序设置的字符串，要么是 `null`（如果驱动程序不使用该字段或尚未创建它）。仅返回给管理员。

版本 3.21 新增

service_uuid

body

字符串

一个唯一的标识符，用于指示特定卷的卷服务是由哪个节点提供的。

版本 3.48 新增

shared_targets

body

布尔值

一个指示符，表示托管该卷的后端是否使用 `shared_targets`。默认值=True。

版本 3.48 新增

可用至版本 3.68

shared_targets

body

布尔值

一个指示符，表示连接该卷的主机是否应该在整个附加/分离过程中进行锁定。 `true` 表示仅当主机上的 iSCSI 启动器不支持手动扫描时，`false` 表示从不使用锁定，而 `null` 表示始终使用锁定。请查看 os-brick 的 `guard_connection` 上下文管理器。默认值=True。

版本 3.69 新增

cluster_name (可选)

body

字符串

卷后端的集群名称。

版本 3.61 新增

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

响应示例 (v3.65)

{
    "volume": {
        "attachments": [],
        "availability_zone": "nova",
        "bootable": "false",
        "consistencygroup_id": null,
        "created_at": "2018-11-29T06:59:23.679903",
        "description": "This is yet, another volume.",
        "encrypted": false,
        "id": "8b2459d1-0059-4e14-a89f-dfa73a452af6",
        "links": [
            {
                "href": "http://127.0.0.1:41467/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/8b2459d1-0059-4e14-a89f-dfa73a452af6",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:41467/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/volumes/8b2459d1-0059-4e14-a89f-dfa73a452af6",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "name": "metadata0"
        },
        "migration_status": null,
        "multiattach": false,
        "name": "vol-003",
        "replication_status": null,
        "size": 10,
        "snapshot_id": null,
        "source_volid": null,
        "status": "creating",
        "updated_at": null,
        "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
        "volume_type": "__DEFAULT__",
        "group_id": null,
        "provider_id": null,
        "service_uuid": null,
        "shared_targets": true,
        "cluster_name": null,
        "volume_type_id": "5fed9d7c-401d-46e2-8e80-f30c70cb7e1d",
        "consumes_quota": true
    }
}
DELETE
/v3/{project_id}/volumes/{volume_id}

删除卷

删除卷。

先决条件

  • 卷状态必须是 `available`、`in-use`、`error`、`error_restoring`、`error_extending`、`error_managing`，并且不能是 `migrating`、`attached`、`awaiting-transfer`、属于组、有快照或在卷传输后与快照分离。

  • 如果希望自动删除此卷的所有快照，可以在请求中传递 `cascade` 选项，这应该允许卷删除成功。

  • 您不能删除正在迁移中的卷。

异步后置条件

  • 卷在卷索引中被删除。

  • OpenStack 块存储管理的卷在存储节点中被删除。

故障排除

  • 如果卷状态保持为 `deleting` 或变为 `error_deleting`，则请求失败。确保您满足先决条件，然后调查存储后端。

  • OpenStack 块存储管理的卷未从存储系统中删除。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

cascade (可选)

查询

布尔值

删除卷的同时删除所有快照。默认值=False。

force (可选)

查询

布尔值

指示是否强制删除卷，即使该卷处于 `deleting` 或 `error_deleting` 状态。默认值为 `false`。

版本 3.23 新增
POST
/v3/{project_id}/volumes/{volume_id}/metadata

为卷创建元数据

创建或替换卷的元数据。不修改请求中未包含的项。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

metadata

body

对象

与卷关联的一个或多个元数据键值对。

请求示例

{
    "metadata": {
        "name": "metadata0"
    }
}

响应参数

名称

入参

类型

描述

metadata

body

对象

与卷关联的一个或多个元数据键值对。

响应示例

{
    "metadata": {
        "name": "metadata0"
    }
}
GET
/v3/{project_id}/volumes/{volume_id}/metadata

显示卷的元数据

显示卷的元数据。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

响应参数

名称

入参

类型

描述

metadata

body

对象

与卷关联的一个或多个元数据键值对。

响应示例

{
    "metadata": {}
}
PUT
/v3/{project_id}/volumes/{volume_id}/metadata

更新卷的元数据

用请求中的键值对替换卷的所有元数据。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

metadata

body

对象

与卷关联的一个或多个元数据键值对。

请求示例

{
    "metadata": {
        "name": "metadata1"
    }
}

响应参数

名称

入参

类型

描述

metadata

body

对象

与卷关联的一个或多个元数据键值对。

响应示例

{
    "metadata": {
        "name": "metadata1"
    }
}
GET
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

显示卷的特定键的元数据

显示卷的特定键的元数据。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

key

路径

字符串

要查看的元数据的元数据键名。

响应参数

名称

入参

类型

描述

meta

body

对象

卷的元数据键值对。

响应示例

{
    "meta": {
        "name": "metadata1"
    }
}
DELETE
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

删除卷的元数据

删除卷的元数据。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

key

路径

字符串

要移除的元数据的元数据键名。
PUT
/v3/{project_id}/volumes/{volume_id}/metadata/{key}

更新卷的特定键的元数据

更新卷的特定键的元数据。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

key

路径

字符串

要更新的元数据的元数据键名。

meta

body

对象

卷的元数据键值对。

请求示例

{
    "meta": {
        "name": "new_name"
    }
}

响应参数

名称

入参

类型

描述

meta

body

对象

卷的元数据键值对。

响应示例

{
    "meta": {
        "name": "new_name"
    }
}
GET
/v3/{project_id}/volumes/summary

获取卷摘要

显示卷摘要，包括卷的总数和总大小（GB）。自 API 微版本 3.12 起可用。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

响应参数

名称

入参

类型

描述

volume-summary

body

对象

`volume-summary` 对象的字典。

total_size

body

整数

卷的总大小（GB）。

total_count

body

整数

卷的总数。

metadata

body

对象

包含所有卷元数据的列表字典，按元数据键分类。

版本 3.36 新增

响应示例

{
    "volume-summary": {
        "total_size": 4,
        "total_count": 4,
        "metadata": {
            "key1": ["value1", "value2"],
            "key2": ["value2"]
        }
    }
}

卷操作 (volumes, action)

扩展卷大小、重置卷状态、设置或删除卷的镜像元数据。将卷附加到服务器、从服务器分离卷，以及在不实际移除关联的后端存储对象的情况下，将卷从块存储管理中移除。

POST
/v3/{project_id}/volumes/{volume_id}/action

扩展卷大小

将卷的大小扩展到请求的大小（以 GiB 为单位）。在请求正文中指定 `os-extend` 操作。

先决条件

  • 在微版本 `3.42` 之前，卷状态必须是 `available`。从微版本 `3.42` 开始，已附加的、状态为 `in-use` 的卷可能可以被扩展，具体取决于云中的策略和后端卷及计算驱动程序的限制。请注意，`reserved` 不是可用于扩展的有效状态。

  • 扩展卷必须有足够的存储空间。

  • 用户配额必须有足够的卷存储。

后置条件

  • 如果请求成功处理，在扩展卷大小时，卷状态将变为 `extending`。

  • 扩展操作成功完成后，卷状态将恢复到其原始值。

  • 从微版本 `3.42` 开始，在扩展已附加卷的大小时，块存储服务会通知计算服务已扩展附加卷。计算服务将异步处理相关服务器实例的卷大小更改。这可以通过计算服务中的 `GET /servers/{server_id}/os-instance-actions` API 进行监控。

故障排除

  • `error_extending` 卷状态表示请求失败。确保您满足先决条件并重试请求。如果请求再次失败，请调查存储后端。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-extend

body

对象

`os-extend` 操作。

new_size

body

整数

卷的新大小（以 GiB 为单位）。

请求示例

{
    "os-extend": {
        "new_size": 3
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

完成卷扩展

在请求正文中指定 `os-extend_volume_completion` 操作。

完成已附加卷的扩展，该卷在通知计算代理后仍处于 `extending` 状态。根据 `error` 参数的值，扩展操作将回滚或最终确定。

先决条件

  • 卷的状态必须是 `extending`。

  • 卷的管理员元数据必须包含一组指示 Cinder 正在等待操作成功外部反馈的键。

异步后置条件

如果 `error` 参数为 `false` 或缺失，并且扩展操作已成功完成，则卷状态将为 `in-use`。否则，卷状态将为 `error_extending`。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

volume_id

路径

字符串

卷的 UUID。

project_id

路径

字符串

多租户云中项目的 UUID。

os-extend_volume_completion

body

对象

`os-extend_volume_completion` 操作。

错误 (可选)

body

布尔值

用于指示扩展操作在 Cinder 外部失败。

请求示例

{
    "os-extend_volume_completion": {
        "error": false
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

重置卷的状态

仅限管理员。重置卷的状态、附加状态、回滚到快照状态和迁移状态。在请求正文中指定 `os-reset_status` 操作。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-reset_status

body

对象

`os-reset_status` 操作。

status

body

字符串

卷状态。

migration_status (可选)

body

字符串

卷迁移状态。仅限管理员。

attach_status (可选)

body

字符串

卷附加状态。

请求示例

{
    "os-reset_status": {
        "status": "available",
        "attach_status": "detached",
        "migration_status": "migrating"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

还原卷到快照

将卷恢复到其最新快照，此 API 仅支持恢复已分离的卷，且卷状态必须为 `available`。

自 API 微版本 `3.40` 起可用。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

revert

body

对象

`revert` 操作。

snapshot_id

body

字符串

快照的 UUID。API 将使用此快照恢复卷。

请求示例

{
    "revert": {
        "snapshot_id": "5aa119a8-d25b-45a7-8d1b-88e127885635"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

设置卷的镜像元数据

为卷设置镜像元数据。在请求正文中指定 `os-set_image_metadata` 操作。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-set_image_metadata

body

对象

`os-set_image_metadata` 操作。

metadata

body

对象

要添加到卷的镜像元数据，作为一组元数据键值对。

请求示例

{
    "os-set_image_metadata": {
        "metadata": {
            "image_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
            "image_name": "image",
            "kernel_id": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
            "ramdisk_id": "somedisk"
        }
    }
}

响应参数

名称

入参

类型

描述

metadata

body

对象

要添加到卷的镜像元数据，作为一组元数据键值对。

响应示例

{
    "metadata": {
        "kernel_id": "6ff710d2-942b-4d6b-9168-8c9cc2404ab1",
        "container_format": "bare",
        "min_ram": "0",
        "ramdisk_id": "somedisk",
        "disk_format": "qcow2",
        "image_name": "image",
        "image_id": "5137a025-3c5f-43c1-bc64-5f41270040a5",
        "checksum": "f8ab98ff5e73ebab884d80c9dc9c7290",
        "min_disk": "0",
        "size": "13267968"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

从卷中移除镜像元数据

按键移除卷的镜像元数据。在请求正文中指定 `os-unset_image_metadata` 操作，以及要移除的键值对的 `key`。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-unset_image_metadata

body

对象

`os-unset_image_metadata` 操作。此操作从镜像元数据中移除键值对。

key

body

字符串

要移除的元数据的元数据键名。

请求示例

{
    "os-unset_image_metadata": {
        "key": "ramdisk_id"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

显示卷的镜像元数据

显示卷的镜像元数据。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-show_image_metadata (可选)

body

对象

`os-show_image_metadata` 操作。

请求示例

{
    "os-show_image_metadata": {}
}

响应参数

名称

入参

类型

描述

metadata

body

对象

要添加到卷的镜像元数据，作为一组元数据键值对。

响应示例

{
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

将卷附加到服务器

将卷附加到服务器。在请求正文中指定 `os-attach` 操作。

先决条件

  • 卷状态必须是 `available`。

  • 您应该设置 `instance_uuid` 或 `host_name`。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-attach

body

对象

`os-attach` 操作。

instance_uuid (可选)

body

字符串

附加实例的 UUID。

mountpoint

body

字符串

附加挂载点。

host_name (可选)

body

字符串

附加主机的名称。

请求示例

{
    "os-attach": {
        "instance_uuid": "95D9EF50-507D-11E5-B970-0800200C9A66",
        "mountpoint": "/dev/vdc"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

将卷从服务器分离

将卷从服务器分离。在请求正文中指定 `os-detach` 操作。

先决条件

  • 卷状态必须是 `in-use`。

出于安全原因（请参阅 bug #2004555），无论策略默认值如何，如果完成请求可能构成风险，块存储 API 将以 409 状态码拒绝用户手动发出的 REST API 调用，这会在以下所有情况发生时出现：

  • 请求来自用户

  • 提供的附件或卷的附件中存在实例 UUID

  • VM 存在于 Nova 中

  • 实例已附加卷

  • 实例中的已附加卷正在使用该附件

来自其他 OpenStack 服务（如计算服务）的调用始终被接受。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-detach

body

对象

`os-detach` 操作。

attachment_id (可选)

body

字符串

附件的 ID。

请求示例

{
    "os-detach": {
        "attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

取消管理卷

将卷从块存储管理中移除，而不移除与之关联的后端存储对象。在请求正文中指定 `os-unmanage` 操作。

先决条件

  • 卷状态必须是 `available`。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-unmanage

body

对象

`os-unmanage` 操作。此操作将指定的卷从 Cinder 管理中移除。

请求示例

{
    "os-unmanage": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

强制分离卷

强制分离卷。在请求正文中指定 `os-force_detach` 操作。

回滚不成功的断开连接操作（在断开卷连接后）。

策略默认允许只有管理员角色的用户执行此操作。云提供商可以通过策略配置文件中的 `volume_extension:volume_admin_actions:force_detach` 规则更改这些权限。

出于安全原因（请参阅 bug #2004555），无论策略默认值如何，如果完成请求可能构成风险，块存储 API 将以 409 状态码拒绝用户手动发出的 REST API 调用，这会在以下所有情况发生时出现：

  • 请求来自用户

  • 提供的附件或卷的附件中存在实例 UUID

  • VM 存在于 Nova 中

  • 实例已附加卷

  • 实例中的已附加卷正在使用该附件

来自其他 OpenStack 服务（如计算服务）的调用始终被接受。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-force_detach

body

对象

`os-force_detach` 操作。

attachment_id (可选)

body

字符串

附件的 ID。

connector (可选)

body

对象

一个 `connector` 对象。

请求示例

{
    "os-force_detach": {
        "attachment_id": "d8777f54-84cf-4809-a679-468ffed56cf1",
        "connector": {
            "initiator": "iqn.2012-07.org.fake:01"
        }
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

重新类型化卷

更改现有卷的类型。在请求正文中指定 `os-retype` 操作。

更改现有卷的卷类型，Cinder 可能会根据新的卷类型将卷迁移到合适的卷主机。

不支持将 `in-use` 的、支持多重附加的卷重新类型化为不支持多重附加的类型，反之亦然。通常不建议重新类型化一个 `in-use` 的多重附加卷，如果该卷具有多个活动的读/写附件。

策略默认允许只有管理员角色的用户或卷的所有者执行此操作。云提供商可以通过策略配置文件更改这些权限。

将未加密的卷重新类型化为相同大小的加密卷很可能会失败。即使卷与源卷的大小相同，加密卷也需要存储额外的加密信息开销。这导致新卷无法容纳所有数据。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-retype

body

对象

`os-retype` 操作。

new_type

body

字符串

卷更改为的新卷类型。

migration_policy (可选)

body

字符串

指定卷在重新类型化时是否应进行迁移。可能的值为 `on-demand` 或 `never`。如果未指定，则默认为 `never`。

注意

如果卷已附加到服务器实例且将要迁移，那么默认策略是只有管理员角色的用户才能尝试重新类型化操作。不支持将 `in-use` 的加密卷重新类型化并迁移到新主机。

请求示例

{
    "os-retype": {
        "new_type": "dedup-tier-replicaton",
        "migration_policy": "never"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

迁移卷

在请求正文中指定 `os-migrate_volume` 操作。

将卷迁移到指定的节点。从 3.16 微版本 开始，可以使用集群代替节点。

通常不建议迁移一个 `in-use` 的多重附加卷，如果该卷具有多个活动的读/写附件。

策略默认允许只有管理员角色的用户执行此操作。云提供商可以通过策略配置文件更改这些权限。

先决条件

  • 卷 `status` 必须是 `available` 或 `in-use`。

  • 卷 `migration_status` 必须是 `None`、`deleting`、`error` 或 `success`。

  • 卷 `replication_status` 必须是 `None`、`disabled` 或 `not-capable`。

  • 迁移必须发生在卷当前所在的主机（或集群）之外。

  • 卷不能是组的成员。

  • 卷不能有快照。

异步后置条件

成功时，卷的 status 将恢复到其原始状态 available 或 in-use，并且 migration_status 将为 success。失败时，migration_status 将为 error。如果发生失败，并且 lock_volume 为 true，且卷在迁移时最初是 available 状态，那么 status 将恢复为 available。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

volume_id

路径

字符串

卷的 UUID。

project_id

路径

字符串

多租户云中项目的 UUID。

os-migrate_volume

body

对象

os-migrate_volume 操作。

host (可选)

body

字符串

卷迁移的目标主机。主机格式为 host@backend。3.16 微版本之前需要。

force_host_copy (可选)

body

布尔值

如果为 false（默认值），则依赖卷后端驱动程序执行迁移，这可能会经过优化。如果为 true，或者卷驱动程序无法自行迁移卷，则会执行通用的基于主机的迁移。

lock_volume (可选)

body

布尔值

如果为 true，迁移一个 available 卷会将其状态更改为 maintenance，阻止对卷执行其他操作，例如 attach、detach、retype 等。

cluster (可选)

body

字符串

卷迁移的目标集群。集群格式为 cluster@backend。从微版本 3.16 开始，必须指定 cluster 或 host。如果指定了 host 且该主机属于某个集群，则该集群将作为迁移目标。

新特性：3.16

请求示例

{
    "os-migrate_volume": {
        "host": "node1@lvm"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

完成卷的迁移

在请求体中指定 os-migrate_volume_completion 操作。

完成卷的迁移，更新数据库中的新卷，将新卷的 status 恢复到原始卷的状态，最后删除原始卷。

先决条件

  • 原始卷和新卷的 migration_status 必须为 None，或者两者都必须设置为非 None 值。

  • 此外，当设置新卷的 migration_status 时，其格式必须为 target:VOLUME_UUID，其中 VOLUME_UUID 是原始卷的 UUID。

异步后置条件

成功时，卷的 status 将恢复到其原始状态 available 或 in-use，并且 migration_status 将为 success。失败时，migration_status 将为 error。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

volume_id

路径

字符串

卷的 UUID。

project_id

路径

字符串

多租户云中项目的 UUID。

os-migrate_volume_completion

body

对象

os-migrate_volume_completion 操作。

new_volume

body

字符串

新卷的 UUID。

错误 (可选)

body

布尔值

用于指示是否发生了需要清理的其他错误。

请求示例

{
    "os-migrate_volume_completion": {
        "new_volume": "2b955850-f177-45f7-9f49-ecb2c256d161",
        "error": false
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

强制删除卷

尝试强制删除卷，无论其状态如何。在请求体中指定 os-force_delete 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-force_delete

body

字符串

os-force_delete 操作。

请求示例

{
    "os-force_delete": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

更新卷的可启动状态

更新卷的可启动状态，将其标记为可启动卷。在请求体中指定 os-set_bootable 操作。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-set_bootable

body

对象

os-set_bootable 操作。

bootable

body

布尔值

启用或禁用可启动属性。您可以从可启动卷启动实例。请参阅 有效的布尔值

请求示例

{
    "os-set_bootable": {
        "bootable": "True"
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

将卷上传到镜像

将指定卷上传到镜像服务。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-volume_upload_image

body

对象

os-volume_upload_image 操作。此操作将指定卷上传到镜像服务。

image_name

body

字符串

新镜像的名称。

force (可选)

body

布尔值

启用或禁用上传已连接到实例的卷。默认值 = False。请参阅 有效的布尔值

disk_format (可选)

body

字符串

新镜像的磁盘格式。默认为 raw。（注意：加密卷类型的卷只能以 raw 格式上传。）

container_format (可选)

body

字符串

新镜像的容器格式。默认为 bare。（注意：加密卷类型的卷必须使用 bare 容器格式。）

visibility (可选)

body

字符串

新镜像的可见性属性。默认为 private。

新特性：3.1

protected (可选)

body

布尔值

新镜像是否受保护。默认值 = False。请参阅 有效的布尔值

新特性：3.1

请求示例

{
    "os-volume_upload_image":{
        "image_name": "test",
        "force": false,
        "disk_format": "raw",
        "container_format": "bare",
        "visibility": "private",
        "protected": false
    }
}

响应参数

名称

入参

类型

描述

os-volume_upload_image

body

对象

os-volume_upload_image 操作。此操作将指定卷上传到镜像服务。

status

body

字符串

卷状态。

image_name

body

字符串

新镜像的名称。

disk_format (可选)

body

字符串

新镜像的磁盘格式。默认为 raw。

container_format (可选)

body

字符串

新镜像的容器格式。默认为 bare。

visibility (可选)

body

字符串

新镜像的可见性属性。默认为 private。

新特性：3.1

protected (可选)

body

布尔值

新镜像是否受保护。默认值 = False。请参阅 有效的布尔值

新特性：3.1

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

image_id

body

字符串

新镜像的 UUID。

display_description

body

字符串

卷描述。

id

body

字符串

卷的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

volume_type

body

字符串

卷关联的卷类型名称。

响应示例

{
    "os-volume_upload_image": {
        "container_format": "bare",
        "disk_format": "raw",
        "display_description": null,
        "id": "3a81fdac-e8ae-4e61-b6a2-2e14ff316f19",
        "image_id": "de75b74e-7f0d-4b59-a263-bd87bfc313bd",
        "image_name": "test",
        "protected": false,
        "size": 1,
        "status": "uploading",
        "updated_at": "2017-06-05T08:44:28.000000",
        "visibility": "private",
        "volume_type": null
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

预留卷

将卷标记为已预留。在请求体中指定 os-reserve 操作。

先决条件

  • 卷状态必须是 `available`。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-reserve

body

对象

os-reserve 操作。

请求示例

{
  "os-reserve": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

取消标记卷为已保留。

取消卷的预留标记。在请求体中指定 os-unreserve 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-unreserve

body

对象

os-unreserve 操作。

请求示例

{
    "os-unreserve":{}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

将卷状态更新为 detaching

将卷状态更新为 'detaching'。在请求体中指定 os-begin_detaching 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-begin_detaching

body

对象

os-begin_detaching 操作。

请求示例

{
    "os-begin_detaching": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

将卷状态回滚到 in-use

将卷状态回滚到 'in-use'。在请求体中指定 os-roll_detaching 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-roll_detaching

body

对象

os-roll_detaching 操作。

请求示例

{
   "os-roll_detaching": {}
}
POST
/v3/{project_id}/volumes/{volume_id}/action

终止卷连接

终止卷连接。在请求体中指定 os-terminate_connection 操作。

先决条件

  • 卷状态必须是 `in-use`。

出于安全原因（请参阅 bug #2004555），无论策略默认值如何，如果完成请求可能构成风险，块存储 API 将以 409 状态码拒绝用户手动发出的 REST API 调用，这会在以下所有情况发生时出现：

  • 请求来自用户

  • 卷的连接中存在实例 UUID

  • VM 存在于 Nova 中

  • 实例已附加卷

  • 实例中的已附加卷正在使用该附件

来自其他 OpenStack 服务（如计算服务）的调用始终被接受。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-terminate_connection (可选)

body

对象

os-terminate_connection 操作。

connector

body

对象

connector 对象。connector 的内部结构取决于卷驱动程序的实现。有关结构中所需元素的详细信息，请参阅卷驱动程序的文档。

请求示例

{
    "os-terminate_connection": {
        "connector": {
            "platform": "x86_64",
            "host": "node2",
            "do_local_attach": false,
            "ip": "192.168.13.101",
            "os_type": "linux2",
            "multipath": false,
            "initiator": "iqn.1994-05.com.redhat:d16cbb5d31e5"
        }
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

初始化卷连接

初始化卷连接。在请求体中指定 os-initialize_connection 操作。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-initialize_connection

body

对象

os-initialize_connection 操作。

connector

body

对象

connector 对象。connector 的内部结构取决于卷驱动程序的实现。有关结构中所需元素的详细信息，请参阅卷驱动程序的文档。

请求示例

{
    "os-initialize_connection": {
        "connector": {
            "platform":"x86_64",
            "host": "node2",
            "do_local_attach": false,
            "ip": "192.168.13.101",
            "os_type": "linux2",
            "multipath": false,
            "initiator": "iqn.1994-05.com.redhat:d16cbb5d31e5"
        }
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

更新卷的只读访问模式标志

启用或禁用将卷更新为只读访问模式。在请求体中指定 os-update_readonly_flag 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

os-update_readonly_flag

body

对象

os-update_readonly_flag 操作。此操作启用或禁用将卷更新为只读访问模式。

readonly

body

布尔值

启用或禁用只读访问模式。此值可以是 True、true、False、false。

请求示例

{
    "os-update_readonly_flag": {
        "readonly": true
    }
}
POST
/v3/{project_id}/volumes/{volume_id}/action

重新镜像卷

使用特定镜像重新镜像卷。在请求体中指定 os-reimage 操作。

状态为 available 或 error 的卷可以直接重新镜像。要重新镜像状态为 reserved 的卷，您必须包含 reimage_reserved 参数并将其设置为 true。

注意

重新镜像卷时，目前不支持镜像签名验证。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume_id

路径

字符串

卷的 UUID。

image_id

body

字符串

新镜像的 UUID。

reimage_reserved (可选)

body

布尔值

通常，要重新镜像的卷的状态为 available 或 error。当设置为 true 时，此参数允许重新镜像状态为 reserved 的卷。重新镜像 reserved 卷的能力可能在某些云中仅限于管理员。默认值为 false。

os-reimage

body

对象

os-reimage 操作。

新特性：3.68

请求示例

{
    "os-reimage": {
        "image_id": "71543ced-a8af-45b6-a5c4-a46282108a90",
        "reimage_reserved": false
    }
}

卷管理扩展 (manageable_volumes)

通过使用现有存储而不是分配新存储来创建或列出卷。

POST
/v3/{project_id}/manageable_volumes

管理现有卷

通过使用现有存储而不是分配新存储来创建块存储卷。

调用者必须在请求的 ref 参数中指定对现有存储卷的引用。尽管每个存储驱动程序可能会以不同的方式解释此引用，但驱动程序应接受一个引用结构，该结构包含 source-id 或 source-name 元素（如果可能）。

API 通过将现有存储卷的大小向上舍入到下一个 GiB 来选择卷的大小。

您不能将卷管理到加密卷类型。

在微版本 3.16 之前，host 字段是必需的，但定义集群的可能性使其不再是必需的，但我们必须有 host 或 cluster 字段，但不能同时拥有具有值的两者。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

volume

body

对象

一个 volume 对象。

description (可选)

body

字符串

卷描述。

availability_zone (可选)

body

字符串

可用区的名称。

bootable (可选)

body

布尔值

启用或禁用可启动属性。您可以从可启动卷启动实例。请参阅 有效的布尔值

volume_type (可选)

body

字符串

卷类型的名称。

name (可选)

body

字符串

卷名称。

host (可选)

body

字符串

现有资源所在的 OpenStack 块存储主机。如果提供了 cluster 字段，则此字段为可选。

cluster (可选)

body

字符串

资源所在的 OpenStack 块存储集群。如果提供了 host 字段，则此字段为可选。

ref

body

对象

对现有卷的引用。此引用的内部结构取决于卷驱动程序的实现。有关结构中所需元素的详细信息，请参阅卷驱动程序的文档。

metadata (可选)

body

对象

要与新卷关联的一个或多个元数据键值对。

请求示例

{
    "volume": {
        "host": "geraint-VirtualBox",
        "ref": {
            "source-name": "existingLV",
            "source-id": "1234"
        },
        "name": "New Volume",
        "availability_zone": "az2",
        "description": "Volume imported from existingLV",
        "volume_type": null,
        "bootable": true,
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

{
    "volume": {
        "host": null,
        "cluster": "cluster@backend",
        "ref": {
            "source-name": "existingLV",
            "source-id": "1234"
        },
        "name": "New Volume",
        "availability_zone": "az2",
        "description": "Volume imported from existingLV",
        "volume_type": null,
        "bootable": true,
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

响应

名称

入参

类型

描述

volume

body

对象

一个 volume 对象。

status

body

字符串

卷状态。

migration_status (可选)

body

字符串

卷迁移状态。仅限管理员。

user_id

body

字符串

用户的 UUID。

attachments

body

数组

实例附加信息。如果此卷已附加到服务器实例，则 `attachments` 列表将包括已附加服务器的 UUID、附件 UUID、已附加主机的名称（如果存在）、卷 UUID、设备以及设备 UUID。否则，此列表为空。例如：

[
  {
    'server_id': '6c8cf6e0-4c8f-442f-9196-9679737feec6',
    'attachment_id': '3dafcac4-1cb9-4b60-a227-d729baa10cf6',
    'attached_at': '2019-09-30T19:30:34.000000',
    'host_name': null,
    'volume_id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53',
    'device': '/dev/vda',
    'id': '5d95d5ee-4bdd-4452-b9d7-d44ca10d3d53'
  }
]

links

body

数组

卷链接。

availability_zone (可选)

body

字符串

可用区的名称。

bootable

body

字符串

启用或禁用可启动属性。您可以从可启动卷启动实例。

encrypted

body

布尔值

如果为 true，则此卷已加密。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

description (可选)

body

字符串

卷描述。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

volume_type

body

对象

一个 `volume_type` 对象。

name

body

字符串

卷名称。

replication_status

body

字符串

卷复制状态。

consistencygroup_id

body

字符串

一致性组的 UUID。

source_volid (可选)

body

字符串

源卷的 UUID。API 会创建一个与源卷大小相同的新卷，除非请求了更大的大小。

snapshot_id (可选)

body

字符串

要从现有快照创建卷，请指定卷快照的 UUID。卷将在与快照相同的可用区域中以相同大小创建。

multiattach

body

布尔值

如果为 true，则此卷可以附加到多个实例。

metadata

body

对象

一个 `metadata` 对象。包含一个或多个与卷关联的元数据键值对。

id

body

字符串

卷的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

响应示例

{
    "volume": {
        "attachments": [],
        "availability_zone": "az2",
        "bootable": "false",
        "created_at": "2014-07-18T00:12:54.000000",
        "description": "Volume imported from existingLV",
        "encrypted": "false",
        "id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
        "links": [
            {
                "href": "http://10.0.2.15:8776/v3/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "self"
            },
            {
                "href": "http://10.0.2.15:8776/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "key1": "value1",
            "key2": "value2"
        },
        "name": "New Volume",
        "os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb",
        "size": 0,
        "snapshot_id": "null",
        "source_volid": "null",
        "status": "creating",
        "user_id": "eae1472b5fc5496998a3d06550929e7e",
        "volume_type": "null"
    }
}
GET
/v3/{project_id}/manageable_volumes

列出可管理卷的摘要

搜索卷后端并列出可管理卷的摘要。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

host

路径

字符串

托管存储后端的服务器的主机名称。

响应

名称

入参

类型

描述

manageable-volumes

body

列表

可管理卷的列表。

safe_to_manage

body

布尔值

资源是否可以管理。

reference

body

对象

资源的某些信息。

source-name

body

字符串

资源的名称。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

响应示例

{
    "manageable-volumes": [
        {
            "safe_to_manage": false,
            "reference": {
                "source-name": "volume-3a81fdac-e8ae-4e61-b6a2-2e14ff316f19"
            },
            "size": 1
        },
        {
            "safe_to_manage": true,
            "reference": {
                "source-name": "lvol0"
            },
            "size": 1
        }
    ]
}
GET
/v3/{project_id}/manageable_volumes/detail

列出可管理卷的详细信息

搜索卷后端并列出可管理卷的详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

host (可选)

查询

字符串

按服务主机名过滤服务列表结果。

响应

名称

入参

类型

描述

manageable-volumes

body

列表

可管理卷的列表。

cinder_id

body

字符串

Cinder 中资源的 UUID。

safe_to_manage

body

布尔值

资源是否可以管理。

reason_not_safe

body

字符串

资源无法管理的理由。

reference

body

对象

资源的某些信息。

source-name

body

字符串

资源的名称。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

extra_info

body

字符串

有关资源的更多信息。

响应示例

{
    "manageable-volumes": [
        {
            "cinder_id": "9ba5bb53-4a18-4b38-be06-992999da338d",
            "reason_not_safe": "already managed",
            "reference": {
                "source-name": "volume-9ba5bb53-4a18-4b38-be06-992999da338d"
            },
            "safe_to_manage": false,
            "size": 1,
            "extra_info": null
        },
        {
            "cinder_id": null,
            "reason_not_safe": null,
            "reference": {
                "source-name": "lvol0"
            },
            "safe_to_manage": true,
            "size": 1,
            "extra_info": null
        }
    ]
}

卷快照 (snapshots)

快照是卷所包含数据的某个时间点的完整副本。

创建、列出或删除快照时，可能的状态值如下：

快照状态

状态

描述

creating

快照正在创建中。

available

快照已准备好使用。

backing-up

快照正在备份。

deleting

快照正在删除。

error

发生快照创建错误。

deleted

快照已删除。

unmanaging

快照正在取消管理。

恢复中

快照正在恢复为卷。

error_deleting

发生快照删除错误。
GET
/v3/{project_id}/snapshots/detail

列出快照和详细信息

列出项目可以访问的所有块存储快照及其详细信息。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回 bad request。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

with_count (可选)

查询

布尔值

是否在 API 响应中显示 `count`，默认为 `False`。

版本 3.45 新增

consumes_quota (可选)

查询

布尔值

按 `consumes_quota` 字段过滤结果。不使用配额的资源通常是用于执行操作的临时内部资源。默认不进行过滤。过滤此选项可能并非总能在云中实现，请参阅 资源过滤器 以确定此过滤器在您的云中是否可用。

版本 3.65 新增

响应参数

名称

入参

类型

描述

status

body

字符串

快照的状态。

os-extended-snapshot-attributes:progress

body

字符串

构建进度的百分比值。

description

body

字符串

快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

name (可选)

body

字符串

对象名称。

user_id

body

字符串

用户的 UUID。

新特性：3.41

volume_id

body

字符串

如果快照是从卷创建的，则为卷 ID。

os-extended-snapshot-attributes:project_id

body

字符串

所属项目的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

id

body

字符串

快照 UUID。

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

count (可选)

body

整数

应用分页之前的请求资源的 মোট 数量。

版本 3.45 新增

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

snapshots_links (可选)

body

数组

快照的链接。

group_snapshot_id

body

字符串

组快照的 ID。

新特性：3.14

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

响应示例 (v3.65)

{
    "snapshots": [
        {
            "created_at": "2019-03-11T16:24:36.464445",
            "description": "Daily backup",
            "id": "d0083dc5-8795-4c1a-bc9c-74f70006c205",
            "metadata": {
                "key": "v3"
            },
            "name": "snap-001",
            "os-extended-snapshot-attributes:progress": "0%",
            "os-extended-snapshot-attributes:project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
            "size": 10,
            "status": "creating",
            "updated_at": null,
            "volume_id": "7acd675e-4e06-4653-af9f-2ecd546342d6",
            "group_snapshot_id": null,
            "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
            "consumes_quota": true
        }
    ]
}
POST
/v3/{project_id}/snapshots

创建快照

创建卷快照，这是卷的一个时间点完整副本。您可以从快照创建卷。

在 API 版本 3.66 之前，需要 'force' 标志来创建正在使用的卷的快照，但现在不再是这样。从 API 版本 3.66 开始，当在卷快照请求中传递时，'force' 标志无效。（为保持向后兼容，评估为 True 的 'force' 标志将被静默忽略。）

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot

body

对象

一个 snapshot 对象。

volume_id

body

字符串

卷的 UUID。

name

body

字符串

快照的名称。

description (可选)

body

字符串

快照的描述。默认为 None。

force (可选)

body

布尔值

指示是否拍摄快照，即使卷已连接。默认为 false。请参阅 有效的布尔值

metadata (可选)

body

对象

快照的一个或多个元数据键值对。

请求示例

{
    "snapshot": {
        "name": "snap-001",
        "description": "Daily backup",
        "volume_id": "5aa119a8-d25b-45a7-8d1b-88e127885635",
        "force": true,
        "metadata": {
            "key": "v3"
        }
    }
}

响应参数

名称

入参

类型

描述

status

body

字符串

快照的状态。

description

body

字符串

快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

name

body

字符串

快照的名称。

snapshot

body

对象

一个 snapshot 对象。

user_id

body

字符串

用户的 UUID。

新特性：3.41

volume_id

body

字符串

如果快照是从卷创建的，则为卷 ID。

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

id

body

字符串

快照 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

group_snapshot_id

body

字符串

组快照的 ID。

新特性：3.14

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

响应示例 (v3.65)

{
    "snapshot": {
        "created_at": "2019-03-11T16:24:34.469003",
        "description": "Daily backup",
        "id": "b36476e5-d18b-47f9-ac69-4818cb43ee21",
        "metadata": {
            "key": "v3"
        },
        "name": "snap-001",
        "size": 10,
        "status": "creating",
        "updated_at": null,
        "volume_id": "d291b81c-6e40-4525-8231-90aa1588121e",
        "group_snapshot_id": null,
        "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
        "consumes_quota": true
    }
}
GET
/v3/{project_id}/snapshots

列出可访问的快照

列出项目可以访问的所有块存储快照及其摘要信息。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回 bad request。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

consumes_quota (可选)

查询

布尔值

按 `consumes_quota` 字段过滤结果。不使用配额的资源通常是用于执行操作的临时内部资源。默认不进行过滤。过滤此选项可能并非总能在云中实现，请参阅 资源过滤器 以确定此过滤器在您的云中是否可用。

版本 3.65 新增

with_count (可选)

查询

布尔值

是否在 API 响应中显示 `count`，默认为 `False`。

版本 3.45 新增

响应参数

名称

入参

类型

描述

status

body

字符串

快照的状态。

description

body

字符串

快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

name (可选)

body

字符串

对象名称。

volume_id

body

字符串

如果快照是从卷创建的，则为卷 ID。

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

id

body

字符串

快照 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

count (可选)

body

整数

应用分页之前的请求资源的 মোট 数量。

版本 3.45 新增

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

snapshots_links (可选)

body

数组

快照的链接。

响应示例

{
    "snapshots": [
        {
            "created_at": "2019-03-11T16:29:08.973832",
            "description": "Daily backup",
            "id": "2c228773-50eb-422d-be7e-b5c6ced0c7a9",
            "metadata": {
                "key": "v3"
            },
            "name": "snap-001",
            "size": 10,
            "status": "creating",
            "updated_at": null,
            "volume_id": "428ec041-b999-40d8-8a54-9e98b19406cc"
        }
    ]
}
GET
/v3/{project_id}/snapshots/{snapshot_id}/metadata

显示快照的元数据

显示快照的元数据。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

响应参数

名称

入参

类型

描述

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

响应示例

{
    "metadata": {
        "key": "v3"
    }
}
POST
/v3/{project_id}/snapshots/{snapshot_id}/metadata

创建快照的元数据

更新快照的元数据。

创建或替换匹配键的元数据项。不修改请求中未包含的项。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

请求示例

{
    "metadata": {
        "key": "v3"
    }
}

响应参数

名称

入参

类型

描述

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

响应示例

{
    "metadata": {
        "key": "value"
    }
}
PUT
/v3/{project_id}/snapshots/{snapshot_id}/metadata

更新快照的元数据

用请求中的键值对替换快照的所有元数据。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

请求示例

{
    "metadata": {
        "new_key": "new_value"
    }
}

响应参数

名称

入参

类型

描述

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

响应示例

{
    "metadata": {
        "new_key": "new_value"
    }
}
GET
/v3/{project_id}/snapshots/{snapshot_id}

显示快照的详细信息

显示快照的详情。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

响应参数

名称

入参

类型

描述

status

body

字符串

快照的状态。

os-extended-snapshot-attributes:progress

body

字符串

构建进度的百分比值。

description

body

字符串

快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

name (可选)

body

字符串

对象名称。

snapshot

body

对象

一个 snapshot 对象。

user_id

body

字符串

用户的 UUID。

新特性：3.41

volume_id

body

字符串

如果快照是从卷创建的，则为卷 ID。

os-extended-snapshot-attributes:project_id

body

字符串

所属项目的 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

id

body

字符串

快照 UUID。

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

group_snapshot_id

body

字符串

组快照的 ID。

新特性：3.14

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

响应示例 (v3.65)

{
    "snapshot": {
        "created_at": "2019-03-12T04:42:00.809352",
        "description": "Daily backup",
        "id": "4a584cae-e4ce-429b-9154-d4c9eb8fda4c",
        "metadata": {
            "key": "v3"
        },
        "name": "snap-001",
        "os-extended-snapshot-attributes:progress": "0%",
        "os-extended-snapshot-attributes:project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
        "size": 10,
        "status": "creating",
        "updated_at": null,
        "volume_id": "b72c48f1-64b7-4cd8-9745-b12e0be82d37",
        "group_snapshot_id": null,
        "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
        "consumes_quota": true
    }
}
PUT
/v3/{project_id}/snapshots/{snapshot_id}

更新快照

更新快照。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

snapshot

body

对象

一个 snapshot 对象。

description (可选)

body

字符串

快照的描述。默认为 None。

name (可选)

body

字符串

快照的名称。

请求示例

{
    "snapshot": {
        "name": "snap-002",
        "description": "This is yet, another snapshot."
    }
}

响应参数

名称

入参

类型

描述

status

body

字符串

快照的状态。

description

body

字符串

快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

name (可选)

body

字符串

对象名称。

snapshot

body

对象

一个 snapshot 对象。

id

body

字符串

快照 UUID。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

volume_id

body

字符串

如果快照是从卷创建的，则为卷 ID。

user_id

body

字符串

用户的 UUID。

新特性：3.41

metadata

body

对象

快照的一个或多个元数据键值对（如果有）。

group_snapshot_id

body

字符串

组快照的 ID。

新特性：3.14

consumes_quota (可选)

body

布尔值

此资源是否消耗配额。不计入配额使用的资源通常是为执行操作而创建的临时内部资源。

版本 3.65 新增

响应示例 (v3.65)

{
    "snapshot": {
        "created_at": "2019-03-12T04:53:53.426591",
        "description": "This is yet, another snapshot.",
        "id": "43666194-8e72-451a-b7bb-54fef763b2b8",
        "metadata": {
            "key": "v3"
        },
        "name": "snap-002",
        "size": 10,
        "status": "creating",
        "updated_at": null,
        "volume_id": "070c942d-9909-42e9-a467-7a781f150c58",
        "group_snapshot_id": null,
        "user_id": "c853ca26-e8ea-4797-8a52-ee124a013d0e",
        "consumes_quota": true
    }
}
DELETE
/v3/{project_id}/snapshots/{snapshot_id}

删除快照

删除快照。

先决条件

  • 快照状态必须为 available 或 error

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。
GET
/v3/{project_id}/snapshot/{snapshot_id}/metadata/{key}

显示特定键的快照元数据

显示特定键的快照元数据。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

key

路径

字符串

要查看的元数据的元数据键名。

响应参数

名称

入参

类型

描述

meta

body

对象

快照的元数据键值对。

响应示例

{
    "meta": {
        "key": "v3"
    }
}
DELETE
/v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}

删除快照的元数据

删除快照的元数据。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

key

路径

字符串

要移除的元数据的元数据键名。
PUT
/v3/{project_id}/snapshots/{snapshot_id}/metadata/{key}

更新特定键的快照元数据

更新特定键的快照元数据。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

key

路径

字符串

要更新的元数据的元数据键名。

meta

body

对象

快照的元数据键值对。

请求示例

{
  "meta": {
    "key": "new_value"
  }
}

响应参数

名称

入参

类型

描述

meta

body

对象

快照的元数据键值对。

响应示例

{
    "meta": {
        "key": "new_value"
    }
}

快照操作 (snapshots, action)

仅限管理员，取决于策略设置。重置、更新快照的状态。

POST
/v3/{project_id}/snapshots/{snapshot_id}/action

重置快照状态

重置状态。在请求体中指定 os-reset_status 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

os-reset_status

body

对象

`os-reset_status` 操作。

status

body

字符串

快照的状态。

请求示例

{
    "os-reset_status": {
        "status": "available"
    }
}
POST
/v3/{project_id}/snapshots/{snapshot_id}/action

更新快照状态

更新与快照状态相关的字段。在请求体中指定 os-update_snapshot_status 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

os-update_snapshot_status

body

对象

os-update_snapshot_status 操作。

status

body

字符串

快照的状态。

progress (可选)

body

字符串

快照构建进度的百分比值。

请求示例

{
    "os-update_snapshot_status": {
        "status": "creating",
        "progress": "80%"
    }
}
POST
/v3/{project_id}/snapshots/{snapshot_id}/action

强制删除快照

尝试强制删除快照，无论其状态如何。在请求体中指定 os-force_delete 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot_id

路径

字符串

快照的 UUID。

os-force_delete

body

字符串

os-force_delete 操作。

请求示例

{
    "os-force_delete": {}
}

快照管理扩展 (manageable_snapshots)

通过使用现有存储而不是分配新存储来创建或列出快照。

POST
/v3/{project_id}/manageable_snapshots

管理现有快照

通过使用现有存储而不是分配新存储来创建快照。

调用者必须在请求的 ref 参数中指定对现有存储卷的引用。尽管每个存储驱动程序可能会以不同的方式解释此引用，但驱动程序应接受一个引用结构，该结构包含 source-id 或 source-name 元素（如果可能）。

API 通过将现有快照的大小向上舍入到下一个 GiB 来选择快照的大小。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

snapshot

body

对象

一个 snapshot 对象。

description (可选)

body

字符串

快照的描述。默认为 None。

metadata (可选)

body

对象

快照的一个或多个元数据键值对。

name (可选)

body

字符串

快照的名称。默认为 None。

ref

body

对象

对现有卷的引用。此引用的内部结构取决于卷驱动程序的实现。有关结构中所需元素的详细信息，请参阅卷驱动程序的文档。

volume_id

body

字符串

卷的 UUID。

请求示例

{
    "snapshot": {
        "description": null,
        "metadata": null,
        "ref": {
            "source-name": "lvol0"
        },
        "name": null,
        "volume_id": "1df34919-aba7-4a1b-a614-3b409d71ac03"
    }
}

响应

名称

入参

类型

描述

snapshot

body

对象

一个 snapshot 对象。

status

body

字符串

快照的状态。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

metadata (可选)

body

对象

快照的一个或多个元数据键值对。

name (可选)

body

字符串

快照的名称。默认为 None。

volume_id

body

字符串

卷的 UUID。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

description

body

字符串

快照的描述。

id

body

字符串

对象的 UUID。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

响应示例

{
    "snapshot": {
        "created_at": "2018-09-26T03:45:03.893592",
        "description": "this is a new snapshot",
        "id": "b6314a71-9d3d-439a-861d-b790def0d693",
        "metadata": {
            "manage-snap-meta1": "value1",
            "manage-snap-meta2": "value2",
            "manage-snap-meta3": "value3"
        },
        "name": "new_snapshot",
        "size": 1,
        "status": "creating",
        "updated_at": "null",
        "volume_id": "1df34919-aba7-4a1b-a614-3b409d71ac03"
    }
}
GET
/v3/{project_id}/manageable_snapshots

列出可管理快照的摘要

搜索卷后端并列出可管理快照的摘要。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

host (可选)

查询

字符串

按服务主机名过滤服务列表结果。

响应

名称

入参

类型

描述

manageable-snapshots

body

列表

可管理快照的列表。

source_reference

body

对象

快照的原始卷信息。

safe_to_manage

body

布尔值

资源是否可以管理。

reference

body

对象

资源的某些信息。

source-name

body

字符串

资源的名称。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

响应示例

{
    "manageable-snapshots": [
        {
            "source_reference": {
                "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
            },
            "safe_to_manage": true,
            "reference": {
                "source-name": "lvol0"
            },
            "size": 1
        },
        {
            "source_reference": {
                "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
            },
            "safe_to_manage": false,
            "reference": {
                "source-name": "_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
            },
            "size": 1
        }
    ]
}
GET
/v3/{project_id}/manageable_snapshots/detail

列出可管理快照的详细信息

搜索卷后端并列出可管理快照的详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

host (可选)

查询

字符串

按服务主机名过滤服务列表结果。

响应

名称

入参

类型

描述

manageable-snapshots

body

列表

可管理快照的列表。

cinder_id

body

字符串

Cinder 中资源的 UUID。

source_reference

body

对象

快照的原始卷信息。

safe_to_manage

body

布尔值

资源是否可以管理。

reason_not_safe

body

字符串

资源无法管理的理由。

reference

body

对象

资源的某些信息。

source-name

body

字符串

资源的名称。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

extra_info

body

字符串

有关资源的更多信息。

响应示例

{
    "manageable-snapshots": [
        {
            "cinder_id": null,
            "reason_not_safe": null,
            "reference": {
                "source-name": "lvol0"
            },
            "source_reference": {
                "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
            },
            "safe_to_manage": true,
            "size": 1,
            "extra_info": null
        },
        {
            "cinder_id": "d0c84570-a01f-4579-9789-5e9f266587cd",
            "reason_not_safe": "already managed",
            "reference": {
                "source-name":"_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
            },
            "source_reference": {
                "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
            },
            "safe_to_manage": false,
            "size": 1,
            "extra_info": null
        }
    ]
}

卷转移

将卷从一个用户转移到另一个用户。

POST
/v3/{project_id}/os-volume-transfer/{transfer_id}/accept

接受卷转移

接受卷传输。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer_id

路径

字符串

卷转移的唯一标识符。

auth_key

body

字符串

卷转移的身份验证密钥。

请求示例

{
    "accept": {
        "auth_key": "9266c59563c84664"
    }
}

响应参数

名称

入参

类型

描述

transfer

body

对象

卷转移对象。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

卷转移的 UUID。

links

body

数组

卷迁移的链接。

name (可选)

body

字符串

对象名称。

响应示例

{
    "transfer": {
        "id": "0a840aa1-8f8f-4042-86d7-09d8ca755272",
        "links": [
            {
                "href": "http://127.0.0.1:46057/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/0a840aa1-8f8f-4042-86d7-09d8ca755272",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:46057/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/0a840aa1-8f8f-4042-86d7-09d8ca755272",
                "rel": "bookmark"
            }
        ],
        "name": "first volume",
        "volume_id": "e56dee53-e565-40f4-9c6b-b983f74a2aa5"
    }
}
POST
/v3/{project_id}/os-volume-transfer

创建卷转移

创建卷传输。

先决条件

  • 卷 status 必须为 available

  • 不支持转移加密卷

  • 如果卷有快照，则这些快照必须是 available 状态

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer

body

对象

卷转移对象。

name (可选)

body

字符串

对象名称。

volume_id

body

字符串

卷的 UUID。

请求示例

{
    "transfer": {
        "volume_id": "c86b9af4-151d-4ead-b62c-5fb967af0e37",
        "name": "first volume"
    }
}

响应参数

名称

入参

类型

描述

auth_key

body

字符串

卷转移的身份验证密钥。

links

body

数组

卷迁移的链接。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

卷转移的 UUID。

name (可选)

body

字符串

对象名称。

响应示例

{
    "transfer": {
        "auth_key": "dbccabcdbad19e07",
        "created_at": "2019-03-20T09:29:46.743632",
        "id": "3d26db0c-69cd-42e4-ae42-7552759ab361",
        "links": [
            {
                "href": "http://127.0.0.1:40345/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d26db0c-69cd-42e4-ae42-7552759ab361",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:40345/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d26db0c-69cd-42e4-ae42-7552759ab361",
                "rel": "bookmark"
            }
        ],
        "name": "first volume",
        "volume_id": "59fe2097-931b-4ceb-b74b-f862ff3b6277"
    }
}
GET
/v3/{project_id}/os-volume-transfer

列出项目的卷转移

列出卷转移。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

响应参数

名称

入参

类型

描述

volume_id

body

字符串

卷的 UUID。

id

body

字符串

卷转移的 UUID。

links

body

数组

卷迁移的链接。

name (可选)

body

字符串

对象名称。

响应示例

{
    "transfers": [
        {
            "id": "a0f13fb9-904c-41c8-8c2e-495cac61a78f",
            "links": [
                {
                    "href": "http://127.0.0.1:45017/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:45017/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
                    "rel": "bookmark"
                }
            ],
            "name": "first volume",
            "volume_id": "e72d7454-0234-4e3e-99e9-560d1ff79a71"
        }
    ]
}
GET
/v3/{project_id}/os-volume-transfer/{transfer_id}

显示卷转移详细信息

显示卷转移的详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer_id

路径

字符串

卷转移的唯一标识符。

响应参数

名称

入参

类型

描述

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

卷转移的 UUID。

links

body

数组

卷迁移的链接。

name (可选)

body

字符串

对象名称。

响应示例

{
    "transfer": {
        "created_at": "2019-03-20T09:29:48.732953",
        "id": "5055b9c2-527b-47ef-bdd6-62e1130f511f",
        "links": [
            {
                "href": "http://127.0.0.1:41845/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/5055b9c2-527b-47ef-bdd6-62e1130f511f",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:41845/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/5055b9c2-527b-47ef-bdd6-62e1130f511f",
                "rel": "bookmark"
            }
        ],
        "name": "first volume",
        "volume_id": "8cdd62be-4bea-4b7c-bb53-c0b5424ee2af"
    }
}
DELETE
/v3/{project_id}/os-volume-transfer/{transfer_id}

删除卷转移

删除卷转移。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer_id

路径

字符串

卷转移的唯一标识符。
GET
/v3/{project_id}/os-volume-transfer/detail

列出卷转移和详细信息

列出卷转移及其详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

响应参数

名称

入参

类型

描述

transfers

body

数组

转移详细信息列表。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

卷转移的 UUID。

links

body

数组

卷迁移的链接。

name (可选)

body

字符串

对象名称。

响应示例

{
    "transfers": [
        {
            "created_at": "2019-03-20T09:29:52.758407",
            "id": "1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
            "links": [
                {
                    "href": "http://127.0.0.1:37479/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:37479/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
                    "rel": "bookmark"
                }
            ],
            "name": "first volume",
            "volume_id": "acb5a860-3f17-4c35-9484-394a12dd7dfc"
        }
    ]
}

卷转移 (volume-transfers) (3.55 或更高版本)

将卷从一个用户转移到另一个用户。这是微版本 3.55 的新转移 API。

POST
/v3/{project_id}/volume-transfers/{transfer_id}/accept

接受卷转移

接受卷传输。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
413 - 请求实体过大

无法完成此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer_id

路径

字符串

卷转移的唯一标识符。

auth_key

body

字符串

卷转移的身份验证密钥。

请求示例

{
    "accept": {
        "auth_key": "f318375a4400391e"
    }
}

响应参数

名称

入参

类型

描述

transfer

body

对象

卷转移对象。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

对象的 UUID。

links

body

数组

卷迁移的链接。

name

body

字符串

卷转移的名称。

响应示例

{
    "transfer": {
        "id": "9e395d6d-5138-423c-a63c-7b62c6265fa1",
        "links": [
            {
                "href": "http://127.0.0.1:39369/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/9e395d6d-5138-423c-a63c-7b62c6265fa1",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:39369/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/9e395d6d-5138-423c-a63c-7b62c6265fa1",
                "rel": "bookmark"
            }
        ],
        "name": "first volume",
        "volume_id": "8d19f929-f1da-4a76-acad-9ed17da0981e"
    }
}
POST
/v3/{project_id}/volume-transfers

创建卷转移

创建卷传输。

先决条件

  • 卷 status 必须为 available

  • 不支持转移加密卷

  • 如果卷有快照，则除非 no_snapshots=True，否则这些快照必须是 available 状态。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer

body

对象

卷转移对象。

name (可选)

body

字符串

对象名称。

volume_id

body

字符串

卷的 UUID。

no_snapshots (可选)

body

布尔值

不带快照转移卷。如果未指定，则默认为 False。

新特性：3.55

请求示例

{
    "transfer": {
        "volume_id": "80d68197-b67e-4c8e-bbb9-030b2581f921",
        "name": "first volume",
        "no_snapshots": false
    }
}

响应参数

名称

入参

类型

描述

auth_key

body

字符串

卷转移的身份验证密钥。

links

body

数组

卷迁移的链接。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

对象的 UUID。

name (可选)

body

字符串

对象名称。

destination_project_id (可选)

body

字符串

记录卷转移后的目标项目 ID。

新特性：3.57

source_project_id (可选)

body

字符串

记录卷转移前的源项目 ID。

新特性：3.57

accepted (可选)

body

布尔值

记录此转移是否已被接受。

新特性：3.57

no_snapshots (可选)

body

布尔值

不带快照转移卷。如果未指定，则默认为 False。

新特性：3.55

响应示例

{
    "transfer": {
        "accepted": false,
        "auth_key": "e2cb02466324813c",
        "created_at": "2023-06-12T21:21:38.392033",
        "destination_project_id": null,
        "id": "94bae1a0-83fb-496c-9cd2-800d8237ab0d",
        "links": [
            {
                "href": "http://127.0.0.1:45193/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/94bae1a0-83fb-496c-9cd2-800d8237ab0d",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:45193/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/94bae1a0-83fb-496c-9cd2-800d8237ab0d",
                "rel": "bookmark"
            }
        ],
        "name": "first volume",
        "no_snapshots": false,
        "source_project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
        "volume_id": "202eead8-3c82-41e1-914f-83638a063be9"
    }
}
GET
/v3/{project_id}/volume-transfers

列出项目的卷转移

列出卷转移。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

新特性：3.59

sort_key (可选)

查询

字符串

按属性排序。默认为 created_at。API 使用 sort_key 属性值的自然排序方向。已弃用，改用组合的 sort 参数。

新特性：3.59

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

新特性：3.59

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

新特性：3.59

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

新特性：3.59

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

新特性：3.59

响应参数

名称

入参

类型

描述

volume_id

body

字符串

卷的 UUID。

id

body

字符串

对象的 UUID。

links

body

数组

卷迁移的链接。

name (可选)

body

字符串

对象名称。

响应示例

{
    "transfers": [
        {
            "id": "a0f13fb9-904c-41c8-8c2e-495cac61a78f",
            "links": [
                {
                    "href": "http://127.0.0.1:45017/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:45017/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/a0f13fb9-904c-41c8-8c2e-495cac61a78f",
                    "rel": "bookmark"
                }
            ],
            "name": "first volume",
            "volume_id": "e72d7454-0234-4e3e-99e9-560d1ff79a71"
        }
    ]
}
GET
/v3/{project_id}/volume-transfers/{transfer_id}

显示卷转移详细信息

显示卷转移的详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer_id

路径

字符串

卷转移的唯一标识符。

响应参数

名称

入参

类型

描述

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

对象的 UUID。

links

body

数组

卷迁移的链接。

name (可选)

body

字符串

对象名称。

destination_project_id (可选)

body

字符串

记录卷转移后的目标项目 ID。

新特性：3.57

source_project_id (可选)

body

字符串

记录卷转移前的源项目 ID。

新特性：3.57

accepted (可选)

body

布尔值

记录此转移是否已被接受。

新特性：3.57

no_snapshots (可选)

body

布尔值

不带快照转移卷。如果未指定，则默认为 False。

新特性：3.55

响应示例

{
    "transfer": {
        "accepted": false,
        "created_at": "2023-06-22T08:28:17.647081",
        "destination_project_id": null,
        "id": "3d79fbda-8d9c-4da3-a016-e5612fcb7f65",
        "links": [
            {
                "href": "http://127.0.0.1:34593/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d79fbda-8d9c-4da3-a016-e5612fcb7f65",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:34593/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/3d79fbda-8d9c-4da3-a016-e5612fcb7f65",
                "rel": "bookmark"
            }
        ],
        "name": "first volume",
        "no_snapshots": false,
        "source_project_id": "89afd400-b646-4bbc-b12b-c0a4d63e5bd3",
        "volume_id": "7e31e409-2a7a-4ea6-aa0b-bc7be056fc57"
    }
}
DELETE
/v3/{project_id}/volume-transfers/{transfer_id}

删除卷转移

删除卷转移。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

transfer_id

路径

字符串

卷转移的唯一标识符。
GET
/v3/{project_id}/volume-transfers/detail

列出卷转移和详细信息

列出卷转移及其详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

响应参数

名称

入参

类型

描述

transfers

body

数组

转移详细信息列表。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_id

body

字符串

卷的 UUID。

id

body

字符串

对象的 UUID。

links

body

数组

卷迁移的链接。

name (可选)

body

字符串

对象名称。

destination_project_id (可选)

body

字符串

记录卷转移后的目标项目 ID。

新特性：3.57

source_project_id (可选)

body

字符串

记录卷转移前的源项目 ID。

新特性：3.57

accepted (可选)

body

布尔值

记录此转移是否已被接受。

新特性：3.57

响应示例

{
    "transfers": [
        {
            "created_at": "2019-03-20T09:29:52.758407",
            "id": "1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
            "links": [
                {
                    "href": "http://127.0.0.1:37479/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:37479/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/os-volume-transfer/1b3f7d49-8fd8-41b8-b2a5-859c5fe71a20",
                    "rel": "bookmark"
                }
            ],
            "name": "first volume",
            "volume_id": "acb5a860-3f17-4c35-9484-394a12dd7dfc"
        }
    ]
}

附件 (attachments)

列出所有附件、列出所有附件（含详细信息）、显示附件详细信息、创建附件和删除附件。

注意

除了“完成附件”之外的所有内容在 3.27 微版本中都是新的。“完成附件”在 3.44 微版本中是新的。

创建、列出、更新或删除附件时，可能的状态值如下：

卷附件状态

状态

描述

attached

附件的卷已连接。

attaching

附件的卷正在连接。

detached

附件的卷已断开连接。

reserved

附件的卷已预留。

error_attaching

附件的卷正在错误地连接。

error_detaching

附件的卷正在错误地断开连接。

deleted

附件已删除。
DELETE
/v3/{project_id}/attachments/{attachment_id}

删除附件

删除附件。

出于安全原因（请参阅 bug #2004555），块存储 API 会拒绝用户手动发起的 REST API 调用，并返回 409 状态码，如果当前有 Nova 实例正在使用该附件，则会发生这种情况，即满足所有以下条件时：

  • 附件包含实例 UUID

  • VM 存在于 Nova 中

  • 实例已附加卷

  • 实例中的已附加卷正在使用该附件

来自其他 OpenStack 服务（如计算服务）的调用始终被接受。

从 3.27 微版本开始可用。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

attachment_id

路径

字符串

附件的 ID。
GET
/v3/{project_id}/attachments/{attachment_id}

显示附件详细信息

显示附件的详细信息。

从 3.27 微版本开始可用。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

attachment_id

路径

字符串

附件的 ID。

响应参数

名称

入参

类型

描述

status

body

字符串

附件的状态。

detached_at

body

字符串

附件断开连接的时间。

connection_info

body

对象

服务器用于连接卷的连接信息。

attached_at

body

字符串

附件连接的时间。

attach_mode

body

字符串

附件的连接模式，只读 ('ro') 或读写 ('rw')，默认为 'rw'。

实例

body

字符串

附加实例的 UUID。

volume_id

body

字符串

附件所属卷的 UUID。

id

body

字符串

附件 ID。

响应示例

{
    "attachment": {
        "status": "attaching",
        "detached_at": "2015-09-16T09:28:52.000000",
        "connection_info": {},
        "attached_at": "2015-09-16T09:28:52.000000",
        "attach_mode": "ro",
        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
    }
}
GET
/v3/{project_id}/attachments/detail

列出带详细信息的附件

列出所有带详细信息的附件。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回 bad request。

从 3.27 微版本开始可用。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

status

body

字符串

附件的状态。

detached_at

body

字符串

附件断开连接的时间。

connection_info

body

对象

服务器用于连接卷的连接信息。

attached_at

body

字符串

附件连接的时间。

attach_mode

body

字符串

附件的连接模式，只读 ('ro') 或读写 ('rw')，默认为 'rw'。

实例

body

字符串

附加实例的 UUID。

volume_id

body

字符串

附件所属卷的 UUID。

id

body

字符串

附件 ID。

响应示例

{
    "attachments": [
        {
            "status": "attaching",
            "detached_at": "2015-09-16T09:28:52.000000",
            "connection_info": {},
            "attached_at": "2015-09-16T09:28:52.000000",
            "attach_mode": "ro",
            "instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
            "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
            "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
        }
    ]
}
GET
/v3/{project_id}/attachments

列出附件

列出所有附件。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回 bad request。

从 3.27 微版本开始可用。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

instance_id (可选)

查询

字符串

附加实例的 UUID。

volume_id (可选)

查询

字符串

附件所属卷的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

status

body

字符串

附件的状态。

实例

body

字符串

附加实例的 UUID。

volume_id

body

字符串

附件所属卷的 UUID。

id

body

字符串

附件 ID。

响应示例

{
    "attachments": [
        {
            "status": "attaching",
            "instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
            "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c",
            "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
        }
    ]
}
POST
/v3/{project_id}/attachments

创建附件

创建附件。

从 3.27 微版本开始可用。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

attachment

body

对象

附件对象。

instance_uuid (可选)

body

字符串

附加实例的 UUID。

connector (可选)

body

对象

一个 `connector` 对象。

volume_uuid

body

字符串

附件所属卷的 UUID。

mode (可选)

body

字符串

附件的连接模式，可接受值为只读 ('ro') 和读写 ('rw')。

新特性：3.54

请求示例

{
    "attachment": {
        "instance_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "connector": {
            "initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
            "ip": "192.168.1.20",
            "platform": "x86_64",
            "host": "tempest-1",
            "os_type": "linux2",
            "multipath": false,
            "mountpoint": "/dev/vdb",
            "mode": "ro"
        },
        "volume_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
    }
}

响应参数

名称

入参

类型

描述

attachment

body

对象

附件对象。

status

body

字符串

附件的状态。

detached_at

body

字符串

附件断开连接的时间。

connection_info

body

对象

服务器用于连接卷的连接信息。

attached_at

body

字符串

附件连接的时间。

attach_mode

body

字符串

附件的连接模式，只读 ('ro') 或读写 ('rw')，默认为 'rw'。

实例

body

字符串

附加实例的 UUID。

volume_id

body

字符串

附件所属卷的 UUID。

id

body

字符串

附件 ID。

响应示例

{
    "attachment": {
        "status": "attaching",
        "detached_at": "2015-09-16T09:28:52.000000",
        "connection_info": {},
        "attached_at": "2015-09-16T09:28:52.000000",
        "attach_mode": "ro",
        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
    }
}
PUT
/v3/{project_id}/attachments/{attachment_id}

更新附件

使用连接器信息更新已预留的附件记录，并设置驱动程序的相应 connection_info。

从 3.27 微版本开始可用。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

attachment_id

路径

字符串

附件的 ID。

attachement

body

对象

附件对象。

connector

body

对象

connector 对象。connector 的内部结构取决于卷驱动程序的实现。有关结构中所需元素的详细信息，请参阅卷驱动程序的文档。

请求示例

{
    "attachment": {
        "connector": {
            "initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
            "ip": "192.168.1.20",
            "platform": "x86_64",
            "host": "tempest-1",
            "os_type": "linux2",
            "multipath": false,
            "mountpoint": "/dev/vdb",
            "mode": "ro"
        }
    }
}

响应参数

名称

入参

类型

描述

attachment

body

对象

附件对象。

status

body

字符串

附件的状态。

detached_at

body

字符串

附件断开连接的时间。

connection_info

body

对象

服务器用于连接卷的连接信息。

attached_at

body

字符串

附件连接的时间。

attach_mode

body

字符串

附件的连接模式，只读 ('ro') 或读写 ('rw')，默认为 'rw'。

实例

body

字符串

附加实例的 UUID。

volume_id

body

字符串

附件所属卷的 UUID。

id

body

字符串

附件 ID。

响应示例

{
    "attachment": {
        "status": "attaching",
        "detached_at": "2015-09-16T09:28:52.000000",
        "connection_info": {},
        "attached_at": "2015-09-16T09:28:52.000000",
        "attach_mode": "ro",
        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
    }
}
POST
/v3/{project_id}/attachments/{attachment_id}/action

完成附件

完成 Cinder 卷的附件。

从 3.44 微版本开始可用。

响应代码

成功

代码

原因
204 - No Content

请求已满足，但服务未返回任何内容。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

attachment_id

路径

字符串

附件的 ID。

请求示例

{
    "os-complete": {}
}

可用区 (os-availability-zone)

列出可用性区域信息。

GET
/v3/{project_id}/os-availability-zone

列出可用性区域信息

列出可用性区域信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

响应参数

名称

入参

类型

描述

project_id

body

字符串

项目的 UUID。

availabilityZoneInfo

body

数组

可用区信息列表。

zoneName

body

字符串

可用区名称。

zoneState

body

对象

可用区的当前状态。

available

body

布尔值

可用性区域是否可供使用。

响应示例

{
    "availabilityZoneInfo": [{
        "zoneState": {
            "available": true
        },
    "zoneName": "nova"
    }]
}

后端存储池

仅限管理员。列出调度程序服务已知的​​所有后端存储池。

GET
/v3/{project_id}/scheduler-stats/get_pools

列出所有后端存储池

列出所有后端存储池。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回 bad request。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

detail (可选)

查询

布尔值

指示是在响应中显示池的详细信息还是仅显示池名称。设置为 true 以显示池的详细信息。设置为 false 以仅显示池名称。默认为 false。

响应参数

名称

入参

类型

描述

pools

body

数组

存储池列表。

updated

body

字符串

扩展上次更新的日期和时间戳。

QoS_support

body

布尔值

服务质量 (QoS) 支持。

name

body

字符串

后端池的名称。

total_capacity_gb

body

字符串

后端卷的总容量（GB）。有效值为字符串，例如 unknown，或数字（整数或浮点数）。

volume_backend_name

body

字符串

后端卷的名称。

capabilities

body

对象

后端的容量。值为 null 或表示每个池容量的字符串值。例如，total_capacity_gb 或 QoS_support。

free_capacity_gb

body

字符串

后端卷的可用容量（GB）。有效值为字符串，例如 unknown，或数字（整数或浮点数）。

driver_version

body

字符串

驱动程序版本。

reserved_percentage

body

整数

后端内部使用保留的总容量的百分比。

storage_protocol

body

字符串

后端卷的存储后端。例如，iSCSI 或 FC。

响应示例

{
    "pools": [
        {
            "name": "pool1",
            "capabilities": {
                "updated": "2014-10-28T00:00:00-00:00",
                "total_capacity_gb": 1024,
                "free_capacity_gb": 100,
                "volume_backend_name": "pool1",
                "reserved_percentage": 0,
                "driver_version": "1.0.0",
                "storage_protocol": "iSCSI",
                "QoS_support": false
            }
        },
        {
            "name": "pool2",
            "capabilities": {
                "updated": "2014-10-28T00:00:00-00:00",
                "total_capacity_gb": 512,
                "free_capacity_gb": 200,
                "volume_backend_name": "pool2",
                "reserved_percentage": 0,
                "driver_version": "1.0.1",
                "storage_protocol": "iSER",
                "QoS_support": true
            }
        }
    ]
}

备份 (backups)

备份是存储在外部服务中的卷的完整副本。该服务可以配置。唯一支持的服务是对象存储。之后可以将备份从外部服务恢复到原始备份所在的同一个卷，或恢复到一个新卷。

创建、列出或删除备份时，可能的状态值如下：

备份状态

状态

描述

creating

备份正在创建中。

available

备份已准备好恢复为卷。

deleting

备份正在删除。

error

发生备份错误。

恢复中

备份正在恢复为卷。

error_deleting

删除备份时发生错误。

如果发生错误，您可以在备份的 fail_reason 字段中找到有关错误的更多信息。

GET
/v3/{project_id}/backups/detail

列出带详细信息的备份

列出项目可以访问的块存储备份及其详细信息。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回 bad request。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

with_count (可选)

查询

布尔值

是否在 API 响应中显示 `count`，默认为 `False`。

版本 3.45 新增

响应参数

名称

入参

类型

描述

backups

body

数组

一个 backup 对象列表。

status

body

字符串

备份状态。有关可能的返回值，请参阅备份状态表。

object_count

body

整数

备份中的对象数量。

fail_reason

body

字符串

如果备份失败，则为失败原因。否则为 null。

description (可选)

body

字符串

备份描述或 null。

links

body

数组

备份的链接。

availability_zone (可选)

body

字符串

可用区的名称。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

name

body

字符串

备份名称。

has_dependent_backups (可选)

body

布尔值

如果此值为 true，则有其他备份依赖于此备份。

volume_id

body

字符串

卷的 UUID。

container (可选)

body

字符串

容器名称或 null。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

id

body

字符串

备份的 UUID。

is_incremental (可选)

body

布尔值

指示备份模式是否为增量。如果此值为 true，则备份模式为增量。如果此值为 false，则备份模式为完整。

data_timestamp

body

字符串

数据在卷上保存的首次时间。如果是从卷进行的备份，则与备份的 created_at 相同。如果是从快照进行的备份，则与快照的 created_at 相同。

snapshot_id (可选)

body

字符串

源卷快照的 UUID。

os-backup-project-attr:project_id

body

字符串

所属项目的 UUID。

新特性：3.18

count (可选)

body

整数

应用分页之前的请求资源的 মোট 数量。

版本 3.45 新增

metadata (可选)

body

对象

备份元数据键值对。

新特性：3.43

user_id

body

字符串

所有者项目的 UUID。

新特性：3.56

encryption_key_id (可选)

body

字符串

加密密钥的 UUID。仅对加密卷包含。

版本 3.64 新增

backup_links (可选)

body

数组

一个数组，包含一个对象，该对象具有 "rel" 字段（值为 "next"）和 href 字段，其值指向下一页备份的链接。仅当备份数超过当前响应中列出的数量时出现。

响应示例

{
    "backups": [
        {
            "availability_zone": null,
            "container": null,
            "created_at": "2023-07-10T13:23:21.178739",
            "data_timestamp": "2023-07-10T13:23:21.178739",
            "description": "Test backup",
            "fail_reason": null,
            "has_dependent_backups": false,
            "id": "7ab823f7-1174-4447-9a76-863ae2dcf372",
            "is_incremental": false,
            "links": [
                {
                    "href": "http://127.0.0.1:44197/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/7ab823f7-1174-4447-9a76-863ae2dcf372",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:44197/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/7ab823f7-1174-4447-9a76-863ae2dcf372",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001",
            "object_count": 0,
            "size": 10,
            "snapshot_id": null,
            "status": "creating",
            "updated_at": "2023-07-10T13:23:21.189552",
            "volume_id": "9fc31617-303d-4b52-826e-b598cca40419"
        }
    ]
}
GET
/v3/{project_id}/backups/{backup_id}

显示备份详细信息

显示备份的详细信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup_id

路径

字符串

备份的 UUID。

响应参数

名称

入参

类型

描述

备份中

body

对象

一个 backup 对象。

status

body

字符串

备份状态。有关可能的返回值，请参阅备份状态表。

object_count

body

整数

备份中的对象数量。

container (可选)

body

字符串

容器名称或 null。

description (可选)

body

字符串

备份描述或 null。

links

body

数组

备份的链接。

availability_zone (可选)

body

字符串

可用区的名称。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

name

body

字符串

备份名称。

has_dependent_backups (可选)

body

布尔值

如果此值为 true，则有其他备份依赖于此备份。

volume_id

body

字符串

卷的 UUID。

fail_reason

body

字符串

如果备份失败，则为失败原因。否则为 null。

size

body

整数

卷的大小，以 gibibytes (GiB) 为单位。

备份中

body

对象

一个 backup 对象。

id

body

字符串

备份的 UUID。

is_incremental (可选)

body

布尔值

指示备份模式是否为增量。如果此值为 true，则备份模式为增量。如果此值为 false，则备份模式为完整。

data_timestamp

body

字符串

数据在卷上保存的首次时间。如果是从卷进行的备份，则与备份的 created_at 相同。如果是从快照进行的备份，则与快照的 created_at 相同。

snapshot_id (可选)

body

字符串

源卷快照的 UUID。

os-backup-project-attr:project_id

body

字符串

所属项目的 UUID。

新特性：3.18

metadata (可选)

body

对象

备份元数据键值对。

新特性：3.43

user_id

body

字符串

所有者项目的 UUID。

新特性：3.56

encryption_key_id (可选)

body

字符串

加密密钥的 UUID。仅对加密卷包含。

版本 3.64 新增

响应示例

{
    "backup": {
        "availability_zone": null,
        "container": null,
        "created_at": "2023-06-23T11:56:02.509831",
        "data_timestamp": "2023-06-23T11:56:02.509831",
        "description": "Test backup",
        "fail_reason": null,
        "has_dependent_backups": false,
        "id": "6a122f4b-d2f6-448f-aeb5-68bae5ff8358",
        "is_incremental": false,
        "links": [
            {
                "href": "http://127.0.0.1:46627/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/6a122f4b-d2f6-448f-aeb5-68bae5ff8358",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:46627/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/6a122f4b-d2f6-448f-aeb5-68bae5ff8358",
                "rel": "bookmark"
            }
        ],
        "name": "backup001",
        "object_count": 0,
        "size": 10,
        "snapshot_id": null,
        "status": "creating",
        "updated_at": "2023-06-23T11:56:02.512426",
        "volume_id": "49a784cf-b759-4594-acdf-5238ee50976b"
    }
}
DELETE
/v3/{project_id}/backups/{backup_id}

删除备份

删除备份。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup_id

路径

字符串

备份的 UUID。
POST
/v3/{project_id}/backups/{backup_id}/restore

恢复备份

将块存储备份恢复到现有或新的块存储卷。

name 参数仅在新卷创建时有效。

如果指定了 UUID，则备份将恢复到指定的卷。指定的卷有以下要求：

  • 指定的卷状态为 available。

  • 指定卷的大小必须等于或大于备份的大小。

如果未提供现有的卷 UUID，备份将恢复到一个大小和名称与原始备份卷匹配的新卷。在这种情况下，如果提供了 name 参数，它将用作新卷的名称。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
413 - 请求实体过大

无法完成此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup_id

路径

字符串

备份的 UUID。

restore

body

对象

一个 restore 对象。

name (可选)

body

字符串

卷名称。

volume_id (可选)

body

字符串

您要将备份恢复到的卷的 UUID。

请求示例

{
    "restore": {
        "name": "vol-01",
        "volume_id": "64f5d2fb-d836-4063-b7e2-544d5c1ff607"
    }
}

响应参数

名称

入参

类型

描述

restore

body

对象

一个 restore 对象。

backup_id

路径

字符串

备份的 UUID。

volume_id

body

字符串

卷的 UUID。

volume_name

body

字符串

卷名称。

响应示例

{
    "restore": {
        "backup_id": "2ef47aee-8844-490c-804d-2a8efe561c65",
        "volume_id": "795114e8-7489-40be-a978-83797f2c1dd3",
        "volume_name": "volume01"
    }
}
POST
/v3/{project_id}/backups

创建备份

从卷或快照创建块存储备份。

卷的状态必须为 available，或者如果使用了 force 标志，则也可以创建 in-use 卷的备份。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

备份中

body

对象

一个 backup 对象。

volume_id

body

字符串

您要备份的卷的 UUID。

container (可选)

body

字符串

容器名称或 null。

description (可选)

body

字符串

备份描述或 null。

incremental (可选)

body

布尔值

备份模式。有效值为增量备份模式的 true 或完整备份模式的 false。默认为 false。请参阅 有效的布尔值

force (可选)

body

布尔值

指示是否备份，即使卷已连接。默认为 false。请参阅 有效的布尔值

name (可选)

body

字符串

卷备份的名称。

snapshot_id (可选)

body

字符串

您要备份的源快照的 UUID。

metadata (可选)

body

对象

备份元数据键值对。

新特性：3.43

availability_zone (可选)

body

字符串

备份可用性区域键值对。

新特性：3.51

请求示例

{
    "backup": {
        "container": null,
        "description": "Test backup",
        "name": "backup001",
        "volume_id": "0aa67a0c-7339-4be6-b5d5-2afe21ca270c",
        "incremental": false,
        "snapshot_id": null,
        "force": false
    }
}

响应参数

名称

入参

类型

描述

备份中

body

对象

一个 backup 对象。

id

body

字符串

备份的 UUID。

links

body

数组

备份的链接。

name

body

字符串

备份名称。

metadata (可选)

body

对象

备份元数据键值对。

新特性：3.43

响应示例

{
    "backup": {
        "id": "b1f41f9b-741e-4992-a246-b97de7e6e87e",
        "links": [
            {
                "href": "http://127.0.0.1:40797/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/b1f41f9b-741e-4992-a246-b97de7e6e87e",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:40797/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/b1f41f9b-741e-4992-a246-b97de7e6e87e",
                "rel": "bookmark"
            }
        ],
        "name": "backup001"
    }
}
PUT
/v3/{project_id}/backups/{backup_id}

更新备份

更新块存储备份。此 API 自 v3.9 起可用。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup_id

路径

字符串

备份的 UUID。

备份中

body

对象

一个 backup 对象。

description (可选)

body

字符串

备份描述或 null。

name (可选)

body

字符串

卷备份的名称。

metadata (可选)

body

对象

备份元数据键值对。

新特性：3.43

请求示例

{
    "backup":{
        "name":"backup001",
        "description": "this is a backup"
    }
}

响应参数

名称

入参

类型

描述

备份中

body

对象

一个 backup 对象。

id

body

字符串

备份的 UUID。

links

body

数组

备份的链接。

name

body

字符串

备份名称。

metadata (可选)

body

对象

备份元数据键值对。

新特性：3.43

响应示例

{
    "backup": {
        "id": "06d5db4f-1f80-4a71-99a6-99368cfb8f8e",
        "links": [
            {
                "href": "http://127.0.0.1:45187/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/06d5db4f-1f80-4a71-99a6-99368cfb8f8e",
                "rel": "self"
            },
            {
                "href": "http://127.0.0.1:45187/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/06d5db4f-1f80-4a71-99a6-99368cfb8f8e",
                "rel": "bookmark"
            }
        ],
        "name": "backup001"
    }
}
GET
/v3/{project_id}/backups

列出项目的备份

列出项目可以访问的块存储备份。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回 bad request。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

with_count (可选)

查询

布尔值

是否在 API 响应中显示 `count`，默认为 `False`。

版本 3.45 新增

响应参数

名称

入参

类型

描述

backups

body

数组

一个 backup 对象列表。

id

body

字符串

备份的 UUID。

links

body

数组

备份的链接。

name

body

字符串

备份名称。

count (可选)

body

整数

应用分页之前的请求资源的 মোট 数量。

版本 3.45 新增

backup_links (可选)

body

数组

一个数组，包含一个对象，该对象具有 "rel" 字段（值为 "next"）和 href 字段，其值指向下一页备份的链接。仅当备份数超过当前响应中列出的数量时出现。

响应示例

{
    "backups": [
        {
            "id": "c26d9897-cace-44cc-ad0f-3a0d0b6d1450",
            "links": [
                {
                    "href": "http://127.0.0.1:46803/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/c26d9897-cace-44cc-ad0f-3a0d0b6d1450",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:46803/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/backups/c26d9897-cace-44cc-ad0f-3a0d0b6d1450",
                    "rel": "bookmark"
                }
            ],
            "name": "backup001"
        }
    ]
}
GET
/v3/{project_id}/backups/{backup_id}/export_record

导出备份

导出备份信息。

响应代码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup_id

路径

字符串

备份的 UUID。

响应参数

名称

入参

类型

描述

backup-record

body

对象

一个记录卷备份元数据的对象，包括 backup_service 和 backup_url。

backup_service

body

字符串

执行备份使用的服务。

backup_url

body

字符串

用于定位备份的标识符字符串。

响应示例

{
    "backup-record": {
        "backup_service": "cinder.backup.drivers.swift",
        "backup_url": "eyJzdGF0"
    }
}
POST
/v3/{project_id}/backups/import_record

导入备份

导入备份信息。

响应代码

成功

代码

原因
201 - 已创建

请求已完成，并创建了新资源。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
503 - 服务不可用

服务现在无法处理请求。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup-record

body

对象

一个记录卷备份元数据的对象，包括 backup_service 和 backup_url。

backup_service

body

字符串

执行备份使用的服务。

backup_url

body

字符串

用于定位备份的标识符字符串。

请求示例

{
    "backup-record": {
        "backup_service": "cinder.backup.drivers.swift",
        "backup_url": "eyJzdGF0"
    }
}

响应参数

名称

入参

类型

描述

id

body

字符串

备份的 UUID。

links

body

数组

备份的链接。

name

body

字符串

备份名称。

响应示例

{
    "backup": {
        "id": "deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
        "links": [
            {
                "href": "https://:8776/v3/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "self"
            },
            {
                "href": "https://:8776/c95fc3e4afe248a49a28828f286a7b38/backups/deac8b8c-35c9-4c71-acaa-889c2d5d5c8e",
                "rel": "bookmark"
            }
        ],
        "name": null
    }
}

备份操作 (backups, action)

强制删除备份并重置备份的状态。

POST
/v3/{project_id}/backups/{backup_id}/action

强制删除备份

强制删除备份。在请求体中指定 os-force_delete 操作。

此操作会删除备份及其所有备份数据。

如果备份驱动程序不支持此操作，则返回 405 状态码。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
404 - Not Found

找不到请求的资源。
405 - 方法不允许

该方法对于此端点和资源无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup_id

路径

字符串

备份的 UUID。

os-force_delete

body

字符串

os-force_delete 操作。

请求示例

{
    "os-force_delete": {}
}
POST
/v3/{project_id}/backups/{backup_id}/action

重置备份状态

重置备份状态。在请求体中指定 os-reset_status 操作。

响应代码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

backup_id

路径

字符串

备份的 UUID。

os-reset_status

body

对象

`os-reset_status` 操作。

status

body

字符串

备份的状态。

请求示例

{
    "os-reset_status": {
        "status": "available"
    }
}

存储后端功能 (capabilities)

显示存储后端的​​功能。

GET
/v3/{project_id}/capabilities/{hostname}

显示所有后端功能

显示主机上存储后端的​​功能。hostname 的格式为 hostname@volume_backend_name。

响应代码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

hostname

路径

字符串

托管存储后端的服务器的主机名称。

响应参数

名称

入参

类型

描述

pool_name

body

字符串

存储池的名称。

description

body

字符串

功能描述。

volume_backend_name

body

字符串

后端卷的名称。

namespace

body

字符串

存储命名空间，例如 OS::Storage::Capabilities::foo。

visibility

body

字符串

卷类型访问权限。

driver_version

body

字符串

驱动程序版本。

vendor_name

body

字符串

供应商名称。

properties

body

对象

后端卷功能列表，由 Cinder 标准功能和供应商特定属性组成。

storage_protocol

body

字符串

后端卷的存储后端。例如，iSCSI 或 FC。

replication_targets

body

列表

用于在此后端上复制卷的卷后端列表。

display_name

body

字符串

卷后端功能名称。

响应示例

{
    "namespace": "OS::Storage::Capabilities::fake",
    "vendor_name": "OpenStack",
    "volume_backend_name": "lvmdriver-1",
    "pool_name": "pool",
    "driver_version": "2.0.0",
    "storage_protocol": "iSCSI",
    "display_name": "Capabilities of Cinder LVM driver",
    "description": "These are volume type options provided by Cinder LVM driver, blah, blah.",
    "visibility": "public",
    "replication_targets": [],
    "properties": {
        "compression": {
            "title": "Compression",
            "description": "Enables compression.",
            "type": "boolean"
        },
        "qos": {
            "title": "QoS",
            "description": "Enables QoS.",
            "type": "boolean"
        },
        "replication": {
            "title": "Replication",
            "description": "Enables replication.",
            "type": "boolean"
        },
        "thin_provisioning": {
            "title": "Thin Provisioning",
            "description": "Sets thin provisioning.",
            "type": "boolean"
        }
    }
}

集群 (clusters)

仅限管理员。列出所有 Cinder 集群，显示集群详细信息，启用或禁用集群。

每个 Cinder 服务运行在单个*主机*计算机上（可能同一主机上运行多个服务；这取决于您如何部署 Cinder）。为了支持高可用性场景，服务可以分组到*集群*中，其中同一类型的服务（例如，cinder-volume）可以在不同的主机上运行，这样如果一台主机出现故障，服务仍然可以在另一台主机上可用。由于让这些服务闲置等待另一台主机出现故障（也称为主动/被动模式）没有意义，因此将服务分组到集群中也允许 Cinder 支持主动/主动模式，在这种模式下，集群中的所有服务都在持续工作。

注意

目前唯一可以分组到集群的服务是 cinder-volume。

集群由部署配置确定；因此，下面没有列出“创建集群”的 API 调用。但是，一旦您的服务启动并运行，您就可以使用以下 API 请求来获取有关您的集群的信息并更新其状态。

PUT
/v3/{project_id}/clusters/disable

禁用集群

禁用集群。在请求正文中指定集群的名称，并可选择指定二进制名称。

从 3.7 微版本开始可用。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

name

body

字符串

用于标识服务集群的名称。

binary (可选)

body

字符串

集群中服务的二进制名称。

disabled_reason (可选)

body

字符串

禁用资源的理由。

请求示例

{
    "name": "cluster_name",
    "binary": "cinder-volume",
    "disabled_reason": "for testing"
}

响应参数

名称

入参

类型

描述

cluster

body

对象

集群对象。

name

body

字符串

服务集群的名称。

binary

body

字符串

集群中服务的二进制名称。

state

body

字符串

集群的状态。可能是 up 或 down。

status

body

字符串

集群的状态。可能是 enabled 或 disabled。

replication_status (可选)

body

字符串

集群复制状态。仅在配置时包含在响应中。可能的值包括：enabled 或 disabled。

disabled_reason (可选)

body

字符串

禁用资源的理由。

响应示例

{
    "cluster": {
        "binary": "cinder-volume",
        "disabled_reason": "for testing",
        "name": "cluster_name",
        "state": "down",
        "status": "disabled"
    }
}
PUT
/v3/{project_id}/clusters/enable

启用集群

启用集群。在请求正文中指定集群的名称，并可选择指定二进制名称。

从 3.7 微版本开始可用。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

name

body

字符串

用于标识服务集群的名称。

binary (可选)

body

字符串

集群中服务的二进制名称。

请求示例

{
    "name": "cluster_name",
    "binary": "cinder-volume"
}

响应参数

名称

入参

类型

描述

cluster

body

对象

集群对象。

name

body

字符串

服务集群的名称。

binary

body

字符串

集群中服务的二进制名称。

state

body

字符串

集群的状态。可能是 up 或 down。

status

body

字符串

集群的状态。可能是 enabled 或 disabled。

replication_status (可选)

body

字符串

集群复制状态。仅在配置时包含在响应中。可能的值包括：enabled 或 disabled。

disabled_reason (可选)

body

字符串

禁用资源的理由。

响应示例

{
    "cluster": {
        "name": "cluster_name",
        "state": "down",
        "binary": "cinder-volume",
        "status": "enabled",
        "disabled_reason": null
    }
}
GET
/v3/{project_id}/clusters/{cluster_name}

显示集群详细信息

显示集群的详细信息，通过其名称，并可选择指定二进制名称。

从 3.7 微版本开始可用。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

cluster_name

路径

字符串

集群的名称。

binary (可选)

查询

字符串

按集群服务的二进制名称过滤集群列表结果。可能的值包括 cinder-api、cinder-scheduler、cinder-volume 或 cinder-backup。

响应参数

名称

入参

类型

描述

cluster

body

对象

集群对象。

name

body

字符串

服务集群的名称。

binary

body

字符串

集群中服务的二进制名称。

state

body

字符串

集群的状态。可能是 up 或 down。

status

body

字符串

集群的状态。可能是 enabled 或 disabled。

num_hosts

body

整数

集群中的主机数量。

num_down_hosts

body

整数

集群中处于关闭状态的主机数量。

last_heartbeat

body

字符串

收到的最后一次心跳。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

disabled_reason (可选)

body

字符串

禁用资源的理由。

replication_status (可选)

body

字符串

集群复制状态。仅在配置时包含在响应中。可能的值包括：enabled 或 disabled。

frozen (可选)

body

布尔值

集群是否处于冻结状态。

3.26 版本新增

active_backend_id (可选)

body

字符串

活动存储后端的 ID。仅在 cinder-volume 服务中。

3.26 版本新增

响应示例

{
    "cluster": {
        "binary": "cinder-volume",
        "created_at": "2016-06-01T02:46:28.000000",
        "disabled_reason": null,
        "last_heartbeat": "2016-06-01T02:46:28.000000",
        "name": "cluster_name",
        "num_down_hosts": 0,
        "num_hosts": 0,
        "state": "down",
        "status": "enabled",
        "updated_at": "2016-06-01T02:46:28.000000"
    }
}
GET
/v3/{project_id}/clusters

列出集群

列出所有集群。

从 3.7 微版本开始可用。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

name (可选)

查询

字符串

按集群名称过滤集群列表结果。

binary (可选)

查询

字符串

按集群服务的二进制名称过滤集群列表结果。可能的值包括 cinder-api、cinder-scheduler、cinder-volume 或 cinder-backup。

is_up (可选)

查询

布尔值

按状态过滤集群列表结果。

disabled (可选)

查询

布尔值

按状态过滤集群列表结果。

num_hosts (可选)

查询

整数

按主机数量过滤集群列表结果。

num_down_hosts (可选)

查询

整数

按关闭主机数量过滤集群列表结果。

replication_status (可选)

查询

字符串

按复制状态过滤集群列表结果。可能的值包括：enabled、disabled。

响应参数

名称

入参

类型

描述

clusters

body

数组

集群对象列表。

name

body

字符串

服务集群的名称。

binary

body

字符串

集群中服务的二进制名称。

state

body

字符串

集群的状态。可能是 up 或 down。

status

body

字符串

集群的状态。可能是 enabled 或 disabled。

replication_status (可选)

body

字符串

集群复制状态。仅在配置时包含在响应中。可能的值包括：enabled 或 disabled。

响应示例

{
    "clusters": [
        {
            "name": "cluster_name",
            "binary": "cinder-volume",
            "state": "down",
            "status": "enabled"
        },
        {
            "name": "cluster2",
            "binary": "cinder-volume",
            "state": "down",
            "status": "disabled"
        }
    ]
}
GET
/v3/{project_id}/clusters/detail

列出带详细信息的集群

列出所有带详细信息的集群。

从 3.7 微版本开始可用。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

name (可选)

查询

字符串

按集群名称过滤集群列表结果。

binary (可选)

查询

字符串

按集群服务的二进制名称过滤集群列表结果。可能的值包括 cinder-api、cinder-scheduler、cinder-volume 或 cinder-backup。

is_up (可选)

查询

布尔值

按状态过滤集群列表结果。

disabled (可选)

查询

布尔值

按状态过滤集群列表结果。

num_hosts (可选)

查询

整数

按主机数量过滤集群列表结果。

num_down_hosts (可选)

查询

整数

按关闭主机数量过滤集群列表结果。

replication_status (可选)

查询

字符串

按复制状态过滤集群列表结果。可能的值包括：enabled、disabled。

frozen (可选)

body

布尔值

集群是否处于冻结状态。

3.26 版本新增

active_backend_id (可选)

body

字符串

活动存储后端的 ID。仅在 cinder-volume 服务中。

3.26 版本新增

响应参数

名称

入参

类型

描述

clusters

body

数组

集群对象列表。

name

body

字符串

服务集群的名称。

binary

body

字符串

集群中服务的二进制名称。

state

body

字符串

集群的状态。可能是 up 或 down。

status

body

字符串

集群的状态。可能是 enabled 或 disabled。

num_hosts

body

整数

集群中的主机数量。

num_down_hosts

body

整数

集群中处于关闭状态的主机数量。

last_heartbeat

body

字符串

收到的最后一次心跳。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

updated_at

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

disabled_reason (可选)

body

字符串

禁用资源的理由。

replication_status (可选)

body

字符串

集群复制状态。仅在配置时包含在响应中。可能的值包括：enabled 或 disabled。

frozen (可选)

body

布尔值

集群是否处于冻结状态。

3.26 版本新增

active_backend_id (可选)

body

字符串

活动存储后端的 ID。仅在 cinder-volume 服务中。

3.26 版本新增

响应示例

{
    "clusters": [
        {
            "binary": "cinder-volume",
            "created_at": "2016-06-01T02:46:28.000000",
            "disabled_reason": null,
            "last_heartbeat": "2016-06-01T02:46:28.000000",
            "name": "cluster_name",
            "num_down_hosts": 0,
            "num_hosts": 0,
            "state": "down",
            "status": "enabled",
            "updated_at": "2016-06-01T02:46:28.000000"
        },
        {
            "binary": "cinder-volume",
            "created_at": "2016-06-01T01:46:28.000000",
            "disabled_reason": "for testing",
            "last_heartbeat": "",
            "name": "cluster2",
            "num_down_hosts": 1,
            "num_hosts": 2,
            "state": "down",
            "status": "disabled",
            "updated_at": "2016-06-01T01:46:28.000000"
        }
    ]
}

一致性组（已弃用）

一致性组允许您从多个卷创建同一时间点的快照。例如，一个数据库可能将表、日志和配置放在不同的卷上。要从以前的时间点恢复此数据库，最好从确切的同一时间点一起恢复日志、表和配置。

使用策略配置文件授予这些操作的权限，以限制角色。

GET
/v3/{project_id}/consistencygroups

列出项目的一致性组

列出一致性组。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

consistencygroups

body

数组

一致性组列表。

id

body

字符串

对象的 UUID。

name (可选)

body

字符串

对象名称。

响应示例

{
    "consistencygroups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my-cg1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my-cg2"
        }
    ]
}
POST
/v3/{project_id}/consistencygroups

创建一致性组

创建一致性组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

consistencygroup

body

对象

一致性组。

description (可选)

body

字符串

一致性组的描述。

availability_zone (可选)

body

字符串

可用区的名称。

volume_types

body

字符串

用逗号分隔的卷类型列表。在具有多存储后端的环境中，调度程序根据卷类型确定将卷发送到何处。有关如何使用卷类型创建多存储后端的信息，请参阅 配置多存储后端。

name (可选)

body

字符串

一致性组的名称。

请求示例

{
    "consistencygroup": {
        "name": "firstcg",
        "description": "first consistency group",
        "volume_types": "type1,type2",
        "availability_zone": "az0"
    }
}

响应

名称

入参

类型

描述

consistencygroup

body

对象

一致性组。

status

body

字符串

一致性组的状态。

description

body

字符串

一致性组的描述。

availability_zone (可选)

body

字符串

可用区的名称。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_types

body

数组

卷类型列表。在具有多个存储后端的环境中，调度器会根据卷类型确定将卷发送到哪里。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

name (可选)

body

字符串

一致性组的名称。

id (可选)

body

字符串

一致性组的 UUID。

响应示例

{
    "consistencygroup": {
        "status": "error",
        "description": "first consistency group",
        "availability_zone": "az0",
        "created_at": "2016-08-19T19:32:19.000000",
        "volume_types": ["type1", "type2"],
        "id": "63d1a274-de38-4384-a97e-475306777027",
        "name": "firstcg"
    }
}
GET
/v3/{project_id}/consistencygroups/{consistencygroup_id}

显示一致性组的详细信息

显示一致性组的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

consistencygroup_id

路径

字符串

一致性组的 ID。

响应参数

名称

入参

类型

描述

status

body

字符串

一致性组的状态。

description

body

字符串

一致性组的描述。

availability_zone (可选)

body

字符串

可用区的名称。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_types

body

数组

卷类型列表。在具有多个存储后端的环境中，调度器会根据卷类型确定将卷发送到哪里。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

id

body

字符串

对象的 UUID。

name (可选)

body

字符串

对象名称。

响应示例

{
    "consistencygroup": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "status": "available",
        "availability_zone": "az1",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "my-cg1",
        "description": "my first consistency group",
        "volume_types": [
            "123456"
        ]
    }
}
POST
/v3/{project_id}/consistencygroups/create_from_src

从源创建一致性组

从源创建一致性组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

consistencygroup-from-src

body

对象

一致性组从源对象。

status

body

字符串

一致性组的状态。

user_id

body

字符串

用户的 UUID。

description (可选)

body

字符串

一致性组的描述。

cgsnapshot_id (可选)

body

字符串

一致性组快照的 UUID。

source_cgid (可选)

body

字符串

源一致性组的 UUID。

project_id

body

字符串

项目的 UUID。

name (可选)

body

字符串

对象名称。

请求示例

{
    "consistencygroup-from-src": {
        "name": "firstcg",
        "description": "first consistency group",
        "cgsnapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
        "source_cgid": "6f519a48-3183-46cf-a32f-41815f814546",
        "user_id": "6f519a48-3183-46cf-a32f-41815f815555",
        "project_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "status": "creating"
    }
}
POST
/v3/{project_id}/consistencygroups/{consistencygroup_id}/delete

删除一致性组

删除一致性组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

consistencygroup_id

路径

字符串

一致性组的 ID。

consistencygroup

body

对象

一致性组。

force (可选)

body

布尔值

指示是否备份，即使卷已连接。默认为 false。请参阅 有效的布尔值

请求示例

{
    "consistencygroup": {
        "force": false
    }
}
GET
/v3/{project_id}/consistencygroups/detail

列出一致性组和详细信息

列出一致性组及其详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

consistencygroups

body

数组

一致性组列表。

status

body

字符串

一致性组的状态。

description

body

字符串

一致性组的描述。

availability_zone (可选)

body

字符串

可用区的名称。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

volume_types

body

数组

卷类型列表。在具有多个存储后端的环境中，调度器会根据卷类型确定将卷发送到哪里。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

id

body

字符串

对象的 UUID。

name (可选)

body

字符串

对象名称。

响应示例

{
    "consistencygroups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "status": "available",
            "availability_zone": "az1",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my-cg1",
            "description": "my first consistency group",
            "volume_types": [
                "123456"
            ]
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "status": "error",
            "availability_zone": "az2",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my-cg2",
            "description": "Edited description",
            "volume_types": [
                "234567"
            ]
        }
    ]
}
PUT
/v3/{project_id}/consistencygroups/{consistencygroup_id}/update

更新一致性组

更新一致性组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

consistencygroup_id

路径

字符串

一致性组的 ID。

consistencygroup

body

对象

一致性组。

remove_volumes (可选)

body

字符串

要从卷组或一致性组中移除的一个或多个卷 UUID，用逗号分隔。

description (可选)

body

字符串

一致性组的描述。

add_volumes (可选)

body

字符串

要添加到卷组或一致性组的一个或多个卷 UUID，用逗号分隔。

name (可选)

body

字符串

对象名称。

请求示例

{
    "consistencygroup": {
        "name": "my_cg",
        "description": "My consistency group",
        "add_volumes": "volume-uuid-1,volume-uuid-2",
        "remove_volumes": "volume-uuid-8,volume-uuid-9"
    }
}

一致性组快照（已弃用）

列出所有、列出所有带详细信息、显示详细信息、创建和删除一致性组快照。

DELETE
/v3/{project_id}/cgsnapshots/{cgsnapshot_id}

删除一致性组快照

删除一致性组快照。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

cgsnapshot_id

路径

字符串

一致性组快照的 ID。
GET
/v3/{project_id}/cgsnapshots/{cgsnapshot_id}

显示一致性组快照详细信息

显示一致性组快照的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

cgsnapshot_id

路径

字符串

一致性组快照的 ID。

响应参数

名称

入参

类型

描述

cgsnapshot

body

对象

一致性组快照对象。

status (可选)

body

字符串

一致性组快照的 status。

description

body

字符串

一致性组快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

consistencygroup_id

body

字符串

一致性组的 UUID。

id

body

字符串

对象的 UUID。

name

body

字符串

一致性组快照的名称。

响应示例

{
    "cgsnapshot": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "status": "available",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "my-cg1",
        "description": "my first consistency group"
    }
}
GET
/v3/{project_id}/cgsnapshots/detail

列出所有带详细信息的一致性组快照

列出所有带详细信息的一致性组快照。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

响应参数

名称

入参

类型

描述

cgsnapshots

body

对象

一组 cgsnapshot 对象。

status (可选)

body

字符串

一致性组快照的 status。

description

body

字符串

一致性组快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

consistencygroup_id

body

字符串

一致性组的 UUID。

id

body

字符串

对象的 UUID。

name

body

字符串

一致性组快照的名称。

响应示例

{
    "cgsnapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814444",
            "status": "available",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my-cg1",
            "description": "my first consistency group"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "consistencygroup_id": "aed36625-a6d7-4681-ba59-c7ba3d18dddd",
            "status": "error",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my-cg2",
            "description": "Edited description"
        }
    ]
}
GET
/v3/{project_id}/cgsnapshots

列出所有一致性组快照

列出所有一致性组快照。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

响应参数

名称

入参

类型

描述

cgsnapshots

body

对象

一组 cgsnapshot 对象。

id

body

字符串

对象的 UUID。

name

body

字符串

一致性组快照的名称。

响应示例

{
    "cgsnapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my-cg1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my-cg2"
        }
    ]
}
POST
/v3/{project_id}/cgsnapshots

创建一致性组快照

创建一致性组快照。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

cgsnapshot

body

对象

一致性组快照对象。

name (可选)

body

字符串

快照的名称。默认为 None。

consistencygroup_id

body

字符串

一致性组的 UUID。

description (可选)

body

字符串

一致性组快照的描述。

请求示例

{
    "cgsnapshot": {
        "consistencygroup_id": "6f519a48-3183-46cf-a32f-41815f814546",
        "name": "firstcg",
        "description": "first consistency group",
        "status": "creating"
    }
}

响应参数

名称

入参

类型

描述

status (可选)

body

字符串

一致性组快照的 status。

description

body

字符串

一致性组快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

consistencygroup_id

body

字符串

一致性组的 UUID。

id

body

字符串

对象的 UUID。

name

body

字符串

一致性组快照的名称。

服务（os-services）

仅限管理员。列出所有 Cinder 服务，启用或禁用 Cinder 服务，冻结或解冻指定的 cinder-volume 主机，故障转移正在复制的 cinder-volume 主机。

GET
/v3/{project_id}/os-services

列出所有 Cinder 服务

列出所有 Cinder 服务。提供有关服务为何被禁用的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

host (可选)

查询

字符串

按服务主机名过滤服务列表结果。

binary (可选)

查询

字符串

按服务的二进制名称过滤服务列表结果。

响应参数

名称

入参

类型

描述

services

body

数组

服务对象列表。

binary

body

字符串

服务的二进制名称。

disabled_reason

body

字符串

禁用资源的理由。

host

body

字符串

主机的名称。

state

body

字符串

服务的状态。为 up 或 down 中的一个。

status

body

字符串

服务状态。为 enabled 或 disabled 中的一个。

frozen (可选)

body

布尔值

主机是否被冻结。仅在 cinder-volume 服务中。

updated_at

body

字符串

扩展上次更新的日期和时间戳。

zone

body

字符串

可用区名称。

cluster (可选)

body

字符串

集群名称。仅在 cinder-volume 服务中。

3.7 版本新增

replication_status (可选)

body

字符串

卷服务的复制状态。仅在 cinder-volume 服务中。

active_backend_id (可选)

body

字符串

活动存储后端的 ID。仅在 cinder-volume 服务中。

backend_state (可选)

body

字符串

存储后端的当前状态。仅在 cinder-volume 服务中。

响应示例

{
    "services": [{
        "status": "enabled",
        "binary": "cinder-scheduler",
        "zone": "nova",
        "state": "up",
        "updated_at": "2017-06-29T05:50:35.000000",
        "host": "devstack",
        "disabled_reason": null
    },
    {
        "status": "enabled",
        "binary": "cinder-backup",
        "zone": "nova",
        "state": "up",
        "updated_at": "2017-06-29T05:50:42.000000",
        "host": "devstack",
        "disabled_reason": null
    },
    {
        "status": "enabled",
        "binary": "cinder-volume",
        "zone": "nova",
        "frozen": false,
        "state": "up",
        "updated_at": "2017-06-29T05:50:39.000000",
        "cluster": null,
        "host": "devstack@lvmdriver-1",
        "replication_status": "disabled",
        "active_backend_id": null,
        "disabled_reason": null
    }]
}
PUT
/v3/{project_id}/os-services/disable

禁用 Cinder 服务

禁用 Cinder 服务。通过其主机名和二进制名称指定服务。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

host

body

字符串

主机的名称。

binary

body

字符串

服务的二进制名称。

请求示例

{
    "binary": "cinder-volume",
    "host": "devstack@lvmdriver-1"
}

响应参数

名称

入参

类型

描述

disabled

body

布尔值

服务是否被禁用。

status

body

字符串

服务状态。为 enabled 或 disabled 中的一个。

host

body

字符串

主机的名称。

服务

body

字符串

服务名称。已弃用。保留 service 键以保持 API 兼容性。

binary

body

字符串

服务的二进制名称。

响应示例

{
    "disabled": true,
    "status": "disabled",
    "host": "devstack@lvmdriver-1",
    "service": "",
    "binary": "cinder-volume"
}
PUT
/v3/{project_id}/os-services/disable-log-reason

记录禁用 Cinder 服务的信息

将信息记录到 Cinder 服务表中，说明 Cinder 服务被禁用的原因。

通过其主机名和二进制名称指定服务。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

binary

body

字符串

服务的二进制名称。

host

body

字符串

主机的名称。

disabled_reason (可选)

body

字符串

禁用资源的理由。

请求示例

{
    "binary": "cinder-volume",
    "host": "devstack@lvmdriver-1",
    "disabled_reason": "test"
}

响应

名称

入参

类型

描述

disabled

body

布尔值

服务是否被禁用。

status

body

字符串

服务状态。为 enabled 或 disabled 中的一个。

host

body

字符串

主机的名称。

服务

body

字符串

服务名称。已弃用。保留 service 键以保持 API 兼容性。

binary

body

字符串

服务的二进制名称。

disabled_reason

body

字符串

禁用资源的理由。

响应示例

{
    "disabled": true,
    "status": "disabled",
    "host": "devstack@lvmdriver-1",
    "service": "",
    "binary": "cinder-volume",
    "disabled_reason": "test"
}
PUT
/v3/{project_id}/os-services/enable

启用 Cinder 服务

启用 Cinder 服务。通过其主机名和二进制名称指定服务。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

binary

body

字符串

服务的二进制名称。

host

body

字符串

主机的名称。

请求示例

{
    "binary": "cinder-volume",
    "host": "devstack@lvmdriver-1"
}

响应参数

名称

入参

类型

描述

disabled

body

布尔值

服务是否被禁用。

status

body

字符串

服务状态。为 enabled 或 disabled 中的一个。

host

body

字符串

主机的名称。

服务

body

字符串

服务名称。已弃用。保留 service 键以保持 API 兼容性。

binary

body

字符串

服务的二进制名称。

disabled_reason

body

字符串

禁用资源的理由。

响应示例

{
    "disabled": false,
    "status": "enabled",
    "host": "devstack@lvmdriver-1",
    "service": "",
    "binary": "cinder-volume",
    "disabled_reason": null
}
PUT
/v3/{project_id}/os-services/get-log

获取 Cinder 服务的当前日志级别

获取服务的当前日志级别，自 v3.32 起支持。按二进制、服务器名称和日志路径前缀过滤服务。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

binary (可选)

body

字符串

服务的二进制名称。

server (可选)

body

字符串

主机的名称。

prefix (可选)

body

字符串

我们要查询的日志路径的前缀，例如 cinder. 或 sqlalchemy.engine。如果不存在或传入空字符串，将检索所有日志级别。

请求示例

{
    "binary": "cinder-volume",
    "server": "devstack@lvmdriver-1",
    "prefix": "cinder.volume"
}

响应参数

名称

入参

类型

描述

log_levels

body

数组

日志级别列表。

binary

body

字符串

服务的二进制名称。

host

body

字符串

主机的名称。

levels

body

对象

当前查询的日志级别。

响应示例

{
    "log_levels": [{
        "binary": "cinder-api",
        "host": "devstack",
        "levels": {
            "cinder.volume.api": "DEBUG"
        }
    },
    {
        "binary": "cinder-scheduler",
        "host": "devstack",
        "levels": {
            "cinder.volume.api": "DEBUG"
        }
    },
    {
        "binary": "cinder-backup",
        "host": "devstack",
        "levels": {}
    },
    {
        "binary": "cinder-volume",
        "host": "devstack@lvmdriver-1",
        "levels": {
            "cinder.volume.api": "DEBUG"
        }
    }]
}
PUT
/v3/{project_id}/os-services/set-log

动态设置 Cinder 服务的日志级别

动态设置服务日志级别，自 v3.32 起支持。按二进制、服务器名称和日志路径前缀过滤服务。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

binary (可选)

body

字符串

服务的二进制名称。

server (可选)

body

字符串

主机的名称。

prefix (可选)

body

字符串

我们要查询的日志路径的前缀，例如 cinder. 或 sqlalchemy.engine。如果不存在或传入空字符串，将检索所有日志级别。

levels

body

字符串

要设置的日志级别，不区分大小写，可接受的值包括 INFO、WARNING、ERROR 和 DEBUG。

请求示例

{
    "binary": "cinder-volume",
    "server": "devstack@lvmdriver-1",
    "prefix": "cinder.volume",
    "level": "ERROR"
}
PUT
/v3/{project_id}/os-services/freeze

冻结 Cinder 后端主机

冻结并禁用指定的 cinder-volume 主机，并将 Cinder 服务表中的 Disabled Reason 设置为 frozen。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

host

body

字符串

主机的名称。

请求示例

{
    "host": "devstack@rbd-sas"
}
PUT
/v3/{project_id}/os-services/thaw

解冻 Cinder 后端主机

解冻并启用指定的 cinder-volume 主机，并清除 Cinder 服务表中的 Disabled Reason。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

host

body

字符串

主机的名称。

请求示例

{
    "host": "devstack@rbd-sas"
}
PUT
/v3/{project_id}/os-services/failover_host

故障转移 Cinder 后端主机

故障转移正在复制的 cinder-volume 主机。自 Cinder Volume API 版本 3.26 起，您可以在请求 URL 中使用 failover 代替 failover_host，并且支持请求正文中的集群名称。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

host

body

字符串

主机的名称。

backend_id (可选)

body

字符串

要故障转移到的后端 ID。默认为 None。

cluster (可选)

body

字符串

集群名称。仅在 cinder-volume 服务中。

3.7 版本新增

请求示例

{
    "host": "devstack@lvmdriver-1",
    "backend_id": null
}

通用卷组 (groups)

通用卷组允许您创建卷组并一起管理它们。

通用卷组与一致性组有何不同？目前，Cinder 中的一致性组仅支持一致性组快照。它不能轻松扩展以服务于其他目的。项目可能希望将应用程序使用的卷放在一个组中，以便更容易地一起管理它们，而这个卷组可能支持或不支持一致性组快照。通用卷组就是为了解决这个问题而引入的。通过解耦组构造和一致性概念之间的紧密关系，通用卷组将来可以扩展以支持其他功能。

GET
/v3/{project_id}/groups

列出组

列出组。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回错误请求。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

groups

body

数组

一组组。

id

body

字符串

对象的 UUID。

name

body

字符串

组的名称。

响应示例

{
    "groups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my_group1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my_group2"
        }
    ]
}
POST
/v3/{project_id}/groups

创建组

创建一个组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group

body

对象

组对象。

description (可选)

body

字符串

组的描述。

availability_zone (可选)

body

字符串

可用区的名称。

group_type

body

字符串

组类型的 ID。

volume_types

body

数组

卷类型列表。在具有多个存储后端的环境中，调度器会根据卷类型确定将卷发送到哪里。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

name

body

字符串

组的名称。

请求示例

{
    "group": {
        "name": "first_group",
        "description": "first group",
        "group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
        "volume_types": [
            "4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
            "c4daaf47-c530-4901-b28e-f5f0a359c4e6"
        ],
        "availability_zone": "az0"
    }
}

响应参数

名称

入参

类型

描述

id

路径

字符串

组的 ID。

name

body

字符串

组的名称。

响应示例

{
    "group": {
        "id": "6f519a48-3183-46cf-a32f-41815f816666",
        "name": "first_group"
    }
}
GET
/v3/{project_id}/groups/{group_id}

显示组详细信息

显示组的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

list_volume (可选)

路径

字符串

显示组中的卷 ID。默认为 False。

3.25 版本新增

响应参数

名称

入参

类型

描述

group

body

对象

组对象。

status

body

字符串

通用组的状态。

description

body

字符串

组的描述。

availability_zone (可选)

body

字符串

可用区的名称。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

group_type

body

字符串

组类型的 ID。

group_snapshot_id (可选)

body

字符串

组快照的 ID。

source_group_id (可选)

body

字符串

源组的 UUID。

volume_types

body

数组

卷类型列表。在具有多个存储后端的环境中，调度器会根据卷类型确定将卷发送到哪里。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

id

body

字符串

对象的 UUID。

name

body

字符串

组的名称。

volumes (可选)

body

数组

当 list_volume 设置为 True 时可用，卷 ID 列表。

3.25 版本新增

replication_status (可选)

body

字符串

组复制状态。

3.38 版本新增

project_id (可选)

body

字符串

卷组项目 ID。

3.58 版本新增

响应示例

{
    "group": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "status": "available",
        "availability_zone": "az1",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "first_group",
        "description": "my first group",
        "group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
        "volume_types": [
            "c4daaf47-c530-4901-b28e-f5f0a359c4e6"
        ],
        "volumes": ["a2cdf1ad-5497-4e57-bd7d-f573768f3d03"],
        "group_snapshot_id": null,
        "source_group_id": null,
        "project_id": "7ccf4863071f44aeb8f141f65780c51b"
    }
}
POST
/v3/{project_id}/groups/action

从源创建组

从源创建组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

create-from-src

body

对象

从源创建操作。

description (可选)

body

字符串

组的描述。

group_snapshot_id

body

字符串

组快照的 ID。

source_group_id

body

字符串

源组的 UUID。

name

body

字符串

组的名称。

请求示例

{
    "create-from-src": {
        "name": "first_group",
        "description": "first group",
        "group_snapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
        "source_group_id": null
    }
}

响应参数

名称

入参

类型

描述

id

路径

字符串

组的 ID。

name

body

字符串

组的名称。

响应示例

{
    "group": {
        "id": "6f519a48-3183-46cf-a32f-41815f816666",
        "name": "first_group"
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

删除分组

删除组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

删除

body

对象

删除操作。

delete-volumes (可选)

body

布尔值

如果设置为 true，则允许删除组以及组中的所有卷。请参阅 有效的布尔值

请求示例

{
    "delete": {
        "delete-volumes": false
    }
}
GET
/v3/{project_id}/groups/detail

列出带详细信息的组

列出带详细信息的组，自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回错误请求。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

list_volume (可选)

路径

字符串

显示组中的卷 ID。默认为 False。

3.25 版本新增

响应参数

名称

入参

类型

描述

groups

body

数组

一组组。

status

body

字符串

通用组的状态。

description

body

字符串

组的描述。

availability_zone (可选)

body

字符串

可用区的名称。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

group_type

body

字符串

组类型的 ID。

group_snapshot_id (可选)

body

字符串

组快照的 ID。

source_group_id (可选)

body

字符串

源组的 UUID。

volume_types

body

数组

卷类型列表。在具有多个存储后端的环境中，调度器会根据卷类型确定将卷发送到哪里。有关如何使用卷类型创建多个存储后端的信息，请参阅 配置多个存储后端。

id

路径

字符串

组的 ID。

name (可选)

body

字符串

对象名称。

volumes (可选)

body

数组

当 list_volume 设置为 True 时可用，卷 ID 列表。

3.25 版本新增

replication_status (可选)

body

字符串

组复制状态。

3.38 版本新增

project_id (可选)

body

字符串

卷组项目 ID。

3.58 版本新增

响应示例

{
    "groups": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "status": "available",
            "availability_zone": "az1",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my_group1",
            "description": "my first group",
            "group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
            "volume_types": [
                "4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
                "a3d55d15-eeb1-4816-ada9-bf82decc09b3"
            ],
            "volumes": ["a2cdf1ad-5497-4e57-bd7d-f573768f3d03"],
            "project_id": "7ccf4863071f44aeb8f141f65780c51b"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "status": "error",
            "availability_zone": "az2",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my_group2",
            "description": "Edited description",
            "group_type": "f8645498-1323-47a2-9442-5c57724d2e3c",
            "volume_types": [
                "c4daaf47-c530-4901-b28e-f5f0a359c4e6"
            ],
            "volumes": ["a2cdf1ad-5497-4e57-bd7d-f573768f3d03"],
            "project_id": "7ccf4863071f44aeb8f141f65780c51b"
        }
    ]
}
PUT
/v3/{project_id}/groups/{group_id}

更新分组

更新组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

group

body

对象

组对象。

remove_volumes (可选)

body

字符串

要从卷组或一致性组中移除的一个或多个卷 UUID，用逗号分隔。

description (可选)

body

字符串

组的描述。

add_volumes (可选)

body

字符串

要添加到卷组或一致性组的一个或多个卷 UUID，用逗号分隔。

name

body

字符串

组的名称。

请求示例

{
    "group": {
        "name": "my_group",
        "description": "My group",
        "add_volumes": "volume-uuid-1,volume-uuid-2",
        "remove_volumes": "volume-uuid-8,volume-uuid-9"
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

重置组状态

重置组的状态。在请求正文中指定 reset_status 操作。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

reset_status

body

对象

重置状态操作。

status (可选)

body

字符串

一致性组快照的 status。

请求示例

{
    "reset_status": {
        "status": "available"
    }
}

组复制 (groups, action)

列出目标、启用、禁用和故障转移组复制。

API 微版本 3.38 起可用。

POST
/v3/{project_id}/groups/{group_id}/action

列出复制目标

列出组的复制目标。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

请求示例

{
    "list_replication_targets": {}
}

响应参数

名称

入参

类型

描述

backend_id

body

字符串

故障转移目标后端的 ID。

unique_key (可选)

body

字符串

供应商特定的键值对。仅在管理员时返回。

响应示例

{
    "replication_targets": {
        "backend_id": "vendor-id-1",
        "unique_key": "value1"
    }
}
POST
/v3/{project_id}/groups/{group_id}/action

启用组复制

为组启用复制。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

请求示例

{
    "enable_replication": {}
}
POST
/v3/{project_id}/groups/{group_id}/action

禁用组复制

为组禁用复制。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

请求示例

{
    "disable_replication": {}
}
POST
/v3/{project_id}/groups/{group_id}/action

故障转移复制

故障转移复制的组。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_id

路径

字符串

组的 ID。

allow_attached_volume

body

布尔值

是否允许在任何卷处于“使用中”状态时进行故障转移。请参阅 有效的布尔值

secondary_backend_id

body

字符串

故障转移目标后端的 ID。

请求示例

{
    "failover_replication": {
        "allow_attached_volume": true,
        "secondary_backend_id": "vendor-id-1"
    }
}

组快照 (group_snapshots)

列出所有、列出所有带详细信息、显示详细信息、创建和删除组快照。

DELETE
/v3/{project_id}/group_snapshots/{group_snapshot_id}

删除组快照

删除组快照。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_snapshot_id

路径

字符串

组快照的 ID。
GET
/v3/{project_id}/group_snapshots/{group_snapshot_id}

显示组快照详细信息

显示组快照的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_snapshot_id

路径

字符串

组快照的 ID。

响应参数

名称

入参

类型

描述

group_snapshot

body

对象

组快照。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

group_id

body

字符串

源组的 UUID。

id

body

字符串

组快照的 ID。

name

body

字符串

组快照的名称。

status

body

字符串

通用组快照的 status。

description

body

字符串

组快照的描述。

group_type_id

body

字符串

组类型的 ID。

project_id (可选)

body

字符串

卷组快照项目 ID。

3.58 版本新增

响应示例

{
    "group_snapshot": {
        "id": "6f519a48-3183-46cf-a32f-41815f813986",
        "group_id": "6f519a48-3183-46cf-a32f-41815f814444",
        "status": "available",
        "created_at": "2015-09-16T09:28:52.000000",
        "name": "my_group_snapshot1",
        "description": "my first group snapshot",
        "group_type_id": "7270c56e-6354-4528-8e8b-f54dee2232c8",
        "project_id": "7ccf4863071f44aeb8f141f65780c51b"
    }
}
GET
/v3/{project_id}/group_snapshots/detail

列出带详细信息的组快照

列出所有带详细信息的组快照。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回错误请求。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

3.29 版本新增

sort_key (可选)

查询

字符串

按属性排序。有效值为 name、status、group_id、group_type_id、size、id、created_at 或 updated_at。默认为 created_at。API 使用 sort_key 属性值的自然排序方向。已弃用，推荐使用 sort 参数。

3.29 版本新增

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

3.29 版本新增

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

3.29 版本新增

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

3.29 版本新增

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

3.29 版本新增

响应参数

名称

入参

类型

描述

group_snapshots

body

数组

一组组快照。

id

body

字符串

组快照的 ID。

name

body

字符串

组快照的名称。

status

body

字符串

通用组快照的 status。

description

body

字符串

组快照的描述。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

group_id

body

字符串

组的 ID。

group_type_id

body

字符串

组类型的 ID。

project_id (可选)

body

字符串

卷组快照项目 ID。

3.58 版本新增

响应示例

{
    "group_snapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "group_id": "6f519a48-3183-46cf-a32f-41815f814444",
            "status": "available",
            "created_at": "2015-09-16T09:28:52.000000",
            "name": "my_group_snapshot1",
            "description": "my first group snapshot",
            "group_type_id": "0ef094a2-d9fd-4c79-acfd-ac60a0506b7d",
            "project_id": "7ccf4863071f44aeb8f141f65780c51b"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "group_id": "aed36625-a6d7-4681-ba59-c7ba3d18dddd",
            "status": "error",
            "created_at": "2015-09-16T09:31:15.000000",
            "name": "my_group_snapshot2",
            "description": "Edited description",
            "group_type_id": "7270c56e-6354-4528-8e8b-f54dee2232c8",
            "project_id": "7ccf4863071f44aeb8f141f65780c51b"
        }
    ]
}
GET
/v3/{project_id}/group_snapshots

列出组快照

列出所有组快照，自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回错误请求。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

all_tenants (可选)

查询

字符串

显示所有项目的详细信息。仅限管理员。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

3.29 版本新增

sort_key (可选)

查询

字符串

按属性排序。有效值为 name、status、group_id、group_type_id、size、id、created_at 或 updated_at。默认为 created_at。API 使用 sort_key 属性值的自然排序方向。已弃用，推荐使用 sort 参数。

3.29 版本新增

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

3.29 版本新增

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

3.29 版本新增

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

3.29 版本新增

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

3.29 版本新增

响应参数

名称

入参

类型

描述

group_snapshots

body

数组

一组组快照。

id

body

字符串

组快照的 ID。

name

body

字符串

组快照的名称。

响应示例

{
    "group_snapshots": [
        {
            "id": "6f519a48-3183-46cf-a32f-41815f813986",
            "name": "my_group_snapshot1"
        },
        {
            "id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
            "name": "my_group_snapshot2"
        }
    ]
}
POST
/v3/{project_id}/group_snapshots

创建组快照

创建组快照。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_snapshot

body

对象

组快照。

name (可选)

body

字符串

组快照的名称。

description (可选)

body

字符串

组快照的描述。

group_id

body

字符串

组的 ID。

请求示例

{
    "group_snapshot": {
        "group_id": "6f519a48-3183-46cf-a32f-41815f814546",
        "name": "first_group_snapshot",
        "description": "first group snapshot"
    }
}

响应参数

名称

入参

类型

描述

group_snapshot

body

对象

组快照。

id

body

字符串

组快照的 ID。

name

body

字符串

组快照的名称。

group_type_id

body

字符串

组类型的 ID。

响应示例

{
    "group_snapshot": {
        "id": "6f519a48-3183-46cf-a32f-41815f816666",
        "name": "first_group_snapshot",
        "group_type_id": "58737af7-786b-48b7-ab7c-2447e74b0ef4"
    }
}
POST
/v3/{project_id}/group_snapshots/{group_snapshot_id}/action

重置组快照状态

重置组快照的状态。在请求正文中指定 reset_status 操作。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_snapshot_id

路径

字符串

组快照的 ID。

reset_status

body

对象

重置状态操作。

status

body

字符串

通用组快照的 status。

请求示例

{
    "reset_status": {
        "status": "available"
    }
}

组类型 (group_types)

要创建通用卷组，您必须指定组类型。

PUT
/v3/{project_id}/group_types/{group_type_id}

更新组类型

更新组类型。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。
500 - 内部服务器错误

服务出现问题，导致无法满足请求。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type_id

路径

字符串

现有组类型的 UUID。

group_type

body

对象

一个 group_type 对象。

name (可选)

body

字符串

组的名称。

description (可选)

body

字符串

组类型的描述。

is_public (可选)

body

布尔值

组类型是否公开可见。请参阅 有效的布尔值

请求示例

{
    "group_type": {
        "name": "grp-type-001",
        "description": "group type 0001",
        "is_public": true
    }
}

响应参数

名称

入参

类型

描述

group_type

body

对象

一个 group_type 对象。

id

body

字符串

组类型的 ID。

is_public

body

布尔值

组类型是否公开可见。

group_specs (可选)

body

对象

包含组类型规范的键值对集。

description

body

字符串

组类型的描述。

name

body

字符串

组类型的名称。

响应示例

{
    "group_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "grp-type-001",
        "description": "group type 001",
        "is_public": true,
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}
GET
/v3/{project_id}/group_types/{group_type_id}

显示组类型详细信息

显示组类型的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type_id

路径

字符串

现有组类型的 UUID。

响应参数

名称

入参

类型

描述

group_type

body

对象

一个 group_type 对象。

id

body

字符串

组类型的 ID。

name

body

字符串

组类型的名称。

is_public

body

布尔值

组类型是否公开可见。

group_specs (可选)

body

对象

包含组类型规范的键值对集。

description

body

字符串

组类型的描述。

响应示例

{
    "group_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "grp-type-001",
        "description": "group type 001",
        "is_public": true,
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}
GET
/v3/{project_id}/group_types/default

显示默认组类型详细信息

显示已配置的默认组类型的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

响应参数

名称

入参

类型

描述

group_type

body

对象

一个 group_type 对象。

id

body

字符串

组类型的 ID。

name

body

字符串

组类型的名称。

is_public

body

布尔值

组类型是否公开可见。

group_specs (可选)

body

对象

包含组类型规范的键值对集。

description

body

字符串

组类型的描述。

响应示例

{
    "group_type": {
        "id": "7270c56e-6354-4528-8e8b-f54dee2232c8",
        "name": "group-type-test",
        "description": "default group type",
        "is_public": true,
        "group_specs": {}
    }
}
DELETE
/v3/{project_id}/group_types/{group_type_id}

删除组类型

删除组类型。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

group_type_id

路径

字符串

现有组类型的 UUID。

project_id

路径

字符串

多租户云中项目的 UUID。
GET
/v3/{project_id}/group_types

列出组类型

列出组类型。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

group_types

body

数组

组类型列表。

id

body

字符串

组类型的 ID。

group_specs (可选)

body

对象

包含组类型规范的键值对集。

name

body

字符串

组类型的名称。

is_public

body

布尔值

组类型是否公开可见。

description

body

字符串

组类型的描述。

响应示例

{
    "group_types": [
        {
            "is_public": true,
            "group_specs": {
                "consistent_group_snapshot_enabled": "<is> False"
            },
            "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
            "name": "group_type1",
            "description": "tempest-group-type-description-1261576824"
        },
        {
            "is_public": true,
            "group_specs": {},
            "id": "8eb69a46-df97-4e41-9586-9a40a7533803",
            "name": "group_type2",
            "description": "tempest-group-type-description-3927295731"
        }
    ]
}
POST
/v3/{project_id}/group_types

创建组类型

创建组类型。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。
409 - Conflict

此资源有一个正在进行的操作，与此请求冲突。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type

body

对象

一个 group_type 对象。

name

body

字符串

组类型的名称。

description (可选)

body

字符串

组类型的描述。

is_public (可选)

body

布尔值

组类型是否公开可见。请参阅 有效的布尔值

group_specs (可选)

body

对象

包含组类型规范的键值对集。

请求示例

{
    "group_type": {
        "name": "grp-type-001",
        "description": "group type 0001",
        "is_public": true,
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}

响应参数

名称

入参

类型

描述

group_type

body

对象

一个 group_type 对象。

id

body

字符串

组类型的 ID。

is_public

body

布尔值

组类型是否公开可见。

group_specs (可选)

body

对象

包含组类型规范的键值对集。

description

body

字符串

组类型的描述。

name

body

字符串

组类型的名称。

响应示例

{
    "group_type": {
        "id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
        "name": "grp-type-001",
        "description": "group type 001",
        "is_public": true,
        "group_specs": {
            "consistent_group_snapshot_enabled": "<is> False"
        }
    }
}

组类型规格 (group_types, group_specs)

POST
/v3/{project_id}/group_types/{group_type_id}/group_specs

为组类型创建或更新组规格

为组类型创建组规格，如果规格键已存在于组规格中，此 API 将更新该规格。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type_id

路径

字符串

现有组类型的 UUID。

group_specs

body

对象

包含组类型规范的键值对集。

请求示例

{
    "group_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}

响应参数

名称

入参

类型

描述

group_specs

body

对象

包含组类型规范的键值对集。

响应示例

{
    "group_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
GET
/v3/{project_id}/group_types/{group_type_id}/group_specs

列出组类型的组规格

列出组类型的全部组规格。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type_id

路径

字符串

现有组类型的 UUID。

响应参数

名称

入参

类型

描述

group_specs

body

对象

包含组类型规范的键值对集。

响应示例

{
    "group_specs": {
        "key1": "value1",
        "key2": "value2"
    }
}
GET
/v3/{project_id}/group_types/{group_type_id}/group_specs/{spec_id}

显示组类型的特定组规格

显示组类型的组规格。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type_id

路径

字符串

现有组类型的 UUID。

spec_id

路径

字符串

组规格的 ID（键）。

响应参数

名称

入参

类型

描述

spec

body

字符串

与指定键对应的组规格的值。

响应示例

{
    "key1": "value1"
}
PUT
/v3/{project_id}/group_types/{group_type_id}/group_specs/{spec_id}

更新组类型的特定组规格

更新组类型的组规格。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type_id

路径

字符串

现有组类型的 UUID。

spec_id

路径

字符串

组规格的 ID（键）。

spec

body

字符串

与指定键对应的组规格的值。

请求示例

{
    "key1": "value1"
}

响应参数

名称

入参

类型

描述

spec

body

字符串

与指定键对应的组规格的值。

响应示例

{
    "key1": "value1"
}
DELETE
/v3/{project_id}/group_types/{group_type_id}/group_specs/{spec_id}

删除组类型的特定组规格

删除组类型的组规格。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。
错误

代码

原因
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

group_type_id

路径

字符串

现有组类型的 UUID。

spec_id

路径

字符串

组规格的 ID（键）。

主机扩展 (os-hosts)

仅限管理员，取决于策略设置。

列出、显示主机。

GET
/v3/{admin_project_id}/os-hosts

列出项目的所有主机

列出所有未被禁用的主机摘要信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。

请求

名称

入参

类型

描述

admin_project_id

路径

字符串

管理员项目的 UUID。

响应参数

名称

入参

类型

描述

hosts

body

对象

OpenStack 块存储主机。

service-status

body

字符串

服务状态。可能的值为 available 或 unavailable。

服务

body

字符串

正在主机上运行的服务的名称。

zone

body

字符串

可用区名称。

service-state

body

字符串

服务状态。可能的值为 enabled 或 disabled。

host_name

body

字符串

托管存储后端的名称，可能采用 host@backend 的格式。

last-update

body

字符串

更新资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含，±hh:mm 值是 UTC 的时区偏移量。在前面的示例中，偏移量值为 -05:00。

如果未设置 updated_at 日期和时间戳，则其值为 null。

响应示例

{
    "hosts": [{
        "service-status": "available",
        "service": "cinder-backup",
        "zone": "nova",
        "service-state": "enabled",
        "host_name": "node1",
        "last-update": "2017-03-09T21:38:41.000000"
    },
    {
        "service-status": "available",
        "service": "cinder-scheduler",
        "zone": "nova",
        "service-state": "enabled",
        "host_name": "node1",
        "last-update": "2017-03-09T21:38:38.000000"
    },
    {
        "service-status": "available",
        "service": "cinder-volume",
        "zone": "nova",
        "service-state": "enabled",
        "host_name": "node1@lvm",
        "last-update": "2017-03-09T21:38:35.000000"
    }]
}
GET
/v3/{admin_project_id}/os-hosts/{host_name}

显示项目的主机详细信息

显示 cinder-volume 主机的卷和快照详细信息。

注意：此 API 专为 cinder-volume 主机设计。它不适用于其他 Cinder 服务主机或已禁用 cinder-volume 服务的主机。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

admin_project_id

路径

字符串

管理员项目的 UUID。

host_name

路径

字符串

托管存储后端的服务器的主机名称。

响应

名称

入参

类型

描述

host

body

对象

现有卷所在的 OpenStack 块存储主机。

volume_count

body

字符串

卷的总数。

total_volume_gb

body

字符串

已使用的 GiB（千兆字节）总量。

total_snapshot_gb

body

字符串

快照使用的总 GiB。

project

body

字符串

主机资源所属的项目 ID。在摘要资源中，值为 (total)。

host

body

字符串

托管存储后端的名称，可能采用 host@backend 的格式。

snapshot_count

body

字符串

已使用的快照总数。

响应示例

{
    "host": [{
            "resource": {
                "volume_count": "8",
                "total_volume_gb": "11",
                "total_snapshot_gb": "1",
                "project": "(total)",
                "host": "node1@rbd-sas",
                "snapshot_count": "1"
            }
        },
        {
            "resource": {
                "volume_count": "8",
                "total_volume_gb": "11",
                "total_snapshot_gb": "1",
                "project": "f21a9c86d7114bf99c711f4874d80474",
                "host": "node1@rbd-sas",
                "snapshot_count": "1"
            }
        }]
}

配额 (limits)

显示项目的绝对限制。

值为 -1 的绝对限制表示该项的绝对限制是无限的。

GET
/v3/{project_id}/limits

显示项目的绝对限制

显示项目的绝对限制。

值为 -1 的绝对限制表示该项的绝对限制是无限的。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
403 - 禁止

策略不允许当前用户执行此操作。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

响应参数

名称

入参

类型

描述

限制

body

对象

限制对象列表。

rate

body

数组

卷复制带宽速率限制，用于缓解实例数据访问速度变慢的问题。

absolute

body

对象

绝对限制对象。

totalSnapshotsUsed

body

整数

已使用的快照总数。

maxTotalBackups

body

整数

最大备份数量。

maxTotalVolumeGigabytes

body

整数

最大卷总量，以 GiB（千兆字节）为单位。

maxTotalSnapshots

body

整数

最大快照数量。

maxTotalBackupGigabytes

body

整数

备份总量的最大值，以 GiB（千兆字节）为单位。

totalBackupGigabytesUsed

body

整数

已使用的备份 GiB（千兆字节）总量。

maxTotalVolumes

body

整数

最大卷数量。

totalVolumesUsed

body

整数

已使用的卷总数。

totalBackupsUsed

body

整数

已使用的备份总数。

totalGigabytesUsed

body

整数

已使用的 GiB（千兆字节）总量。

响应示例

{
    "limits": {
        "rate": [],
        "absolute": {
            "totalSnapshotsUsed": 0,
            "maxTotalBackups": 10,
            "maxTotalVolumeGigabytes": 1000,
            "maxTotalSnapshots": 10,
            "maxTotalBackupGigabytes": 1000,
            "totalBackupGigabytesUsed": 0,
            "maxTotalVolumes": 10,
            "totalVolumesUsed": 0,
            "totalBackupsUsed": 0,
            "totalGigabytesUsed": 0
        }
    }
}

消息 (messages)

列出所有、显示和删除消息。这些是由于操作失败而生成的错误消息，用于了解异步操作失败的原因。

DELETE
/v3/{project_id}/messages/{message_id}

删除消息

删除消息。

响应码

成功

代码

原因
204 - No Content

请求已满足，但服务未返回任何内容。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

message_id

路径

字符串

消息的 UUID。
GET
/v3/{project_id}/messages/{message_id}

显示消息详细信息

显示消息的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

message_id

路径

字符串

消息的 UUID。

响应参数

名称

入参

类型

描述

message

body

字符串

对应于 event_id 的可读翻译消息。

request_id

body

字符串

消息创建期间请求的 ID。

links (可选)

body

数组

消息的链接。

message_level

body

字符串

消息级别，可能的值目前仅为“ERROR”。

event_id

body

字符串

此消息的事件 ID，此 ID 最终可以转换为 user_message。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

guaranteed_until (可选)

body

字符串

消息的过期时间，此消息可能在此时间后被删除。

resource_uuid (可选)

body

字符串

消息创建时操作的资源的 UUID。

id

body

字符串

消息的 UUID。

resource_type (可选)

body

字符串

与 resource_uuid 对应的资源类型。

user_message

body

字符串

对应于 event_id 的可读翻译消息。

响应示例

{
    "message": {
        "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
        "links": [
            {
                "href": "https://:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "self"
            },
            {
                "href": "https://:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "bookmark"
            }
        ],
        "message_level": "ERROR",
        "event_id": "VOLUME_000002",
        "created_at": "2014-10-28T00:00:00-00:00",
        "guaranteed_until": "2014-10-28T00:00:00-00:00",
        "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf",
        "id": "c506cd4b-9048-43bc-97ef-0d7dec369b42",
        "resource_type": "VOLUME",
        "user_message": "No storage could be allocated for this volume request."
    }
}
GET
/v3/{project_id}/messages

列出消息

列出所有消息。自 v3.31 起，如果非管理员用户在 URL 中指定了无效的过滤器，API 将返回错误请求。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

messages

body

字符串

用户消息集合。

request_id

body

字符串

消息创建期间请求的 ID。

links (可选)

body

数组

消息的链接。

message_level

body

字符串

消息级别，可能的值目前仅为“ERROR”。

event_id

body

字符串

此消息的事件 ID，此 ID 最终可以转换为 user_message。

created_at

body

字符串

创建资源的时间和日期。

日期和时间戳格式为 ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

例如，2015-08-27T09:49:58-05:00。

如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。

guaranteed_until (可选)

body

字符串

消息的过期时间，此消息可能在此时间后被删除。

resource_uuid (可选)

body

字符串

消息创建时操作的资源的 UUID。

id

body

字符串

消息的 UUID。

resource_type (可选)

body

字符串

与 resource_uuid 对应的资源类型。

user_message

body

字符串

对应于 event_id 的可读翻译消息。

响应示例

{
    "messages": [{
        "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
        "links": [
            {
                "href": "https://:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "self"
            },
            {
                "href": "https://:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "bookmark"
            }
        ],
        "message_level": "ERROR",
        "event_id": "VOLUME_000002",
        "created_at": "2014-10-28T00:00:00-00:00",
        "guaranteed_until": "2014-10-28T00:00:00-00:00",
        "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf",
        "id": "c506cd4b-9048-43bc-97ef-0d7dec369b42",
        "resource_type": "VOLUME",
        "user_message": "No storage could be allocated for this volume request."
    },{
        "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a",
        "links": [
            {
                "href": "https://:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "self"
            },
            {
                "href": "https://:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42",
                "rel": "bookmark"
            }
        ],
        "message_level": "ERROR",
        "event_id": "VOLUME_000002",
        "created_at": "2014-10-28T00:00:00-00:00",
        "guaranteed_until": "2014-10-28T00:00:00-00:00",
        "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4df4e",
        "id": "c506cd4b-9048-43bc-97ef-0d7dec36d5gt",
        "resource_type": "VOLUME",
        "user_message": "No storage could be allocated for this volume request."
    }]
}

资源过滤器 (resource_filters)

列出所有资源过滤器，自微版本 3.33 起可用。

GET
/v3/{project_id}/resource_filters

列出资源过滤器

列出过滤器。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

resource (可选)

查询

字符串

按资源名称过滤。

响应参数

名称

入参

类型

描述

resource_filters

body

数组

资源过滤器集合。

filters

body

数组

将应用过滤器的资源数组。

resource

body

字符串

将应用过滤器的资源。

响应示例

{
    "resource_filters": [
        {
            "filters": [
                "name",
                "status",
                "image_metadata", "bootable",
                "migration_status"
            ],
            "resource": "volume"
        },
        {
            "filters": [
                "name",
                "status",
                "volume_id"
            ],
            "resource": "snapshot"
        }
    ]
}

服务质量 (QoS) 规格 (qos-specs)

仅限管理员，取决于策略设置。

创建、列出、显示详细信息、关联、取消关联、设置键、取消设置键和删除服务质量 (QoS) 规格。

GET
/v3/{project_id}/qos-specs/{qos_id}/disassociate_all

取消 QoS 规格的所有关联

取消 QoS 规格的所有关联。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。
PUT
/v3/{project_id}/qos-specs/{qos_id}/delete_keys

取消 QoS 规格中的键

取消 QoS 规格中的键。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。

keys

body

数组

键列表。

请求示例

{
    "keys": [
        "key1"
    ]
}
GET
/v3/{project_id}/qos-specs/{qos_id}/associations

获取 QoS 规格的所有关联

列出 QoS 规格的所有关联。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。

响应

名称

入参

类型

描述

qos_associations

body

数组

QoS 关联对象集合。

type

body

字符串

QoS 关联类型。

id

body

字符串

QoS 关联 ID。

name

body

字符串

QoS 关联名称。

响应示例

{
    "qos_associations": []
}
GET
/v3/{project_id}/qos-specs/{qos_id}/associate

将 QoS 规格与卷类型关联

将 QoS 规格与卷类型关联。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。

vol_type_id

查询

字符串

卷类型的 ID。
GET
/v3/{project_id}/qos-specs/{qos_id}/disassociate

从卷类型取消关联 QoS 规格

从卷类型取消关联 QoS 规格。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。

vol_type_id

查询

字符串

卷类型的 ID。
GET
/v3/{project_id}/qos-specs/{qos_id}

显示 QoS 规格详细信息

显示 QoS 规格的详细信息。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
401 - 未授权

用户必须在发出请求之前进行身份验证。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。
405 - 方法不允许

该方法对于此端点和资源无效。
413 - 请求实体过大

无法完成此操作。
503 - 服务不可用

服务现在无法处理请求。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。

响应参数

名称

入参

类型

描述

qos_specs

body

对象

一个 qos_specs 对象。

specs

body

对象

一个 specs 对象。

consumer (可选)

body

字符串

消费者类型。

name

body

字符串

QoS 规格的名称。

id

body

字符串

QoS 规格的生成 ID。

links

body

数组

QoS 规格链接。

响应示例

{
    "qos_specs": {
        "specs": {},
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "0388d6c6-d5d4-42a3-b289-95205c50dd15"
    },
    "links": [
        {
            "href": "http://23.253.228.211:8776/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "self"
        },
        {
            "href": "http://23.253.228.211:8776/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/0388d6c6-d5d4-42a3-b289-95205c50dd15",
            "rel": "bookmark"
        }
    ]
}
PUT
/v3/{project_id}/qos-specs/{qos_id}

设置 QoS 规格中的键

设置 QoS 规格中的键。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。

qos_specs

body

对象

一个 qos_specs 对象。

请求示例

{
    "qos_specs": {
        "delay": "1"
    }
}

响应

名称

入参

类型

描述

qos_specs

body

对象

一个 qos_specs 对象。

响应示例

{
    "qos_specs": {
        "delay": "1"
    }
}
DELETE
/v3/{project_id}/qos-specs/{qos_id}

删除 QoS 规格

删除 QoS 规格。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_id

路径

字符串

QoS 规格的 ID。

force (可选)

查询

布尔值

即使 QoS 规格正在使用，也要将其删除，设置为 true。默认为 false。
POST
/v3/{project_id}/qos-specs

创建 QoS 规格

创建 QoS 规格。

在请求正文中指定一个或多个键值对。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

qos_specs

body

对象

一个 qos_specs 对象。

name

body

字符串

QoS 规格的名称。

请求示例

{
    "qos_specs": {
        "name": "reliability-spec"
    }
}

响应参数

名称

入参

类型

描述

qos_specs

body

对象

一个 qos_specs 对象。

name

body

字符串

QoS 规格的名称。

links

body

数组

QoS 规格链接。

id

body

字符串

QoS 规格的生成 ID。

consumer (可选)

body

字符串

消费者类型。

specs

body

对象

一个 specs 对象。

响应示例

{
    "qos_specs": {
        "specs": {},
        "consumer": "back-end",
        "name": "reliability-spec",
        "id": "599ef437-1c99-42ec-9fc6-239d0519fef1"
    },
    "links": [
        {
            "href": "http://23.253.248.171:8776/v3/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/599ef437-1c99-42ec-9fc6-239d0519fef1",
            "rel": "self"
        },
        {
            "href": "http://23.253.248.171:8776/89afd400-b646-4bbc-b12b-c0a4d63e5bd3/qos-specs/599ef437-1c99-42ec-9fc6-239d0519fef1",
            "rel": "bookmark"
        }
    ]
}
GET
/v3/{project_id}/qos-specs

列出 QoS 规格

列出服务质量 (QoS) 规格。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
300 - 多重选择

资源对应于多个表示形式。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

sort (可选)

查询

字符串

逗号分隔的排序键和可选的排序方向列表，格式为 `[: ]`。有效的方向是 `asc` (升序) 或 `desc` (降序)。

sort_key (可选)

查询

字符串

按属性排序。有效值为 `name`、`status`、`container_format`、`disk_format`、`size`、`id`、`created_at` 或 `updated_at`。默认为 `created_at`。API 使用 `sort_key` 属性值的自然排序方向。已弃用，推荐使用组合的 `sort` 参数。

sort_dir (可选)

查询

字符串

按一个或多个属性和排序方向的组合进行排序。如果省略组合中的排序方向，则默认为 `desc`。已弃用，推荐使用组合的 `sort` 参数。

limit (可选)

查询

整数

请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

offset (可选)

查询

整数

与 limit 结合使用以返回项目的切片。offset 是列表中的起始位置。

marker (可选)

查询

字符串

最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。

响应参数

名称

入参

类型

描述

qos_specs

body

对象

一个 qos_specs 对象。

specs

body

对象

一个 specs 对象。

consumer (可选)

body

字符串

消费者类型。

id

body

字符串

QoS 规格的生成 ID。

name

body

字符串

QoS 规格的名称。

响应示例

{
    "qos_specs": [
        {
            "consumer": "back-end",
            "id": "62c17294-2e52-4877-a01f-a30388749d9d",
            "name": "reliability-spec",
            "specs": {}
        }
    ]
}

配额类集扩展 (os-quota-class-sets)

仅限管理员，取决于策略设置。

显示和更新项目的配额类。

GET
/v3/{admin_project_id}/os-quota-class-sets/{quota_class_name}

显示项目的配额类

显示项目的配额类设置。如果配额类资源不存在特定值，则将报告默认值。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

quota_class_name

路径

字符串

要设置配额的配额类的名称。

admin_project_id

路径

字符串

管理员项目的 UUID。

响应参数

名称

入参

类型

描述

quota_class_set

body

对象

一个 quota_class_set 对象。

backup_gigabytes

body

整数

备份总量的最大值，以 GiB（千兆字节）为单位。

backups

body

整数

最大备份数量。

千兆字节

body

整数

最大卷总量，以 GiB（千兆字节）为单位。

gigabytes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷和快照的大小（GB）。

groups

body

整数

最大组数。

per_volume_gigabytes

body

整数

每个卷允许的卷大小（GB）。

快照

body

整数

最大快照数量。

snapshots_{volume_type}

body

整数

每个项目和指定卷类型允许的快照数量。

volumes

body

整数

最大卷数量。

volumes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷数量。

id

body

字符串

配额类集的名称。

响应示例

{
    "quota_class_set": {
        "backup_gigabytes": 1000,
        "backups": 10,
        "gigabytes": 1000,
        "gigabytes___DEFAULT__": -1,
        "groups": 10,
        "id": "test_class",
        "per_volume_gigabytes": -1,
        "snapshots": 10,
        "snapshots___DEFAULT__": -1,
        "volumes": 10,
        "volumes___DEFAULT__": -1
    }
}
PUT
/v3/{admin_project_id}/os-quota-class-sets/{quota_class_name}

更新项目的配额类

更新项目的配额类设置。如果 quota_class_name 键不存在，则 API 将创建一个。

响应码

成功

代码

原因
200 - 正常

请求成功。
错误

代码

原因
400 - 请求错误

请求中的某些内容无效。
403 - 禁止

策略不允许当前用户执行此操作。
404 - Not Found

找不到请求的资源。

请求

名称

入参

类型

描述

admin_project_id

路径

字符串

管理员项目的 UUID。

quota_class_name

路径

字符串

要设置配额的配额类的名称。

千兆字节

body

整数

最大卷总量，以 GiB（千兆字节）为单位。

gigabytes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷和快照的大小（GB）。

snapshots (可选)

body

整数

最大快照数量。

snapshots_{volume_type}

body

整数

每个项目和指定卷类型允许的快照数量。

volumes (可选)

body

整数

最大卷数量。

volumes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷数量。

请求示例

{
    "quota_class_set": {
        "volumes": 10,
        "gigabytes": 1000,
        "snapshots": 10
    }
}

响应参数

名称

入参

类型

描述

quota_class_set

body

对象

一个 quota_class_set 对象。

backup_gigabytes

body

整数

备份总量的最大值，以 GiB（千兆字节）为单位。

backups

body

整数

最大备份数量。

千兆字节

body

整数

最大卷总量，以 GiB（千兆字节）为单位。

gigabytes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷和快照的大小（GB）。

groups

body

整数

最大组数。

per_volume_gigabytes

body

整数

每个卷允许的卷大小（GB）。

快照

body

整数

最大快照数量。

snapshots_{volume_type}

body

整数

每个项目和指定卷类型允许的快照数量。

volumes

body

整数

最大卷数量。

volumes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷数量。

响应示例

{
    "quota_class_set": {
        "backup_gigabytes": 1000,
        "backups": 10,
        "gigabytes": 1000,
        "gigabytes___DEFAULT__": -1,
        "groups": 10,
        "per_volume_gigabytes": -1,
        "snapshots": 10,
        "snapshots___DEFAULT__": -1,
        "volumes": 10,
        "volumes___DEFAULT__": -1
    }
}

配额集扩展 (os-quota-sets)

仅限管理员，取决于策略设置。

显示、更新和删除项目的配额。

GET
/v3/{admin_project_id}/os-quota-sets/{project_id}

显示项目的配额

显示项目的配额。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

admin_project_id

路径

字符串

管理员项目的 UUID。

project_id

路径

字符串

多租户云中项目的 UUID。

usage (可选)

查询

布尔值

显示项目的配额使用信息。默认为 false。

响应参数

名称

入参

类型

描述

quota_set

body

对象

一个 quota_set 对象。

id

body

字符串

项目的 UUID。

volumes

body

整数

每个项目允许的卷数量。

volumes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷数量。

快照

body

整数

每个项目允许的快照数量。

snapshots_{volume_type}

body

整数

每个项目和指定卷类型允许的快照数量。

backups

body

整数

每个项目允许的备份数量。

groups

body

整数

每个项目允许的组数量。

per_volume_gigabytes

body

整数

每个卷允许的卷大小（GB）。

千兆字节

body

整数

每个项目允许的卷和快照的大小（GB）。

gigabytes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷和快照的大小（GB）。

backup_gigabytes

body

整数

每个项目允许的备份大小（GB）。

响应示例

{
    "quota_set": {
        "backup_gigabytes": 1000,
        "backups": 10,
        "gigabytes": 1000,
        "gigabytes___DEFAULT__": -1,
        "groups": 10,
        "id": "fake_tenant",
        "per_volume_gigabytes": -1,
        "snapshots": 10,
        "snapshots___DEFAULT__": -1,
        "volumes": 10,
        "volumes___DEFAULT__": -1
    }
}
GET
/v3/{admin_project_id}/os-quota-sets/{project_id}?{usage}=True

显示项目的配额使用情况

显示项目的配额使用情况。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

admin_project_id

路径

字符串

管理员项目的 UUID。

usage (可选)

查询

布尔值

显示项目的配额使用信息。默认为 false。

响应参数

名称

入参

类型

描述

quota_set

body

对象

一个 quota_set 对象。

id

body

字符串

项目的 UUID。

volumes

body

对象

此项目的卷使用信息，包括 in_use、limit 和 reserved 属性。

volumes_{volume_type}

body

对象

此项目和此卷类型的卷使用信息，包括 in_use、limit 和 reserved 属性。

快照

body

对象

此项目的快照使用信息，包括 in_use、limit 和 reserved 属性。

snapshots_{volume_type}

body

对象

此项目和此卷类型的快照使用信息，包括 in_use、limit 和 reserved 属性。

backups

body

对象

此项目的备份使用信息，包括 in_use、limit 和 reserved 属性。

groups

body

对象

此项目的组使用信息，包括 in_use、limit 和 reserved 属性。

per_volume_gigabytes

body

对象

每个卷的大小（GB）使用信息，包括 in_use、limit 和 reserved 属性。

千兆字节

body

对象

此项目的卷和快照的大小（GB）使用信息，包括 in_use、limit 和 reserved 属性。

gigabytes_{volume_type}

body

对象

此项目和此卷类型的卷和快照的 (GB) 使用量信息，包括 in_use、limit 和 reserved 属性。

backup_gigabytes

body

对象

此项目的备份的 (GB) 使用量信息，包括 in_use、limit 和 reserved 属性。

响应示例

{
    "quota_set": {
        "backup_gigabytes": {
            "in_use": 0,
            "limit": 1000,
            "reserved": 0
        },
        "backups": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "gigabytes": {
            "in_use": 0,
            "limit": 1000,
            "reserved": 0
        },
        "gigabytes___DEFAULT__": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "groups": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "id": "fake_tenant",
        "per_volume_gigabytes": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "snapshots": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "snapshots___DEFAULT__": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        },
        "volumes": {
            "in_use": 0,
            "limit": 10,
            "reserved": 0
        },
        "volumes___DEFAULT__": {
            "in_use": 0,
            "limit": -1,
            "reserved": 0
        }
    }
}
PUT
/v3/{admin_project_id}/os-quota-sets/{project_id}

更新项目的配额

更新项目的配额。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

admin_project_id

路径

字符串

管理员项目的 UUID。

project_id

路径

字符串

多租户云中项目的 UUID。

quota_set

body

对象

一个 quota_set 对象。

volumes

body

整数

每个项目允许的卷数量。

volumes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷数量。

快照

body

整数

每个项目允许的快照数量。

snapshots_{volume_type}

body

整数

每个项目和指定卷类型允许的快照数量。

backups

body

整数

每个项目允许的备份数量。

groups

body

整数

每个项目允许的组数量。

per_volume_gigabytes

body

整数

每个卷允许的卷大小（GB）。

千兆字节

body

整数

每个项目允许的卷和快照的大小（GB）。

gigabytes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷和快照的大小（GB）。

backup_gigabytes

body

整数

每个项目允许的备份大小（GB）。

请求示例

{
    "quota_set":{
        "groups": 11,
        "volumes": 5,
        "backups": 4
    }
}

响应参数

名称

入参

类型

描述

quota_set

body

对象

一个 quota_set 对象。

volumes

body

整数

每个项目允许的卷数量。

volumes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷数量。

快照

body

整数

每个项目允许的快照数量。

snapshots_{volume_type}

body

整数

每个项目和指定卷类型允许的快照数量。

backups

body

整数

每个项目允许的备份数量。

groups

body

整数

每个项目允许的组数量。

per_volume_gigabytes

body

整数

每个卷允许的卷大小（GB）。

千兆字节

body

整数

每个项目允许的卷和快照的大小（GB）。

gigabytes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷和快照的大小（GB）。

backup_gigabytes

body

整数

每个项目允许的备份大小（GB）。

响应示例

{
    "quota_set": {
        "backup_gigabytes": 1000,
        "backups": 4,
        "gigabytes": 1000,
        "gigabytes___DEFAULT__": -1,
        "groups": 11,
        "per_volume_gigabytes": -1,
        "snapshots": 10,
        "snapshots___DEFAULT__": -1,
        "volumes": 5,
        "volumes___DEFAULT__": -1
    }
}
DELETE
/v3/{admin_project_id}/os-quota-sets/{project_id}

删除项目配额

删除项目配额，使配额恢复到默认值。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

admin_project_id

路径

字符串

管理员项目的 UUID。
GET
/v3/{admin_project_id}/os-quota-sets/{project_id}/defaults

获取项目默认配额

获取项目默认配额。

响应码

成功

代码

原因
200 - 正常

请求成功。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

admin_project_id

路径

字符串

管理员项目的 UUID。

响应参数

名称

入参

类型

描述

quota_set

body

对象

一个 quota_set 对象。

id

body

字符串

项目的 UUID。

volumes

body

整数

每个项目允许的卷数量。

volumes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷数量。

快照

body

整数

每个项目允许的快照数量。

snapshots_{volume_type}

body

整数

每个项目和指定卷类型允许的快照数量。

backups

body

整数

每个项目允许的备份数量。

groups

body

整数

每个项目允许的组数量。

per_volume_gigabytes

body

整数

每个卷允许的卷大小（GB）。

千兆字节

body

整数

每个项目允许的卷和快照的大小（GB）。

gigabytes_{volume_type}

body

整数

每个项目和指定卷类型允许的卷和快照的大小（GB）。

backup_gigabytes

body

整数

每个项目允许的备份大小（GB）。

响应示例

{
    "quota_set": {
        "backup_gigabytes": 1000,
        "backups": 10,
        "gigabytes": 1000,
        "gigabytes___DEFAULT__": -1,
        "groups": 10,
        "id": "fake_tenant",
        "per_volume_gigabytes": -1,
        "snapshots": 10,
        "snapshots___DEFAULT__": -1,
        "volumes": 10,
        "volumes___DEFAULT__": -1
    }
}

Workers (workers)

POST
v3/{project_id}/workers/cleanup

清理服务

请求清理服务，可选择性过滤。此 API 仅在微版本 3.24 或更高版本中可用。

响应码

成功

代码

原因
202 - Accepted

请求已接受，但处理可能需要一些时间。

请求

名称

入参

类型

描述

project_id

路径

字符串

多租户云中项目的 UUID。

cluster_name (可选)

body

字符串

资源所在的 OpenStack 块存储集群。如果提供了 host 字段，则此字段为可选。

service_id (可选)

body

整数

清理服务的 UUID。

host

body

字符串

正在主机上运行的服务的名称。

binary

body

字符串

服务的二进制名称。

is-up (可选)

body

布尔值

按 up/down 状态过滤。请参阅 有效布尔值

disabled (可选)

body

布尔值

按禁用状态过滤。请参阅 有效布尔值

resource-id (可选)

body

字符串

待清理资源的 UUID。

resource-type (可选)

body

字符串

与 resource_uuid 对应的资源类型。

请求示例

{
    "cluster_name": "test",
    "disabled": true,
    "host": "host1@lvmdriver",
    "service_id": 1,
    "is_up": true,
    "binary": "cinder-volume",
    "resource_id": "b122f668-d15a-40f8-af21-38d218796ab8",
    "resource_type": "Volume"
}

响应参数

名称

入参

类型

描述

host

body

字符串

正在主机上运行的服务的名称。

binary

body

字符串

服务的二进制名称。

id (可选)

body

整数

清理服务的 UUID。

cluster_name (可选)

body

字符串

资源所在的 OpenStack 块存储集群。如果提供了 host 字段，则此字段为可选。

响应示例

{
    "cleaning": [
        {
            "id": 1,
            "host": "host1@lvmdriver",
            "binary": "cinder-volume",
            "cluster_name": "test"
        }
    ],
    "unavailable": []
}

有效布尔值

以下是布尔参数的有效值列表。

[True, ‘True’, ‘TRUE’, ‘true’, ‘1’, ‘ON’, ‘On’, ‘on’, ‘YES’, ‘Yes’, ‘yes’, ‘y’, ‘t’, False, ‘False’, ‘FALSE’, ‘false’, ‘0’, ‘OFF’, ‘Off’, ‘off’, ‘NO’, ‘No’, ‘no’, ‘n’, ‘f’]