Placement API

这是 OpenStack Placement API 的参考。要了解有关 OpenStack Placement API 概念的更多信息，请参阅Placement 简介。

Placement API 使用 JSON 进行数据交换。因此，发送数据负载到请求体中的 API（即 PUT 和 POST）的 Content-Type 头部必须设置为 application/json，除非另有说明。

显示全部

请求 ID

默认情况下，系统上的所有日志都包含全局请求 ID 和本地请求 ID（如果可用）。本地请求 ID 是每个服务本地生成的唯一 ID，因此在该操作中涉及的每个服务（Nova、Cinder、Glance、Neutron 等）都不同。格式为 req- + UUID (UUID4)。全局请求 ID 是用户指定的请求 ID，用作所有服务的通用标识符。此请求 ID 在该操作中涉及的所有服务中都相同。格式为 req- + UUID (UUID4)。这允许管理员跟踪 API 请求的处理，因为它在所有不同的 nova 服务之间或在 Nova 和 Nova 在该请求中调用的其他组件服务之间进行转换。

即使在请求中指定了全局请求 ID，用户始终会收到一个本地请求 ID 作为响应。

有关请求 ID 的更多详细信息，请参考：错误（它不适用于 Placement API，但有一些共同点。）

请求

名称	入参	类型	描述
X-Openstack-Request-Id (可选)	标头	字符串	全局请求 ID，它是 OpenStack 组件中用于跟踪每个请求的唯一通用 ID。全局请求 ID 的格式必须是 req- + UUID (UUID4)。如果不符合该格式，则会被忽略。它与请求关联并出现在该请求的日志行中。默认情况下，中间件配置确保全局请求 ID 出现在日志文件中。

响应

名称	入参	类型	描述
X-Openstack-Request-Id	标头	字符串	本地请求 ID，它是自动生成的唯一 ID，用于跟踪每个对 placement 的请求。它与请求关联并出现在该请求的日志行中。默认情况下，中间件配置确保本地请求 ID 出现在日志文件中。

错误

当与 placement API 交互时发生错误，响应将包含一些不同的信号来指示哪里出了问题，包括状态头部和响应体中的信息。JSON 错误响应体的结构由 OpenStack 错误指南定义。

HTTP 状态码

响应的 Status 头部将包含一个代码，由RFC 7231 第 6 节定义，该代码提供了问题的总体概述。此值也出现在响应体的 status 属性中。

详细信息

错误情况的文本描述，位于 detail 属性中。该值通常是服务内部发生的任何异常关联的消息。

错误代码

当微版本为 >=1.23 时，响应还将包含 JSON 主体中的 code 属性。这些将在下面进行记录。如果响应未使用特定代码，则显示 placement.undefined_code。

注意

在某些情况下，例如当使用 keystone 且请求中未提供身份验证信息（导致 401 响应）时，错误响应的结构将与上述不符，因为错误是由 placement 服务之外的代码产生的。

错误代码

定义的错误是

代码	含义
placement.undefined_code	当未定义或不需要特定代码时使用的默认代码。
placement.inventory.inuse	已尝试删除或缩减正在使用的容量的库存。
placement.concurrent_update	另一个操作已同时发出了一个请求，该请求涉及此请求中引用的一项或多项相同资源，从而改变了状态。应检索当前状态以确定是否应重试所需的 операции。
placement.duplicate_name	此类型的资源已存在同名，不允许重复名称。
placement.resource_provider.inuse	尝试删除资源提供者，但其库存存在分配。
placement.resource_provider.cannot_delete_parent	尝试删除资源提供者，但其拥有一项或多项子提供者。必须先删除它们才能删除此提供者。
placement.resource_provider.not_found	在涉及多个资源提供者的操作（例如Reshaper）中提及的资源提供者不存在。
placement.query.duplicate_key	请求中包含了只能指定一次的查询参数的多个实例。
placement.query.bad_value	请求中的值符合 schema，但语义验证失败。
placement.query.missing_value	请求中缺少必需的查询参数。

资源提供者和消费者代

Placement 通过为资源提供者和消费者维护一个代来处理针对同一实体的并发请求。代是一个不透明的值，每次其实体在服务器上成功更改时都会更新。

在适当的微版本中，代在涉及资源提供者和/或消费者（分配）的响应中返回，并且必须包含在对这些实体进行更改的请求中。服务器会检查以确保请求中指定的代与内部值匹配。不匹配表示在中间有另一个请求成功更新了该实体，从而改变了其代。这将导致 HTTP 409 Conflict 响应，并带错误代码 placement.concurrent_update。

根据使用场景，对这种错误的一种适当反应可能是重新 GET 相关的实体，重新评估并进行适当更新，然后使用新的负载重新提交请求。

以下伪代码是说明如何确保在资源提供者上设置一个特性的简单示例。

注意

这不是生产代码。除了不是任何特定编程语言的有效语法外，它故意忽略了详细信息和良好的编程实践，例如错误检查、重试限制等。它纯粹是为了说明目的。

function _is_concurrent_update(resp) {
    if(resp.status_code != 409) return False
    return(resp.json()["errors"][0]["code"] == "placement.concurrent_update")
}

function ensure_trait_on_provider(provider_uuid, trait) {
    do {
        path = "/resource_providers/" + provider_uuid + "/traits"
        get_resp = placement.GET(path)
        payload = get_resp.json()
        if(trait in payload["traits"]) return
        payload["traits"].append(trait)
        put_resp = placement.PUT(path, payload)
    } while _is_concurrent_update(put_resp)
}

API 版本

为了随着时间的推移为用户带来新功能，Placement API 支持微版本化。微版本允许通过 OpenStack-API-Version 头部按请求使用某些功能。例如，要请求微版本 1.10，请指定头部

OpenStack-API-Version: placement 1.10

有关微版本的更多详细信息，请参考：微版本规范

注意

每个版本支持的最大微版本各不相同。请参考：REST API 版本历史以获取 API 微版本历史详细信息。

GET

/

列出版本

详情

获取有关 Placement API 所有已知主要版本的信息，包括有关最小和最大微版本的信息。

注意

目前，Placement API 只有一个主要版本：版本 1.0。

正常响应代码：200

响应

名称	入参	类型	描述
versions	body	数组	一个描述可用 API 版本的版本对象列表。
id	body	字符串	正在描述的版本的通用名称。仅供参考。
min_version	body	字符串	支持的最小微版本。
max_version	body	字符串	支持的最大微版本。
status	body	字符串	正在描述的版本的状态。在 placement 中，这是“CURRENT”。
links	body	数组	与此版本相关的链接列表。

响应示例

{
    "versions" : [
        {
            "min_version" : "1.0",
            "id" : "v1.0",
            "max_version" : "1.28",
            "status": "CURRENT",
            "links": [
                {
                    "href": "",
                    "rel": "self"
                }
            ]
        }
    ]
}

资源提供者

资源提供者是提供一种或多种资源类别（例如磁盘或内存）的可消耗库存的实体。它们可以被列出（带过滤器）、创建、更新和删除。

GET

/resource_providers

列出资源提供程序

详情

列出可选过滤的资源提供者集合。

正常响应代码：200

错误响应代码：badRequest(400)

如果在 resources 请求参数中指定的资源类别不存在，则会返回 400 BadRequest 响应代码。

请求

可以使用多个查询参数来过滤返回的资源提供者列表。如果提供了多个不同的参数，则所有过滤器的结果将通过布尔 AND 合并。

名称	入参	类型	描述
name (可选)	查询	字符串	用于过滤列表的资源提供者名称。
uuid (可选)	查询	字符串	资源提供者的 UUID。
member_of (可选)	查询	字符串	表示聚合 UUID 的字符串；或前缀 in: 后跟逗号分隔的表示聚合 UUID 的字符串列表。返回的资源提供者必须直接与由 UUID 标识的至少一个聚合关联 member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa 从微版本 1.24 开始，可以指定多个 member_of 查询字符串参数。多个 member_of 参数将导致过滤与所有 member_of 查询字符串值中列出的聚合关联的提供者。例如，要获取与聚合 A 以及与聚合 B 或 C 中的任何一个关联的提供者，用户可以发出以下查询 member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID 从微版本 1.32 开始，member_of 查询字符串参数支持指定禁止的聚合。禁止的聚合以 ! 为前缀。此否定表达式也可以在多个 member_of 参数中使用 member_of=AGGA_UUID&member_of=!AGGB_UUID 在逻辑上将翻译为“候选资源提供者必须在 AGGA 中，并且不在 AGGB 中。”我们不支持 ! 在 in: 内的值上，但我们支持 !in:。以下两个示例查询都返回不在 AGGA、AGGB 或 AGGC 中的候选资源提供者 member_of=!in:AGGA_UUID,AGGB_UUID,AGGC_UUID member_of=!AGGA_UUID&member_of=!AGGB_UUID&member_of=!AGGC_UUID 我们不检查同一个聚合 UUID 是否同时存在于肯定和否定表达式中，以返回 400 BadRequest。在这种情况下，我们仍然返回 200。例如 member_of=AGGA_UUID&member_of=!AGGA_UUID 将返回一个空列表的 resource_providers，而 member_of=in:AGGA_UUID,AGGB_UUID&member_of=!AGGA_UUID 将返回不在AGGA中但在AGGB中的资源提供者。 1.3 版中的新功能
resources (可选)	查询	字符串	逗号分隔的字符串列表，指示提供者必须具有容量和可用性以提供指定类别的资源数量 resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048 请注意，该数量必须是大于 0 的整数。 1.4 版中的新功能
in_tree (可选)	查询	字符串	资源提供者的 UUID。返回的资源提供者将位于与指定提供者相同的“提供者树”中。 1.14 版中的新功能
required (可选)	查询	字符串	逗号分隔的字符串特性名称列表。结果将进行过滤，只包含具有所有指定特性的资源提供者。从微版本 1.22 开始，可以通过在特性前加上 ! 来表示禁止任何资源提供者具有的特性。 从微版本 1.39 开始，required 查询参数可以重复。重复参数的特性列表将进行 AND 运算。因此 required=T1,!T2&required=T3 表示 T1 且非 T2 且 T3。 此外，从微版本 1.39 开始，required 参数支持以下语法 required=in:T1,T2,T3 这意味着 T1 或 T2 或 T3。 不支持将禁止特性混入 in: 前缀值中并会被拒绝。但在同一个请求中，将普通特性列表和 in: 前缀特性列表混入两个查询参数中是支持的。所以 required=in:T3,T4&required=T1,!T2 受支持，它表示 T1 且非 T2 且 (T3 或 T4)。 1.18 版中的新功能

响应

名称	入参	类型	描述
resource_providers	body	数组	一个 resource_provider 对象列表。
generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
uuid	body	字符串	资源提供者的 UUID。
links	body	数组	与一个资源提供者相关联的链接列表。 注意 聚合关系链接从版本 1.1 开始可用。特性关系链接从版本 1.6 开始可用。分配关系链接从版本 1.11 开始可用。
name	body	字符串	一个资源提供者的名称。
parent_provider_uuid	body	字符串	资源提供者直接父级的 UUID。 1.14 版中的新功能
root_provider_uuid	body	字符串	此提供者树中最高级提供者的只读 UUID。 1.14 版中的新功能

响应示例

{
  "resource_providers": [
    {
      "generation": 1,
      "uuid": "99c09379-6e52-4ef8-9a95-b9ce6f68452e",
      "links": [
        {
          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e",
          "rel": "self"
        },
        {
          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/aggregates",
          "rel": "aggregates"
        },
        {
          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/inventories",
          "rel": "inventories"
        },
        {
          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/usages",
          "rel": "usages"
        },
        {
          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/traits",
          "rel": "traits"
        },
        {
          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/allocations",
          "rel": "allocations"
        }
      ],
      "name": "vgr.localdomain",
      "parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
      "root_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
    },
    {
      "generation": 2,
      "uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5",
      "links": [
        {
          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5",
          "rel": "self"
        },
        {
          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/aggregates",
          "rel": "aggregates"
        },
        {
          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/inventories",
          "rel": "inventories"
        },
        {
          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/usages",
          "rel": "usages"
        },
        {
          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/traits",
          "rel": "traits"
        },
        {
          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/allocations",
          "rel": "allocations"
        }
      ],
      "name": "pony1",
      "parent_provider_uuid": null,
      "root_provider_uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5"
    }
  ]
}

POST

/resource_providers

创建资源提供者

详情

创建一个新的资源提供者。

正常响应代码：201（微版本 1.0 - 1.19），200（微版本 1.20 - ）

错误响应代码：conflict(409)

如果存在另一个具有所提供名称或 UUID 的资源提供者，则将返回 409 Conflict 响应代码。

请求

名称	入参	类型	描述
name	body	字符串	一个资源提供者的名称。
uuid (可选)	body	字符串	资源提供者的 UUID。
parent_provider_uuid (可选)	body	字符串	资源提供者直接父级的 UUID。 在版本 1.37 之前，一旦设置，资源提供者的父级就不能更改。 自版本 1.37 以来，它可以设置为任何现有的提供者 UUID，除了会导致循环的提供者。它也可以设置为空，将提供者转换为新的根提供者。此操作需要谨慎使用。移动提供者可能意味着用于创建现有资源分配的原始规则可能因该移动而失效。 1.14 版中的新功能

请求示例

{
    "name": "NFS Share",
    "uuid": "7d2590ae-fb85-4080-9306-058b4c915e3f",
    "parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}

响应（微版本 1.0 - 1.19）

名称	入参	类型	描述
位置	标头	字符串	将返回创建资源的位置 URL，HTTP 头部“Location: <Location URL>”。

成功 POST 后不返回任何主体内容。

响应（微版本 1.20 - ）

名称	入参	类型	描述
位置	标头	字符串	将返回创建资源的位置 URL，HTTP 头部“Location: <Location URL>”。
generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
uuid	body	字符串	资源提供者的 UUID。
links	body	数组	与资源提供者关联的链接列表。
name	body	字符串	一个资源提供者的名称。
parent_provider_uuid	body	字符串	资源提供者直接父级的 UUID。
root_provider_uuid	body	字符串	此提供者树中最高级提供者的 UUID。

响应示例（微版本 1.20 - ）

{
    "generation": 0,
    "links": [
        {
            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f",
            "rel": "self"
        },
        {
            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/aggregates",
            "rel": "aggregates"
        },
        {
            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/inventories",
            "rel": "inventories"
        },
        {
            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/usages",
            "rel": "usages"
        },
        {
            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/traits",
            "rel": "traits"
        },
        {
            "href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/allocations",
            "rel": "allocations"
        }
    ],
    "name": "NFS Share",
    "uuid": "7d2590ae-fb85-4080-9306-058b4c915e3f",
    "parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
    "root_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}

资源提供者

有关描述，请参阅资源提供者。这组 API 调用使用由 uuid 标识的单个资源提供者。一个资源提供者可以被列出、更新和删除。

GET

/resource_providers/{uuid}

显示资源提供者

详情

返回由 {uuid} 标识的资源提供者的表示。

正常响应代码：200

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

名称	入参	类型	描述
generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
uuid	body	字符串	资源提供者的 UUID。
links	body	数组	与一个资源提供者相关联的链接列表。 注意 聚合关系链接从版本 1.1 开始可用。特性关系链接从版本 1.6 开始可用。分配关系链接从版本 1.11 开始可用。
name	body	字符串	一个资源提供者的名称。
parent_provider_uuid	body	字符串	资源提供者直接父级的 UUID。 1.14 版中的新功能
root_provider_uuid	body	字符串	此提供者树中最高级提供者的只读 UUID。 1.14 版中的新功能

响应示例

{
    "generation": 0,
    "links": [
        {
            "href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868",
            "rel": "self"
        },
        {
            "href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/aggregates",
            "rel": "aggregates"
        },
        {
            "href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/inventories",
            "rel": "inventories"
        },
        {
            "href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/usages",
            "rel": "usages"
        },
        {
            "href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/traits",
            "rel": "traits"
        },
        {
            "href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/allocations",
            "rel": "allocations"
        }
    ],
    "name": "Ceph Storage Pool",
    "uuid": "3b4005be-d64b-456f-ba36-0ffd02718868",
    "parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
    "root_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}

PUT

/resource_providers/{uuid}

更新资源提供者

详情

更新由 {uuid} 标识的资源提供者的名称。

正常响应代码：200

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

如果存在另一个具有所提供名称的资源提供者，则将返回 409 Conflict 响应代码。

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
name	body	字符串	一个资源提供者的名称。
parent_provider_uuid (可选)	body	字符串	资源提供者直接父级的 UUID。 在版本 1.37 之前，一旦设置，资源提供者的父级就不能更改。 自版本 1.37 以来，它可以设置为任何现有的提供者 UUID，除了会导致循环的提供者。它也可以设置为空，将提供者转换为新的根提供者。此操作需要谨慎使用。移动提供者可能意味着用于创建现有资源分配的原始规则可能因该移动而失效。 1.14 版中的新功能

请求示例

 {
     "name": "Shared storage",
     "parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
 }

响应

名称	入参	类型	描述
generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
uuid	body	字符串	资源提供者的 UUID。
links	body	数组	与一个资源提供者相关联的链接列表。 注意 聚合关系链接从版本 1.1 开始可用。特性关系链接从版本 1.6 开始可用。分配关系链接从版本 1.11 开始可用。
name	body	字符串	一个资源提供者的名称。
parent_provider_uuid	body	字符串	资源提供者直接父级的 UUID。 1.14 版中的新功能
root_provider_uuid	body	字符串	此提供者树中最高级提供者的只读 UUID。 1.14 版中的新功能

响应示例

{
    "generation": 0,
    "links": [
        {
            "href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f",
            "rel": "self"
        },
        {
            "href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/aggregates",
            "rel": "aggregates"
        },
        {
            "href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/inventories",
            "rel": "inventories"
        },
        {
            "href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/usages",
            "rel": "usages"
        },
        {
            "href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/traits",
            "rel": "traits"
        },
        {
            "href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/allocations",
            "rel": "allocations"
        }
    ],
    "name": "Shared storage",
    "uuid": "33f26ae0-dbf2-485b-a24a-244d8280e29f",
    "parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
    "root_provider_uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5"
}

DELETE

/resource_providers/{uuid}

删除资源提供者

详情

删除由 {uuid} 标识的资源提供者。此操作还将取消关联聚合并删除库存。

正常响应代码：204

错误响应代码：itemNotFound(404), conflict(409)

如果由于删除资源提供者而将删除的任何库存存在分配记录，则将返回 409 Conflict 响应代码。

如果要删除的父资源提供者下存在子资源提供者，也将返回此错误代码。

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

成功删除后不返回正文内容。

资源类别

资源类别是表示资源提供者可以提供的标准或部署者特定资源的实体。

注意

资源类别 API 调用从版本 1.2 开始可用。

GET

/resource_classes

列出资源类别

详情

返回所有资源类的列表。

正常响应代码：200

Response

名称	入参	类型	描述
resource_classes	body	数组	一个 resource_class 对象列表。
links	body	数组	与一个资源类别关联的链接列表。
name	body	字符串	一个资源类别的名称。

响应示例

{
    "resource_classes": [
        {
            "links": [
                {
                    "href": "/placement/resource_classes/VCPU",
                    "rel": "self"
                }
            ],
            "name": "VCPU"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/MEMORY_MB",
                    "rel": "self"
                }
            ],
            "name": "MEMORY_MB"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/DISK_GB",
                    "rel": "self"
                }
            ],
            "name": "DISK_GB"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/PCI_DEVICE",
                    "rel": "self"
                }
            ],
            "name": "PCI_DEVICE"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/SRIOV_NET_VF",
                    "rel": "self"
                }
            ],
            "name": "SRIOV_NET_VF"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/NUMA_SOCKET",
                    "rel": "self"
                }
            ],
            "name": "NUMA_SOCKET"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/NUMA_CORE",
                    "rel": "self"
                }
            ],
            "name": "NUMA_CORE"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/NUMA_THREAD",
                    "rel": "self"
                }
            ],
            "name": "NUMA_THREAD"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/NUMA_MEMORY_MB",
                    "rel": "self"
                }
            ],
            "name": "NUMA_MEMORY_MB"
        },
        {
            "links": [
                {
                    "href": "/placement/resource_classes/IPV4_ADDRESS",
                    "rel": "self"
                }
            ],
            "name": "IPV4_ADDRESS"
        }
    ]
}

POST

/resource_classes

创建资源类别

详情

创建一个新的资源类别。新类别必须是自定义资源类别，以 CUSTOM_ 为前缀，并与标准资源类别不同。

正常响应代码：201

错误响应代码：badRequest(400), conflict(409)

如果资源类别没有前缀 CUSTOM_，则返回 400 BadRequest 响应代码。

如果存在另一个具有所提供名称的资源类别，则将返回 409 Conflict 响应代码。

请求

名称	入参	类型	描述
name	body	字符串	一个资源类别的名称。名称必须以 CUSTOM_ 前缀开头。否则，请求将返回 Bad Request (400) 响应代码。

请求示例

{"name": "CUSTOM_FPGA"}

响应

名称	入参	类型	描述
位置	标头	字符串	将返回创建资源的位置 URL，HTTP 头部“Location: <Location URL>”。

成功 POST 后不返回任何主体内容。

资源类别

有关描述，请参阅资源类别。这组 API 调用使用由 name 标识的单个资源类别。一个资源类别可以被列出、更新和删除。

注意

资源类别 API 调用从版本 1.2 开始可用。

GET

/resource_classes/{name}

显示资源类别

详情

返回由 {name} 标识的资源类别的表示。

正常响应代码：200

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
name	路径	字符串	一个资源类别的名称。

响应

名称	入参	类型	描述
name	body	字符串	一个资源类别的名称。
links	body	数组	与一个资源类别关联的链接列表。

响应示例

{
    "links": [
        {
            "href": "/placement/resource_classes/CUSTOM_FPGA",
            "rel": "self"
        }
    ],
    "name": "CUSTOM_FPGA"
}

PUT

/resource_classes/{name}

更新资源类别

详情

创建或验证由 {name} 标识的单个资源类别的存在。

注意

该方法从版本 1.7 开始可用。

正常响应代码：201, 204

如果新资源类别成功创建，则返回 201 Created 响应代码。如果资源类别已存在，则返回 204 No Content 响应代码。

错误响应代码：badRequest(400)

Request

名称	入参	类型	描述
name	路径	字符串	一个资源类别的名称。名称必须以 CUSTOM_ 前缀开头。否则，请求将返回 Bad Request (400) 响应代码。

响应

名称	入参	类型	描述
位置	标头	字符串	将返回创建资源的位置 URL，HTTP 头部“Location: <Location URL>”。

成功 PUT 后不返回任何主体内容。

PUT

/resource_classes/{name}

更新资源类别（微版本 1.2 - 1.6）

详情

警告

强烈不建议使用 <1.7 微版本更改资源类别名称。

更新由 {name} 标识的资源类别的名称。

正常响应代码：200

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

如果存在另一个具有所提供名称的资源类别，则将返回 409 Conflict 响应代码。

Request

名称	入参	类型	描述
name	路径	字符串	一个资源类别的名称。
name	body	字符串	一个资源类别的名称。名称必须以 CUSTOM_ 前缀开头。否则，请求将返回 Bad Request (400) 响应代码。

请求示例

{"name": "CUSTOM_FPGA_V2"}

响应

名称	入参	类型	描述
name	body	字符串	一个资源类别的名称。
links	body	数组	与一个资源类别关联的链接列表。

响应示例

{
    "links": [
        {
            "href": "/placement/resource_classes/CUSTOM_FPGA_V2",
            "rel": "self"
        }
    ],
    "name": "CUSTOM_FPGA_V2"
}

DELETE

/resource_classes/{name}

删除资源类别

详情

删除由 {name} 标识的资源类别。

正常响应代码：204

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

如果尝试删除标准资源类别，则返回 400 BadRequest 响应代码。

如果该资源类别存在库存，则返回 409 Conflict 响应代码。

请求

名称	入参	类型	描述
name	路径	字符串	一个资源类别的名称。

Response

成功删除后不返回正文内容。

资源提供者库存

每个资源提供者都拥有一种或多种资源类别的库存记录。库存记录包含有关资源的总量和保留量以及该资源对提供者的任何消耗约束的信息。

GET

/resource_providers/{uuid}/inventories

列出资源提供者库存

详情

正常响应代码：200

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

名称	入参	类型	描述
inventories	body	对象	一个以资源类别为键的库存字典。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
allocation_ratio	body	float	它用于确定提供者的资源消耗是否可以超过物理约束。 例如，对于 vCPU 资源，如果 allocation_ratio = 16.0 total = 8 总容量等于 128 vCPU。
max_unit	body	整数	库存可以拥有的最大分配量。
min_unit	body	整数	库存可以拥有的最小分配量。
reserved	body	整数	提供程序为其自身用途保留的资源的量。
step_size	body	整数	可以请求的资源的整除量表示。例如，step_size = 5 表示只能请求可被 5 整除的值（5、10、15 等）。
total	body	整数	提供程序可以容纳的资源的实际量。

响应示例

{
    "inventories": {
        "DISK_GB": {
            "allocation_ratio": 1.0,
            "max_unit": 35,
            "min_unit": 1,
            "reserved": 0,
            "step_size": 1,
            "total": 35
        },
        "MEMORY_MB": {
            "allocation_ratio": 1.5,
            "max_unit": 5825,
            "min_unit": 1,
            "reserved": 512,
            "step_size": 1,
            "total": 5825
        },
        "VCPU": {
            "allocation_ratio": 16.0,
            "max_unit": 4,
            "min_unit": 1,
            "reserved": 0,
            "step_size": 1,
            "total": 4
        }
    },
    "resource_provider_generation": 7
}

PUT

/resource_providers/{uuid}/inventories

更新资源提供者库存

详情

替换由 {uuid} 标识的资源提供者的库存记录集。

正常响应代码：200

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
inventories	body	对象	一个以资源类别为键的库存字典。
total	body	整数	提供程序可以容纳的资源的实际量。
allocation_ratio (可选)	body	float	它用于确定提供者的资源消耗是否可以超过物理约束。 例如，对于 vCPU 资源，如果 allocation_ratio = 16.0 total = 8 总容量等于 128 vCPU。
max_unit (可选)	body	整数	库存可以拥有的最大分配量。
min_unit (可选)	body	整数	库存可以拥有的最小分配量。
reserved (可选)	body	整数	提供者为其自身使用保留的资源数量。在微版本 1.25 之前，此值必须小于 total 的值。从微版本 1.26 开始，此值必须小于或等于 total 的值。
step_size (可选)	body	整数	可以请求的资源的整除量表示。例如，step_size = 5 表示只能请求可被 5 整除的值（5、10、15 等）。

请求示例

{
    "inventories": {
        "MEMORY_MB": {
            "allocation_ratio": 2.0,
            "max_unit": 16,
            "step_size": 4,
            "total": 128
        },
        "VCPU": {
            "allocation_ratio": 10.0,
            "reserved": 2,
            "total": 64
        }
    },
    "resource_provider_generation": 1
}

响应

名称	入参	类型	描述
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
inventories	body	对象	一个以资源类别为键的库存字典。
allocation_ratio	body	float	它用于确定提供者的资源消耗是否可以超过物理约束。 例如，对于 vCPU 资源，如果 allocation_ratio = 16.0 total = 8 总容量等于 128 vCPU。
max_unit	body	整数	库存可以拥有的最大分配量。
min_unit	body	整数	库存可以拥有的最小分配量。
reserved	body	整数	提供程序为其自身用途保留的资源的量。
step_size	body	整数	可以请求的资源的整除量表示。例如，step_size = 5 表示只能请求可被 5 整除的值（5、10、15 等）。
total	body	整数	提供程序可以容纳的资源的实际量。

响应示例

{
    "inventories": {
        "MEMORY_MB": {
            "allocation_ratio": 2.0,
            "max_unit": 16,
            "min_unit": 1,
            "reserved": 0,
            "step_size": 4,
            "total": 128
        },
        "VCPU": {
            "allocation_ratio": 10.0,
            "max_unit": 2147483647,
            "min_unit": 1,
            "reserved": 2,
            "step_size": 1,
            "total": 64
        }
    },
    "resource_provider_generation": 2
}

DELETE

/resource_providers/{uuid}/inventories

删除资源提供者库存

详情

删除由 {uuid} 标识的资源提供者的所有库存记录。

故障排除

当对提供者存在分配时，或者在尝试操作时提供者的库存被另一个线程更新时，请求返回 HTTP 409。

注意

该方法从版本 1.5 开始可用。

正常响应代码：204

错误响应代码：itemNotFound(404), conflict(409)

注意

由于此请求不接受资源提供者代，因此在多个线程管理单个提供者的库存时使用不安全。在这种情况下，请使用 PUT /resource_providers/{uuid}/inventories API，并带有一个空的 inventories 字典。

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

成功删除后不返回正文内容。

资源提供者库存

有关描述，请参阅资源提供者库存。

这组 API 调用使用由 resource_class 标识的单个库存。每个调用可以列出、创建、更新和删除一个库存。

GET

/resource_providers/{uuid}/inventories/{resource_class}

显示资源提供者库存

详情

正常响应代码：200

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
resource_class	路径	字符串	一个资源类别的名称。

响应

名称	入参	类型	描述
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
allocation_ratio	body	float	它用于确定提供者的资源消耗是否可以超过物理约束。 例如，对于 vCPU 资源，如果 allocation_ratio = 16.0 total = 8 总容量等于 128 vCPU。
max_unit	body	整数	库存可以拥有的最大分配量。
min_unit	body	整数	库存可以拥有的最小分配量。
reserved	body	整数	提供程序为其自身用途保留的资源的量。
step_size	body	整数	可以请求的资源的整除量表示。例如，step_size = 5 表示只能请求可被 5 整除的值（5、10、15 等）。
total	body	整数	提供程序可以容纳的资源的实际量。

响应示例

{
    "allocation_ratio": 16.0,
    "max_unit": 4,
    "min_unit": 1,
    "reserved": 0,
    "resource_provider_generation": 9,
    "step_size": 1,
    "total": 4
}

PUT

/resource_providers/{uuid}/inventories/{resource_class}

更新资源提供者库存

详情

替换由 {uuid} 标识的资源提供者的 {resource_class} 库存记录。

正常响应代码：200

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
resource_class	路径	字符串	一个资源类别的名称。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
total	body	整数	提供程序可以容纳的资源的实际量。
allocation_ratio (可选)	body	float	它用于确定提供者的资源消耗是否可以超过物理约束。 例如，对于 vCPU 资源，如果 allocation_ratio = 16.0 total = 8 总容量等于 128 vCPU。
max_unit (可选)	body	整数	库存可以拥有的最大分配量。
min_unit (可选)	body	整数	库存可以拥有的最小分配量。
reserved (可选)	body	整数	提供者为其自身使用保留的资源数量。在微版本 1.25 之前，此值必须小于 total 的值。从微版本 1.26 开始，此值必须小于或等于 total 的值。
step_size (可选)	body	整数	可以请求的资源的整除量表示。例如，step_size = 5 表示只能请求可被 5 整除的值（5、10、15 等）。

请求示例

{
    "resource_provider_generation": 7,
    "total": 50
}

响应

名称	入参	类型	描述
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
allocation_ratio	body	float	它用于确定提供者的资源消耗是否可以超过物理约束。 例如，对于 vCPU 资源，如果 allocation_ratio = 16.0 total = 8 总容量等于 128 vCPU。
max_unit	body	整数	库存可以拥有的最大分配量。
min_unit	body	整数	库存可以拥有的最小分配量。
reserved	body	整数	提供程序为其自身用途保留的资源的量。
step_size	body	整数	可以请求的资源的整除量表示。例如，step_size = 5 表示只能请求可被 5 整除的值（5、10、15 等）。
total	body	整数	提供程序可以容纳的资源的实际量。

响应示例

{
    "allocation_ratio": 1.0,
    "max_unit": 2147483647,
    "min_unit": 1,
    "reserved": 0,
    "resource_provider_generation": 8,
    "step_size": 1,
    "total": 50
}

DELETE

/resource_providers/{uuid}/inventories/{resource_class}

删除资源提供者库存

详情

删除由 {uuid} 标识的资源提供者的 {resource_class} 库存记录。

请参阅 Delete resource provider inventories 中的故障排除部分以获取描述。此外，当存在针对指定资源提供者和资源类别的分配时，请求返回 HTTP 409。

正常响应代码：204

错误响应代码：itemNotFound(404), conflict(409)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
resource_class	路径	字符串	一个资源类别的名称。

响应

成功删除后不返回正文内容。

资源提供者聚合

每个资源提供者可以与一个或多个其他资源提供者在称为聚合的组中关联。本节中的 API 调用用于列出和更新与一个资源提供者关联的聚合。

提供者聚合用于建模提供者之间的关系。示例可能包括

• 一个共享存储池向提供 VCPU 和 MEMORY_MB 资源的计算节点提供者提供 DISK_GB 资源。

• 亲和/反亲和关系，例如物理位置、断电域或其他可靠性/可用性结构。

• 计算主机提供者分组对应于 Nova 主机聚合或可用性区域。

注意

Placement 聚合与 Nova 主机聚合不相同，不应视为等效。

Nova 的主机聚合和 placement 聚合之间的主要区别如下

• 在 Nova 中，主机聚合将nova-compute 服务与其他 nova-compute 服务关联起来。Placement 聚合不特定于 nova-compute 服务，实际上根本不是计算特定的。Placement API 中的资源提供者是通用的，placement 聚合只是通用资源提供者组。这是一个重要的区别，特别是对于 Ironic，当与 Nova 一起使用时，许多 Ironic 裸机节点连接到单个 nova-compute 服务。在 Placement API 中，每个 Ironic 裸机节点都是自己的资源提供者，因此可以通过 placement 聚合关联与其他 Ironic 裸机节点关联。

• 在 Nova 中，主机聚合可能附有元数据键/值对。与 Nova 主机聚合关联的所有 nova-compute 服务共享相同的元数据。Placement 聚合没有这样的元数据，因为 placement 聚合只代表资源提供者的分组。在 Placement API 中，资源提供者被单独修饰有特性，提供有关资源提供者的定性信息。

• 在 Nova 中，主机聚合决定了一个或多个 nova-compute 服务所在的可用性区域。虽然 placement 聚合可以用于建模可用性区域，但它们没有固有的此概念。

注意

聚合 API 请求从版本 1.1 开始可用。

GET

/resource_providers/{uuid}/aggregates

列出资源提供者聚合

详情

返回与由 {uuid} 标识的资源提供者关联的聚合列表。

正常响应代码：200

错误响应代码：如果提供者不存在，则为 itemNotFound(404)。（如果提供者没有聚合，则结果为 200，并带有一个空聚合列表。）

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应（微版本 1.1 - 1.18）

名称	入参	类型	描述
aggregates	body	数组	聚合 UUID 列表。以前不存在的聚合将自动创建。

响应示例（微版本 1.1 - 1.18）

{
    "aggregates": [
        "42896e0d-205d-4fe3-bd1e-100924931787",
        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
    ]
}

响应（微版本 1.19 - ）

名称	入参	类型	描述
aggregates	body	数组	聚合 UUID 列表。以前不存在的聚合将自动创建。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。

响应示例（微版本 1.19 - ）

{
    "aggregates": [
        "42896e0d-205d-4fe3-bd1e-100924931787",
        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
    ],
    "resource_provider_generation": 8
}

PUT

/resource_providers/{uuid}/aggregates

更新资源提供者聚合

详情

将聚合列表与由 {uuid} 标识的资源提供者关联起来。

正常响应代码：200

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

请求（微版本 1.1 - 1.18）

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
aggregates	body	数组	聚合 UUID 列表。以前不存在的聚合将自动创建。

请求示例（微版本 1.1 - 1.18）

[
    "42896e0d-205d-4fe3-bd1e-100924931787",
    "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
]

请求（微版本 1.19 - ）

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
aggregates	body	数组	聚合 UUID 列表。以前不存在的聚合将自动创建。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。

请求示例（微版本 1.19 - ）

{
    "aggregates": [
        "42896e0d-205d-4fe3-bd1e-100924931787",
        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
    ],
    "resource_provider_generation": 9
}

响应（微版本 1.1 - ）

名称	入参	类型	描述
aggregates	body	数组	聚合 UUID 列表。以前不存在的聚合将自动创建。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。 1.19 版中的新功能

响应示例（微版本 1.1 - 1.18）

{
    "aggregates": [
        "42896e0d-205d-4fe3-bd1e-100924931787",
        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
    ]
}

响应示例（微版本 1.19 - ）

{
    "aggregates": [
        "42896e0d-205d-4fe3-bd1e-100924931787",
        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
    ],
    "resource_provider_generation": 9
}

特性

特性是资源提供者的定性特征。特性的经典例子是请求不同提供者的磁盘：用户可以请求一个实例的 80GiB 磁盘空间（定量），但也可以期望磁盘是 SSD 而不是旋转磁盘（定性）。特性提供了一种方法来标记存储提供者是 SSD 还是旋转磁盘。

注意

特性 API 请求从版本 1.6 开始可用。

GET

/traits

列出特性

详情

根据指定的参数返回有效的特性字符串列表。

正常响应代码：200

请求

可以使用多个查询参数来过滤返回的特性列表。如果提供了多个不同的参数，则所有过滤器的结果将通过布尔 AND 合并。

名称	入参	类型	描述
name (可选)	查询	字符串	用于过滤特性的字符串。以下选项可用 startswith 运算符过滤名称以特定前缀开头的特性，例如 name=startswith:CUSTOM, in 运算符过滤名称在指定列表中的特性，例如 name=in:HW_CPU_X86_AVX,HW_CPU_X86_SSE,HW_CPU_X86_INVALID_FEATURE。
associated (可选)	查询	字符串	如果此参数为 true，则返回的特性将是至少与一个资源提供者关联的特性。参数的可用值为 true 和 false。

响应

名称	入参	类型	描述
traits	body	数组	特性列表。

响应示例

{
    "traits": [
        "CUSTOM_HW_FPGA_CLASS1",
        "CUSTOM_HW_FPGA_CLASS2",
        "CUSTOM_HW_FPGA_CLASS3"
    ]
}

GET

/traits/{name}

显示特性

详情

检查特性名称是否存在于此云中。

正常响应代码：204

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
name	路径	字符串	特性的名称。

响应

成功 GET 后不返回任何主体内容。

PUT

/traits/{name}

更新特性

详情

插入一个新的自定义特性。如果特性已存在，则返回 204。

特性有两种：标准特性和自定义特性。标准特性可在不同的 OpenStack 云部署之间互操作。标准特性的定义来自 os-traits 库。标准特性在 placement API 中是只读的，这意味着用户无法通过 API 修改任何标准特性。自定义特性由管理员用户用于管理资源提供者的非标准定性信息。

正常响应代码：201, 204

错误响应代码：badRequest(400)

• 如果特性名称没有前缀 CUSTOM_，则为 400 BadRequest。

请求

名称	入参	类型	描述
name	路径	字符串	特性的名称。

响应

名称	入参	类型	描述
位置	标头	字符串	将返回创建资源的位置 URL，HTTP 头部“Location: <Location URL>”。

成功 PUT 后不返回任何主体内容。

DELETE

/traits/{name}

删除特性

详情

删除由 {name} 指定的特性。请注意，只能删除自定义特性。

正常响应代码：204

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

• 如果要删除的名称是标准特性，则为 400 BadRequest。

• 如果不存在此类特性，则为 404 Not Found。

• 如果删除的名称与任何 ResourceProvider 存在关联，则为 409 Conflict。

请求

名称	入参	类型	描述
name	路径	字符串	特性的名称。

响应

成功删除后不返回正文内容。

资源提供者特性

有关描述，请参阅特性。这组 API 请求查询/编辑特性与资源提供者之间的关联。

注意

特性 API 请求从版本 1.6 开始可用。

GET

/resource_providers/{uuid}/traits

列出资源提供者特性

详情

返回由 {uuid} 标识的资源提供者的特性列表。

正常响应代码：200

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

名称	入参	类型	描述
traits	body	数组	特性列表。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。

响应示例

{
    "resource_provider_generation": 1,
    "traits": [
        "CUSTOM_HW_FPGA_CLASS1",
        "CUSTOM_HW_FPGA_CLASS3"
    ]
}

PUT

/resource_providers/{uuid}/traits

更新资源提供者特性

详情

将特性与由 {uuid} 标识的资源提供者关联起来。所有关联的特性将被请求体中指定的特性替换。

正常响应代码：200

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

• 如果任何指定的特性无效，则为 400 Bad Request。有效特性可通过 GET /traits 查询。

• 如果 resource_provider_generation 与服务器端不匹配，则为 409 Conflict。

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。
traits	body	数组	特性列表。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。

请求示例

{
    "resource_provider_generation": 0,
    "traits": [
        "CUSTOM_HW_FPGA_CLASS1",
        "CUSTOM_HW_FPGA_CLASS3"
    ]
}

响应

名称	入参	类型	描述
traits	body	数组	特性列表。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。

响应示例

{
    "resource_provider_generation": 1,
    "traits": [
        "CUSTOM_HW_FPGA_CLASS1",
        "CUSTOM_HW_FPGA_CLASS3"
    ]
}

DELETE

/resource_providers/{uuid}/traits

删除资源提供者特性

详情

解除所有特性与由 {uuid} 标识的资源提供者的关联。

正常响应代码：204

错误响应代码：itemNotFound(404), conflict(409)

• 如果在尝试操作时提供者的特性被另一个线程更新，则为 409 Conflict。

注意

由于此请求不接受资源提供者代，因此在多个线程管理单个提供者的特性时使用不安全。在这种情况下，请使用 PUT /resource_providers/{uuid}/traits API，并带有一个空的 traits 列表。

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

成功删除后不返回正文内容。

分配

分配是表示资源已被某些资源消费者分配和使用的记录。它们指示从特定资源提供者分配给给定资源消费者的特定资源数量。

POST

/allocations

管理分配

详情

在单个请求中为多个消费者创建、更新或删除分配。这允许客户端原子地设置或交换多个消费者的分配，这可能在迁移或移动类型操作期间需要。

通过将 allocations 设置为空对象（参见下面的示例），可以删除请求中提及的单个消费者 uuid 的分配。

从微版本 1.13 开始可用。

正常响应代码：204

错误响应代码：badRequest(400), conflict(409)

• 如果任何指定的资源类别在任何资源提供者中都没有可用库存，则为 409 Conflict。

• 如果在尝试操作时库存被另一个请求更新，则为 409 Conflict，并带错误代码 placement.concurrent_update。请参阅资源提供者和消费者代。

• 如果在尝试操作时指定消费者的分配被另一个请求创建、更新或删除，则在微版本 1.28 或更高版本中为 409 Conflict，并带错误代码 placement.concurrent_update。请参阅资源提供者和消费者代。

请求

名称	入参	类型	描述
消费者 UUID	body	字符串	消费者的 UUID。
consumer_generation	body	整数	消费者的代。当指示调用方期望消费者尚不存在时，应设置为 null。 1.28 版中的新功能
consumer_type	body	字符串	一个由数字、A-Z 和 _ 组成的字符串，描述了哪种消费者正在使用或已使用库存数量创建或分配。该字符串由客户端在写入分配时确定，客户端有责任确保协作服务之间的正确选择。例如，计算服务可能会选择将某些消费者类型设置为“INSTANCE”，而其他类型设置为“MIGRATION”。 1.38 版中的新功能
project_id	body	字符串	项目的 UUID。
user_id	body	字符串	用户的 UUID。
allocations	body	对象	一个以资源提供者 UUID 为键的资源分配字典。如果这是一个空对象，则将删除此消费者的分配。
generation (可选)	body	整数	一个一致的视图标记，用于协助管理并发资源提供者更新。该值被忽略；它的存在是为了保持读写表示之间的对称性。
resources	body	对象	一个以资源类别名称为键的资源记录字典。
mappings (可选)	body	对象	一个字典，将请求组后缀与标识满足每个组的资源提供者 UUID 列表关联起来。空字符串和 [a-zA-Z0-9_-]+ 是有效的后缀。在将分配写入服务器时可以发送此字段，但它将被忽略；这保留了读写表示之间的对称性。 1.34 版中的新功能

请求示例（微版本 1.38 - ）

{
  "30328d13-e299-4a93-a102-61e4ccabe474": {
    "consumer_generation": 1,
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {
      "e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
        "resources": {
          "VCPU": 2,
          "MEMORY_MB": 3
        },
        "generation": 4
      }
    },
    "consumer_type": "INSTANCE"
  },
  "71921e4e-1629-4c5b-bf8d-338d915d2ef3": {
    "consumer_generation": 1,
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {},
    "consumer_type": "MIGRATION"
  },
  "48c1d40f-45d8-4947-8d46-52b4e1326df8": {
    "consumer_generation": 1,
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {
      "e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
        "resources": {
          "VCPU": 4,
          "MEMORY_MB": 5
        },
        "generation": 12
      }
    },
    "consumer_type": "INSTANCE"
  }
}

请求示例（微版本 1.28 - 1.36）

{
  "30328d13-e299-4a93-a102-61e4ccabe474": {
    "consumer_generation": 1,
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {
      "e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
        "resources": {
          "VCPU": 2,
          "MEMORY_MB": 3
        },
        "generation": 4
      }
    }
  },
  "71921e4e-1629-4c5b-bf8d-338d915d2ef3": {
    "consumer_generation": 1,
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {}
  },
  "48c1d40f-45d8-4947-8d46-52b4e1326df8": {
    "consumer_generation": 1,
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {
      "e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
        "resources": {
          "VCPU": 4,
          "MEMORY_MB": 5
        },
        "generation": 12
      }
    }
  }
}

请求示例（微版本 1.13 - 1.27）

{
  "30328d13-e299-4a93-a102-61e4ccabe474": {
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {
      "e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
        "resources": {
          "VCPU": 2,
          "MEMORY_MB": 3
        }
      }
    }
  },
  "71921e4e-1629-4c5b-bf8d-338d915d2ef3": {
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {}
  },
  "48c1d40f-45d8-4947-8d46-52b4e1326df8": {
    "project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
    "allocations": {
      "e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
        "resources": {
          "VCPU": 4,
          "MEMORY_MB": 5
        }
      }
    }
  }
}

响应

成功请求后不返回任何主体内容

GET

/allocations/{consumer_uuid}

列出分配

详情

列出由 {consumer_uuid} 标识的消费者在所有消耗的资源提供者上的所有分配记录。

注意

当列出没有分配的消费者 UUID 的分配时，返回一个带有空值的字典 {"allocations": {}}。

正常响应代码：200

请求

名称	入参	类型	描述
消费者 UUID	路径	字符串	消费者的 UUID。

响应

名称	入参	类型	描述
allocations	body	对象	一个以资源提供者 UUID 为键的分配字典。
generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
resources	body	对象	一个以资源类别名称为键的资源记录字典。
consumer_generation	body	整数	消费者的代。当列出没有分配的消费者 UUID 的分配时将不存在。 1.28 版中的新功能
consumer_type	body	字符串	一个由数字、A-Z 和 _ 组成的字符串，描述了哪种消费者正在使用或已使用库存数量创建或分配。该字符串由客户端在写入分配时确定，客户端有责任确保协作服务之间的正确选择。例如，计算服务可能会选择将某些消费者类型设置为“INSTANCE”，而其他类型设置为“MIGRATION”。 1.38 版中的新功能
project_id	body	字符串	项目的 UUID。当列出没有分配的消费者 UUID 的分配时将不存在。 1.12 版中的新功能
user_id	body	字符串	用户的 UUID。当列出没有分配的消费者 UUID 的分配时将不存在。 1.12 版中的新功能

响应示例（1.38 - ）

{
    "allocations": {
        "92637880-2d79-43c6-afab-d860886c6391": {
            "generation": 2,
            "resources": {
                "DISK_GB": 5
            }
        },
        "ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
            "generation": 8,
            "resources": {
                "MEMORY_MB": 512,
                "VCPU": 2
            }
        }
    },
    "consumer_generation": 1,
    "project_id": "7e67cbf7-7c38-4a32-b85b-0739c690991a",
    "user_id": "067f691e-725a-451a-83e2-5c3d13e1dffc",
    "consumer_type": "INSTANCE"
}

响应示例（1.28 - 1.36）

{
    "allocations": {
        "92637880-2d79-43c6-afab-d860886c6391": {
            "generation": 2,
            "resources": {
                "DISK_GB": 5
            }
        },
        "ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
            "generation": 8,
            "resources": {
                "MEMORY_MB": 512,
                "VCPU": 2
            }
        }
    },
    "consumer_generation": 1,
    "project_id": "7e67cbf7-7c38-4a32-b85b-0739c690991a",
    "user_id": "067f691e-725a-451a-83e2-5c3d13e1dffc"
}

响应示例（1.12 - 1.27）

{
    "allocations": {
        "92637880-2d79-43c6-afab-d860886c6391": {
            "generation": 2,
            "resources": {
                "DISK_GB": 5
            }
        },
        "ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
            "generation": 8,
            "resources": {
                "MEMORY_MB": 512,
                "VCPU": 2
            }
        }
    },
    "project_id": "7e67cbf7-7c38-4a32-b85b-0739c690991a",
    "user_id": "067f691e-725a-451a-83e2-5c3d13e1dffc"
}

PUT

/allocations/{consumer_uuid}

更新分配

详情

创建或更新一个或多个分配记录，表示由 {consumer_uuid} 标识的消费者从一个或多个资源提供者消耗一个或多个类别的资源。如果此消费者已存在分配，则会替换它们。

正常响应代码：204

错误响应代码：badRequest(400), itemNotFound(404), conflict(409)

• 如果任何指定的资源类别在任何资源提供者中都没有可用库存，则为 409 Conflict。

• 如果在尝试操作时库存被另一个请求更新，则为 409 Conflict，并带错误代码 placement.concurrent_update。请参阅资源提供者和消费者代。

• 如果在尝试操作时指定消费者的分配被另一个请求创建、更新或删除，则在微版本 1.28 或更高版本中为 409 Conflict，并带错误代码 placement.concurrent_update。请参阅资源提供者和消费者代。

请求（微版本 1.12 - ）

名称	入参	类型	描述
消费者 UUID	路径	字符串	消费者的 UUID。
allocations	body	对象	一个以资源提供者 UUID 为键的资源分配字典。
resources	body	对象	一个以资源类别名称为键的资源记录字典。
consumer_generation	body	整数	消费者的代。当指示调用方期望消费者尚不存在时，应设置为 null。 1.28 版中的新功能
consumer_type	body	字符串	一个由数字、A-Z 和 _ 组成的字符串，描述了哪种消费者正在使用或已使用库存数量创建或分配。该字符串由客户端在写入分配时确定，客户端有责任确保协作服务之间的正确选择。例如，计算服务可能会选择将某些消费者类型设置为“INSTANCE”，而其他类型设置为“MIGRATION”。 1.38 版中的新功能
project_id	body	字符串	项目的 UUID。
user_id	body	字符串	用户的 UUID。
generation (可选)	body	整数	一个一致的视图标记，用于协助管理并发资源提供者更新。该值被忽略；它的存在是为了保持读写表示之间的对称性。
mappings (可选)	body	对象	一个字典，将请求组后缀与标识满足每个组的资源提供者 UUID 列表关联起来。空字符串和 [a-zA-Z0-9_-]+ 是有效的后缀。在将分配写入服务器时可以发送此字段，但它将被忽略；这保留了读写表示之间的对称性。 1.34 版中的新功能

请求示例（微版本 1.38 - ）

{
  "allocations": {
    "4e061c03-611e-4caa-bf26-999dcff4284e": {
      "resources": {
        "DISK_GB": 20
      }
    },
    "89873422-1373-46e5-b467-f0c5e6acf08f": {
      "resources": {
        "MEMORY_MB": 1024,
        "VCPU": 1
      }
    }
  },
  "consumer_generation": 1,
  "user_id": "66cb2f29-c86d-47c3-8af5-69ae7b778c70",
  "project_id": "42a32c07-3eeb-4401-9373-68a8cdca6784",
  "consumer_type": "INSTANCE"
}

请求示例（微版本 1.28 - 1.36）

{
  "allocations": {
    "4e061c03-611e-4caa-bf26-999dcff4284e": {
      "resources": {
        "DISK_GB": 20
      }
    },
    "89873422-1373-46e5-b467-f0c5e6acf08f": {
      "resources": {
        "MEMORY_MB": 1024,
        "VCPU": 1
      }
    }
  },
  "consumer_generation": 1,
  "user_id": "66cb2f29-c86d-47c3-8af5-69ae7b778c70",
  "project_id": "42a32c07-3eeb-4401-9373-68a8cdca6784"
}

请求示例（微版本 1.12 - 1.27）

{
  "allocations": {
    "4e061c03-611e-4caa-bf26-999dcff4284e": {
      "resources": {
        "DISK_GB": 20
      }
    },
    "89873422-1373-46e5-b467-f0c5e6acf08f": {
      "resources": {
        "MEMORY_MB": 1024,
        "VCPU": 1
      }
    }
  },
  "user_id": "66cb2f29-c86d-47c3-8af5-69ae7b778c70",
  "project_id": "42a32c07-3eeb-4401-9373-68a8cdca6784"
}

请求（微版本 1.0 - 1.11）

名称	入参	类型	描述
消费者 UUID	路径	字符串	消费者的 UUID。
allocations	body	数组	字典列表。
resources	body	对象	一个以资源类别名称为键的资源记录字典。
resource_provider	body	对象	包含资源提供者 UUID 的字典。
uuid	body	字符串	资源提供者的 UUID。
project_id	body	字符串	项目的 UUID。 1.8 版中的新功能
user_id	body	字符串	用户的 UUID。 1.8 版中的新功能

请求示例（微版本 1.0 - 1.11）

{
    "allocations": [
        {
            "resource_provider": {
                "uuid": "844ac34d-620e-474c-833c-4c9921251353"
            },
            "resources": {
                "MEMORY_MB": 512,
                "VCPU": 2
            }
        },
        {
            "resource_provider": {
                "uuid": "92637880-2d79-43c6-afab-d860886c6391"
            },
            "resources": {
                "DISK_GB": 5
            }
        }
    ],
    "project_id": "6e3b2ce9-9175-4830-a862-b9de690bdceb",
    "user_id": "81c516e3-5e0e-4dcb-9a38-4473d229a950"
}

响应

成功 PUT 后不返回任何主体内容。

DELETE

/allocations/{consumer_uuid}

删除分配

详情

删除由 {consumer_uuid} 标识的消费者在所有资源提供者上的所有分配记录。

正常响应代码：204

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
消费者 UUID	路径	字符串	消费者的 UUID。

响应

成功删除后不返回正文内容。

资源提供者分配

有关描述，请参阅分配。

GET

/resource_providers/{uuid}/allocations

列出资源提供者分配

详情

返回对此资源提供者进行的所有分配的表示，以消费者 UUID 为键。每个分配包括一个或多个资源类别以及消耗的数量。

正常响应代码：200

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

名称	入参	类型	描述
allocations	body	对象	一个以消费者 UUID 为键的分配记录字典。
resources	body	对象	一个以资源类别名称为键的资源记录字典。
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。

响应示例

{
    "allocations": {
        "56785a3f-6f1c-4fec-af0b-0faf075b1fcb": {
            "resources": {
                "MEMORY_MB": 256,
                "VCPU": 1
            }
        },
        "9afd5aeb-d6b9-4dea-a588-1e6327a91834": {
            "resources": {
                "MEMORY_MB": 512,
                "VCPU": 2
            }
        },
        "9d16a611-e7f9-4ef3-be26-c61ed01ecefb": {
            "resources": {
                "MEMORY_MB": 1024,
                "VCPU": 1
            }
        }
    },
    "resource_provider_generation": 12
}

用法

表示项目和用户对资源的消耗。

注意

Usages API 请求从版本 1.9 开始可用。

GET

/usages

列出用法

详情

返回与由 project_id 标识的项目和由 user_id 标识的用户关联的资源的使用信息报告。该值是一个资源类别字典，其中包含提供的参数的该资源类别的分配总和。

正常响应代码：200

错误响应代码：badRequest(400)

请求

名称	入参	类型	描述
project_id	查询	字符串	项目的 UUID。
user_id (可选)	查询	字符串	用户的 UUID。
consumer_type (可选)	查询	字符串	一个由数字、A-Z 和 _ 组成的字符串，描述了用于过滤使用结果的消费者类型。例如，要仅检索“INSTANCE”类型消费者的使用信息，应提供参数 consumer_type=INSTANCE。可以指定 all 查询参数以将所有结果分组到一个键 all 下。可以指定 unknown 查询参数以将所有结果分组到一个键 unknown 下。 1.38 版中的新功能

响应（微版本 1.38 - ）

名称	入参	类型	描述
usages.consumer_type	body	字符串	一个由数字、A-Z 和 _ 组成的字符串，描述了哪种消费者正在使用或已使用库存数量创建或分配。该字符串由客户端在写入分配时确定，客户端有责任确保协作服务之间的正确选择。例如，计算服务可能会选择将某些消费者类型设置为“INSTANCE”，而其他类型设置为“MIGRATION”。 1.38 版中的新功能
usages.consumer_type.consumer_count	body	整数	特定 consumer_type 的消费者数量。 1.38 版中的新功能
usages.consumer_type.RESOURCE_CLASS	body	整数	使用报告中消耗的资源类别数量。

响应示例（微版本 1.38 - ）

{
   "usages" : {
      "INSTANCE" : {
         "consumer_count" : 5,
         "MEMORY_MB" : 512,
         "VCPU" : 2,
         "DISK_GB" : 5
      },
      "MIGRATION" : {
         "DISK_GB" : 5,
         "VCPU" : 2,
         "consumer_count" : 2,
         "MEMORY_MB" : 512
      },
      "unknown" : {
         "VCPU" : 2,
         "DISK_GB" : 5,
         "consumer_count" : 1,
         "MEMORY_MB" : 512
      }
   }
}

响应（微版本 1.9 - 1.36）

名称	入参	类型	描述
usages	body	对象	一个以资源类别名称为键的资源记录字典。

响应示例（微版本 1.9 - 1.36）

{
    "usages": {
        "DISK_GB": 5,
        "MEMORY_MB": 512,
        "VCPU": 2
    }
}

资源提供者用量

以聚合形式显示资源提供者的资源消耗，即不包含特定消费者的信息。请参阅资源提供者分配。

GET

/resource_providers/{uuid}/usages

列出资源提供者用量

详情

返回与由 {uuid} 标识的资源提供者关联的资源的使用信息报告。该值是一个资源类别字典，其中包含此资源提供者的该资源类别的分配总和。

正常响应代码：200

错误响应代码：itemNotFound(404)

请求

名称	入参	类型	描述
uuid	路径	字符串	资源提供者的 UUID。

响应

名称	入参	类型	描述
resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
usages	body	对象	资源提供者的使用摘要。这是一个字典，描述了此资源提供者上每种资源类别的消耗量。例如，"VCPU": 1 表示使用了 1 个 VCPU。

响应示例

{
    "resource_provider_generation": 1,
    "usages": {
        "DISK_GB": 1,
        "MEMORY_MB": 512,
        "VCPU": 1
    }
}

分配候选

注意

分配候选 API 请求从版本 1.10 开始可用。

GET

/allocation_candidates

列出分配候选

详情

返回一个表示分配请求和资源提供者摘要集合的字典。每个分配请求都有信息来形成 PUT /allocations/{consumer_uuid} 请求，以针对一组相关资源提供者声明资源。可能需要额外的参数，请参阅更新分配。由于有几个分配请求可用，因此有必要选择一个。为了做出决定，提供了包含库存/容量信息的资源提供者摘要。例如，此信息被 nova-scheduler 的 FilterScheduler 用于决定在哪台计算主机上构建服务器。

您还可以在使用提供者树建模文档中找到请求参数的其他案例研究。

正常响应代码：200

错误响应代码：badRequest(400)

请求

名称	入参	类型	描述
resources (可选)	查询	字符串	逗号分隔的字符串列表，指示每个分配请求中的提供者必须共同具备容量和可用性以提供指定类别的资源数量 resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048 这些资源可以通过同一非共享树中或通过聚合关联的任何提供者来满足。
required (可选)	查询	字符串	提供者必须拥有的逗号分隔特性列表 required=HW_CPU_X86_AVX,HW_CPU_X86_SSE 响应中的分配请求将针对具有所有请求资源容量的资源提供者，并且这些资源提供者的集合将共同包含所有必需的特性。这些特性可以通过同一非共享树中或通过聚合关联的任何提供者来满足，只要该提供者也为请求贡献资源。从微版本 1.22 开始，可以通过在特性前加上 ! 来表示禁止任何为请求贡献资源的资源提供者具有的特性。 从微版本 1.39 开始，required 查询参数可以重复。重复参数的特性列表将进行 AND 运算。因此 required=T1,!T2&required=T3 表示 T1 且非 T2 且 T3。 此外，从微版本 1.39 开始，required 参数支持以下语法 required=in:T1,T2,T3 这意味着 T1 或 T2 或 T3。 不支持将禁止特性混入 in: 前缀值中并会被拒绝。但在同一个请求中，将普通特性列表和 in: 前缀特性列表混入两个查询参数中是支持的。所以 required=in:T3,T4&required=T1,!T2 受支持，它表示 T1 且非 T2 且 (T3 或 T4)。 1.17 版中的新功能
member_of (可选)	查询	字符串	表示聚合 UUID 的字符串；或前缀 in: 后跟逗号分隔的表示聚合 UUID 的字符串列表。响应中的分配请求中的资源提供者必须直接或通过根提供者与由 UUID 标识的一个或多个聚合关联 member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa 从微版本 1.24 开始，可以指定多个 member_of 查询字符串参数。多个 member_of 参数将导致过滤直接或通过根提供者与所有 member_of 查询字符串值中列出的聚合关联的提供者。例如，要获取与聚合 A 以及与聚合 B 或 C 中的任何一个关联的提供者，用户可以发出以下查询 member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID 从微版本 1.32 开始，member_of 查询字符串参数支持指定禁止的聚合。禁止的聚合以 ! 为前缀。此否定表达式也可以在多个 member_of 参数中使用 member_of=AGGA_UUID&member_of=!AGGB_UUID 在逻辑上将翻译为“候选资源提供者必须在 AGGA 中，并且不在 AGGB 中。”我们不支持 ! 在 in: 内的值上，但我们支持 !in:。以下两个示例查询都返回不在 AGGA、AGGB 或 AGGC 中的候选资源提供者 member_of=!in:AGGA_UUID,AGGB_UUID,AGGC_UUID member_of=!AGGA_UUID&member_of=!AGGB_UUID&member_of=!AGGC_UUID 我们不检查同一个聚合 UUID 是否同时存在于肯定和否定表达式中，以返回 400 BadRequest。在这种情况下，我们仍然返回 200。例如 member_of=AGGA_UUID&member_of=!AGGA_UUID 将返回空的 allocation_requests 和 provider_summaries，而 member_of=in:AGGA_UUID,AGGB_UUID&member_of=!AGGA_UUID 将返回不在AGGA中但在AGGB中的资源提供者。 1.21 版中的新功能
in_tree (可选)	查询	字符串	一个字符串，表示资源提供者 UUID。提供时，它将过滤返回的分配候选，仅限于与给定资源提供者在同一树中的资源提供者。 1.31 版中的新功能
resourcesN (可选)	查询	字符串	一个逗号分隔的字符串列表，指示提供者必须有能力提供指定类别的资源数量 resources42=VCPU:4,DISK_GB:64,MEMORY_MB:2048 参数键是 resourcesN，其中 N 表示唯一后缀。值格式与（非粒度的）resources 参数相同，但 resourcesN 参数中指定的资源将始终由单个提供者满足。 在微版本 1.25 - 1.32 中，后缀是数字。 从微版本 1.33 开始，后缀是一个字符串，长度可以是 1-64 个字符，由数字、a-z、A-Z、- 和 _ 组成。 不同的分组（带或不带后缀）可能由相同的提供者满足，也可能不满足，具体取决于 group_policy 参数的值。 1.25 版中的新功能
requiredN (可选)	查询	字符串	一个逗号分隔的特性列表，提供者必须具有（或如果前缀为 !，则不具有） required42=HW_CPU_X86_AVX,HW_CPU_X86_SSE,!HW_CPU_X86_AVX2 参数键是 requiredN，其中 N 表示与 resourcesN 参数对应的后缀。 值格式与（非粒度的）required 参数相同；但是，带后缀分组中指定的所有资源和特性将始终由同一资源提供者满足。不同的分组（带或不带后缀）可能由同一提供者满足，也可能不满足，具体取决于 group_policy 参数的值。 在微版本 1.25 - 1.32 中，后缀是数字。 从微版本 1.33 开始，后缀是一个字符串，长度可以是 1-64 个字符，由数字、a-z、A-Z、- 和 _ 组成。 如果未指定相应的 resourcesN 参数且后缀相同，则指定 requiredN 参数是错误的。 从微版本 1.39 开始，粒度 requiredN 查询参数支持 in: 语法以及参数重复。因此 requiredN=in:T3,T4&requiredN=T1,!T2 受支持，它表示 T1 且非 T2 且 (T3 或 T4)。 1.25 版中的新功能
member_ofN (可选)	查询	字符串	表示聚合 UUID 的字符串；或前缀 in: 后跟逗号分隔的表示聚合 UUID 的字符串列表。返回的资源提供者必须直接与由 UUID 标识的至少一个聚合关联。从微版本 1.32 开始，支持指定禁止的聚合。禁止的聚合以 ! 为前缀；或前缀 !in: 后跟逗号分隔的表示聚合 UUID 的字符串列表。返回的资源提供者不得直接与由 UUID 标识的任何聚合关联。参数键是 member_ofN，其中 N 表示与 resourcesN 参数对应的后缀。值格式与（非粒度的）member_of 参数相同；但是，粒度分组中指定的所有资源和特性将始终由同一资源提供者满足。在微版本 1.25 - 1.32 中，后缀是数字。从微版本 1.33 开始，后缀是一个字符串，长度可以是 1-64 个字符，由数字、a-z、A-Z、- 和 _ 组成。不同的分组（带或不带后缀）可能由相同的提供者满足，也可能不满足，具体取决于 group_policy 参数的值。如果未指定相应的 resourcesN 参数且后缀相同，则指定 member_ofN 参数是错误的。 1.25 版中的新功能
in_treeN (可选)	查询	字符串	一个字符串，表示资源提供者 UUID。参数键是 in_treeN，其中 N 表示与 resourcesN 参数对应的后缀。提供时，它将过滤返回的分配候选，以使该带后缀组仅包含与给定资源提供者在同一树中的资源提供者。在微版本 1.25 - 1.32 中，后缀是数字。从微版本 1.33 开始，后缀是一个字符串，长度可以是 1-64 个字符，由数字、a-z、A-Z、- 和 _ 组成。 1.31 版中的新功能
group_policy (可选)	查询	字符串	当提供了多个 resourcesN 查询参数时，需要 group_policy 来指示这些组应如何交互。当 group_policy=none 时，不同的分组（带或不带后缀）可能由同一提供者满足，也可能不满足。当 group_policy=isolate 时，带后缀的组保证由不同的提供者满足——尽管可能仍然与无后缀组重叠。 1.25 版中的新功能
limit (可选)	查询	整数	一个正整数，用于限制响应中返回的最大分配候选数量。 1.16 版中的新功能
root_required (可选)	查询	字符串	一个逗号分隔的特性要求列表，非共享树的根提供者必须满足这些要求 root_required=COMPUTE_SUPPORTS_MULTI_ATTACH,!CUSTOM_WINDOWS_LICENSED 响应中的分配请求将仅限于其（非共享）树的根提供者满足指定特性要求的请求。禁止的特性（根提供者必须不存在）通过在特性前加上 ! 来表示。 1.35 版中的新功能
same_subtree (可选)	查询	字符串	一个逗号分隔的请求组后缀字符串列表 ($S)。每个后缀必须与请求中其他粒度组上的后缀完全匹配。重要的是，标识的请求组不需要 resources[$S]。如果提供了此参数，则满足指定请求组的至少一个资源提供者必须是其余提供者的祖先。same_subtree 查询参数可以重复，每个重复组都独立处理。 1.36 版中的新功能

响应（微版本 1.12 - ）

名称	入参	类型	描述
allocation_requests	body	数组	一个对象列表，其中包含客户端随后可在调用 PUT /allocations/{consumer_uuid} 中使用的序列化 HTTP 正文，以针对一组相关资源提供者声明资源。
provider_summaries	body	对象	一个以资源提供者 UUID 为键的字典，包含在 allocation_requests 中，其中包含库存/容量信息的字典。与资源提供者关联的特性列表包含在版本 1.17 及更高版本中。从微版本 1.29 开始，提供者摘要包含同一资源提供者树中所有包含一个或多个资源提供者的资源提供者，这些资源提供者包含在 allocation_requests 中。
allocations	body	对象	一个以资源提供者 UUID 为键的分配字典。
resources	body	对象	一个以资源类别名称为键的资源记录字典。
capacity	body	整数	提供者可容纳的资源量。
used	body	整数	已分配的资源量。
traits	body	数组	特性列表。 1.17 版中的新功能
parent_provider_uuid	body	字符串	资源提供者直接父级的 UUID。 1.29 版中的新功能
root_provider_uuid	body	字符串	此提供者树中最高级提供者的 UUID。 1.29 版中的新功能
mappings	body	对象	一个字典，将请求组后缀与标识满足每个组的资源提供者 UUID 列表关联起来。空字符串和 [a-zA-Z0-9_-]+ 是有效的后缀。在将分配写入服务器时可以发送此字段，但它将被忽略；这保留了读写表示之间的对称性。 1.34 版中的新功能

响应示例 (微版本 1.34 - )

{
  "allocation_requests": [
    {
      "allocations": {
        "92e971c9-777a-48bf-a181-a2ca1105c015": {
          "resources": {
            "NET_BW_EGR_KILOBIT_PER_SEC": 10
          }
        },
        "cefbdf54-05a8-4db4-ad2b-d6729e5a4de8": {
          "resources": {
            "NET_BW_EGR_KILOBIT_PER_SEC": 20
          }
        },
        "9a9c6b0f-e8d1-4d16-b053-a2bfe8a76757": {
          "resources": {
            "VCPU": 1
          }
        }
      },
      "mappings": {
        "_NET1": [
          "92e971c9-777a-48bf-a181-a2ca1105c015"
        ],
        "_NET2": [
          "cefbdf54-05a8-4db4-ad2b-d6729e5a4de8"
        ],
        "": [
          "9a9c6b0f-e8d1-4d16-b053-a2bfe8a76757"
        ]
      }
    }
  ],
  "provider_summaries": {
    "be99627d-e848-44ef-8341-683e2e557c58": {
      "resources": {},
      "traits": [
        "COMPUTE_VOLUME_MULTI_ATTACH"
      ],
      "parent_provider_uuid": null,
      "root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
    },
    "9a9c6b0f-e8d1-4d16-b053-a2bfe8a76757": {
      "resources": {
        "VCPU": {
          "capacity": 4,
          "used": 0
        },
        "MEMORY_MB": {
          "capacity": 2048,
          "used": 0
        }
      },
      "traits": [
        "HW_NUMA_ROOT",
        "CUSTOM_FOO"
      ],
      "parent_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58",
      "root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
    },
    "ba415f98-1960-4488-b2ed-4518b77eaa60": {
      "resources": {},
      "traits": [
        "CUSTOM_VNIC_TYPE_DIRECT"
      ],
      "parent_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58",
      "root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
    },
    "92e971c9-777a-48bf-a181-a2ca1105c015": {
      "resources": {
        "NET_BW_EGR_KILOBIT_PER_SEC": {
          "capacity": 10000,
          "used": 0
        }
      },
      "traits": [
        "CUSTOM_PHYSNET1"
      ],
      "parent_provider_uuid": "ba415f98-1960-4488-b2ed-4518b77eaa60",
      "root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
    },
    "cefbdf54-05a8-4db4-ad2b-d6729e5a4de8": {
      "resources": {
        "NET_BW_EGR_KILOBIT_PER_SEC": {
          "capacity": 20000,
          "used": 0
        }
      },
      "traits": [
        "CUSTOM_PHYSNET2"
      ],
      "parent_provider_uuid": "ba415f98-1960-4488-b2ed-4518b77eaa60",
      "root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
    }
  }
}

响应示例 (微版本 1.29 - 1.33)

{
    "allocation_requests": [
        {
            "allocations": {
                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
                    "resources": {
                        "DISK_GB": 100
                    }
                },
                "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
                    "resources": {
                        "VCPU": 1,
                        "MEMORY_MB": 1024
                    }
                }
            }
        },
        {
            "allocations": {
                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
                    "resources": {
                        "DISK_GB": 100
                    }
                },
                "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
                    "resources": {
                        "VCPU": 1,
                        "MEMORY_MB": 1024
                    }
                }
            }
        }
    ],
    "provider_summaries": {
        "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
            "resources": {
                "DISK_GB": {
                    "used": 0,
                    "capacity": 1900
                }
            },
            "traits": ["MISC_SHARES_VIA_AGGREGATE"],
            "parent_provider_uuid": null,
            "root_provider_uuid": "a99bad54-a275-4c4f-a8a3-ac00d57e5c64"
        },
        "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
            "resources": {
                "VCPU": {
                    "used": 0,
                    "capacity": 384
                },
                "MEMORY_MB": {
                    "used": 0,
                    "capacity": 196608
                }
            },
            "traits": ["HW_CPU_X86_SSE2", "HW_CPU_X86_AVX2"],
            "parent_provider_uuid": null,
            "root_provider_uuid": "35791f28-fb45-4717-9ea9-435b3ef7c3b3"
        },
        "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
            "resources": {
                "VCPU": {
                    "used": 0,
                    "capacity": 384
                },
                "MEMORY_MB": {
                    "used": 0,
                    "capacity": 196608
                }
            },
            "traits": ["HW_NIC_SRIOV"],
            "parent_provider_uuid": null,
            "root_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd"
        },
        "f5120cad-67d9-4f20-9210-3092a79a28cf": {
            "resources": {
                "SRIOV_NET_VF": {
                    "used": 0,
                    "capacity": 8
                }
            },
            "traits": [],
            "parent_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd",
            "root_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd"
        }
    }
}

响应示例 (微版本 1.17 - 1.28)

{
    "allocation_requests": [
        {
            "allocations": {
                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
                    "resources": {
                        "DISK_GB": 100
                    }
                },
                "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
                    "resources": {
                        "VCPU": 1,
                        "MEMORY_MB": 1024
                    }
                }
            }
        },
        {
            "allocations": {
                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
                    "resources": {
                        "DISK_GB": 100
                    }
                },
                "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
                    "resources": {
                        "VCPU": 1,
                        "MEMORY_MB": 1024
                    }
                }
            }
        }
    ],
    "provider_summaries": {
        "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
            "resources": {
                "DISK_GB": {
                    "used": 0,
                    "capacity": 1900
                }
            },
            "traits": ["HW_CPU_X86_SSE2", "HW_CPU_X86_AVX2"]
        },
        "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
            "resources": {
                "VCPU": {
                    "used": 0,
                    "capacity": 384
                },
                "MEMORY_MB": {
                    "used": 0,
                    "capacity": 196608
                }
            },
            "traits": ["HW_NIC_SRIOV"]
        },
        "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
            "resources": {
                "VCPU": {
                    "used": 0,
                    "capacity": 384
                },
                "MEMORY_MB": {
                    "used": 0,
                    "capacity": 196608
                }
            },
            "traits": []
        }
    }
}

响应示例 (微版本 1.12 - 1.16)

{
    "allocation_requests": [
        {
            "allocations": {
                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
                    "resources": {
                        "DISK_GB": 100
                    }
                },
                "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
                    "resources": {
                        "VCPU": 1,
                        "MEMORY_MB": 1024
                    }
                }
            }
        },
        {
            "allocations": {
                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
                    "resources": {
                        "DISK_GB": 100
                    }
                },
                "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
                    "resources": {
                        "VCPU": 1,
                        "MEMORY_MB": 1024
                    }
                }
            }
        }
    ],
    "provider_summaries": {
        "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
            "resources": {
                "DISK_GB": {
                    "used": 0,
                    "capacity": 1900
                }
            }
        },
        "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
            "resources": {
                "VCPU": {
                    "used": 0,
                    "capacity": 384
                },
                "MEMORY_MB": {
                    "used": 0,
                    "capacity": 196608
                }
            }
        },
        "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
            "resources": {
                "VCPU": {
                    "used": 0,
                    "capacity": 384
                },
                "MEMORY_MB": {
                    "used": 0,
                    "capacity": 196608
                }
            }
        }
    }
}

响应 (微版本 1.10 - 1.11)

名称	入参	类型	描述
allocation_requests	body	数组	一个对象列表，其中包含客户端随后可在调用 PUT /allocations/{consumer_uuid} 中使用的序列化 HTTP 正文，以针对一组相关资源提供者声明资源。
provider_summaries	body	对象	一个字典，键是包含在 allocation_requests 中的资源提供者 UUID，值是包含库存/容量信息的字典。
allocations	body	数组	字典列表。
resource_provider	body	对象	包含资源提供者 UUID 的字典。
uuid	body	字符串	资源提供者的 UUID。
resources	body	对象	一个以资源类别名称为键的资源记录字典。
capacity	body	整数	提供者可容纳的资源量。
used	body	整数	已分配的资源量。

响应示例 (微版本 1.10 - 1.11)

{
    "allocation_requests": [
        {
            "allocations": [
                {
                    "resource_provider": {
                        "uuid": "30742363-f65e-4012-a60a-43e0bec38f0e"
                    },
                    "resources": {
                        "MEMORY_MB": 512
                    }
                }
            ]
        }
    ],
    "provider_summaries": {
        "30742363-f65e-4012-a60a-43e0bec38f0e": {
            "resources": {
                "DISK_GB": {
                    "capacity": 77,
                    "used": 0
                },
                "MEMORY_MB": {
                    "capacity": 11206,
                    "used": 256
                },
                "VCPU": {
                    "capacity": 64,
                    "used": 0
                }
            }
        }
    }
}

重塑器

注意

重塑器请求从版本 1.30 开始可用。

POST

/reshaper

重塑器

详情

原子性地迁移资源提供者库存和相关分配。当某些库存需要从一个资源提供者移动到另一个资源提供者时，例如当一类库存从父级提供者移动到新的子级提供者时，会使用此操作。

注意

这是一个特殊操作，仅在资源提供者拓扑结构发生变化且库存正在使用中的罕见情况下使用。仅在您非常确定自己在做什么的情况下才使用此操作。

正常响应代码：204

错误响应代码：badRequest(400)，conflict(409)

请求

名称	入参	类型	描述
inventories	body	对象	一个包含多个库存的字典，以资源提供者 UUID 为键。每个库存描述了每个资源提供者的所需完整库存。一个空字典表示删除该提供者的库存。
inventories.{resource_provider_uuid}.resource_provider_generation	body	整数	一种一致性标记，有助于管理并发资源提供程序更新。
inventories.{resource_provider_uuid}.inventories	body	对象	一个以资源类别为键的库存字典。
allocations	body	对象	一个包含多个分配的字典，以消费者 UUID 为键。每个分配集合描述了每个消费者的完整分配集。每个消费者分配字典本身都是一个以资源提供者 UUID 为键的资源分配字典。一个空字典表示现有分配没有变化，而消费者字典**内**的空 allocations 字典表示应删除该消费者的所有分配。
allocations.{consumer_uuid}.allocations	body	对象	一个以资源提供者 UUID 为键的资源分配字典。如果这是一个空对象，则将删除此消费者的分配。
allocations.{consumer_uuid}.allocations.{resource_provider_uuid}.resources	body	对象	一个以资源类别名称为键的资源记录字典。
allocations.{consumer_uuid}.project_id	body	字符串	项目的 UUID。
allocations.{consumer_uuid}.user_id	body	字符串	用户的 UUID。
allocations.{consumer_uuid}.mappings	body	对象	一个字典，将请求组后缀与标识满足每个组的资源提供者 UUID 列表关联起来。空字符串和 [a-zA-Z0-9_-]+ 是有效的后缀。在将分配写入服务器时可以发送此字段，但它将被忽略；这保留了读写表示之间的对称性。 1.34 版中的新功能
allocations.{consumer_uuid}.consumer_generation	body	整数	消费者的代。当指示调用方期望消费者尚不存在时，应设置为 null。
allocations.{consumer_uuid}.consumer_type	body	字符串	一个由数字、A-Z 和 _ 组成的字符串，描述了哪种消费者正在使用或已使用库存数量创建或分配。该字符串由客户端在写入分配时确定，客户端有责任确保协作服务之间的正确选择。例如，计算服务可能会选择将某些消费者类型设置为“INSTANCE”，而其他类型设置为“MIGRATION”。 1.38 版中的新功能

请求示例

{
  "allocations": {
    "9ae60315-80c2-48a0-a168-ca4f27c307e1": {
      "allocations": {
        "a7466641-cd72-499b-b6c9-c208eacecb3d": {
          "resources": {
            "DISK_GB": 1000
          }
        }
      },
      "project_id": "2f0c4ffc-4c4d-407a-b334-56297b871b7f",
      "user_id": "cc8a0fe0-2b7c-4392-ae51-747bc73cf473",
      "consumer_generation": 1,
      "consumer_type": "INSTANCE"
    },
    "4a6444e5-10d6-43f6-9a0b-8acce9309ac9": {
      "allocations": {
        "c4ddddbb-01ee-4814-85c9-f57a962c22ba": {
          "resources": {
            "VCPU": 1
          }
        },
        "a7466641-cd72-499b-b6c9-c208eacecb3d": {
          "resources": {
            "DISK_GB": 20
          }
        }
      },
      "project_id": "2f0c4ffc-4c4d-407a-b334-56297b871b7f",
      "user_id": "406e1095-71cb-47b9-9b3c-aedb7f663f5a",
      "consumer_generation": 1,
      "consumer_type": "INSTANCE"
    },
    "e10e7ca0-2ac5-4c98-bad9-51c95b1930ed": {
      "allocations": {
        "c4ddddbb-01ee-4814-85c9-f57a962c22ba": {
          "resources": {
            "VCPU": 8
          }
        }
      },
      "project_id": "2f0c4ffc-4c4d-407a-b334-56297b871b7f",
      "user_id": "cc8a0fe0-2b7c-4392-ae51-747bc73cf473",
      "consumer_generation": 1,
      "consumer_type": "INSTANCE"
    }
  },
  "inventories": {
    "c4ddddbb-01ee-4814-85c9-f57a962c22ba": {
      "inventories": {
        "VCPU": {
          "max_unit": 8,
          "total": 10
        }
      },
      "resource_provider_generation": null
    },
    "a7466641-cd72-499b-b6c9-c208eacecb3d": {
      "inventories": {
        "DISK_GB": {
          "min_unit": 10,
          "total": 2048,
          "max_unit": 1200,
          "step_size": 10
        }
      },
      "resource_provider_generation": 5
    }
  }
}

成功 POST 后不返回任何主体内容。