REST API 版本历史¶
本文档记录了每次微版本变更对 REST API 所做的更改。每个版本的描述都应详细，包含足够的信息，以便在用户文档中使用。
Newton¶
1.0 - 初始版本¶
添加于 Newton 版本。
这是 placement REST API 的初始版本，于 Nova 14.0.0 (Newton) 中发布。它包含以下路由：
/resource_providers/resource_providers/allocations/resource_providers/inventories/resource_providers/usages/allocations
Ocata¶
1.1 - 资源提供者聚合¶
添加于 Ocata 版本。
1.1 版本增加了将聚合与资源提供者关联的支持。
添加了以下新的操作：
GET /resource_providers/{uuid}/aggregates返回与资源提供者关联的所有聚合
PUT /resource_providers/{uuid}/aggregates更新与资源提供者关联的聚合
1.2 - 添加自定义资源类¶
添加于 Ocata 版本。
Placement API 1.2 版本增加了基本操作，允许管理员创建、列出和删除自定义资源类。
添加了以下新的路由：
GET /resource_classes返回所有资源类
POST /resource_classes创建一个新的自定义资源类
PUT /resource_classes/{name}更新自定义资源类的名称
DELETE /resource_classes/{name}删除自定义资源类
GET /resource_classes/{name}获取单个资源类
自定义资源类必须以 CUSTOM_ 前缀开头，并且仅包含字母 A 到 Z，数字 0 到 9 以及下划线 _ 字符。
1.3 - ‘member_of’ 查询参数¶
添加于 Ocata 版本。
1.3 版本增加了支持使用 member_of 查询参数列出属于提供的任何聚合列表的资源提供者。
?member_of=in:{agg1_uuid},{agg2_uuid},{agg3_uuid}
1.4 - 按请求资源容量过滤资源提供者¶
添加于 Ocata 版本。
1.4 版本增加了支持查询具有服务请求资源集能力的资源提供者。现在接受一个新的“resources”查询字符串参数到 GET /resource_providers API 调用。该参数指示提供者必须具有服务各种资源请求数量的能力。 “resources”查询字符串参数的形式为
?resources=$RESOURCE_CLASS_NAME:$AMOUNT,$RESOURCE_CLASS_NAME:$AMOUNT
例如，如果用户希望查看能够服务 2 个 vCPU、1024 MB 内存和 50 GB 磁盘空间的请求的资源提供者，则用户可以发出请求到
GET /resource_providers?resources=VCPU:2,MEMORY_MB:1024,DISK_GB:50
如果资源类不存在，则将返回 HTTP 400 错误。
注意
资源过滤也基于库存记录的 min_unit、max_unit 和 step_size。例如，如果特定资源提供者的 DISK_GB 库存的 max_unit 为 512，并且发出了 DISK_GB:1024 的 GET 请求，则该资源提供者将不会被返回。 min_unit 是可以为给定库存和资源提供者请求的资源的最小数量。 step_size 是可以在给定提供商的给定资源上请求的资源的增量。
Pike¶
1.5 - ‘DELETE’ 资源提供者的所有库存¶
添加于 Pike 版本。
Placement API 1.5 版本增加了用于删除资源提供者的所有库存的 DELETE 方法。支持以下新的方法：
DELETE /resource_providers/{uuid}/inventories删除给定资源提供者的所有库存
1.6 - Traits API¶
添加于 Pike 版本。
1.6 版本增加了基本操作，允许管理员创建、列出和删除自定义 traits，还增加了基本操作，允许管理员将 traits 附加到资源提供者。
添加了以下新的路由：
GET /traits返回所有资源类。
PUT /traits/{name}插入单个自定义 trait。
GET /traits/{name}检查 trait 名称是否存在。
DELETE /traits/{name}删除指定的 trait。
GET /resource_providers/{uuid}/traits返回与特定资源提供者关联的所有 traits。
PUT /resource_providers/{uuid}/traits更新特定资源提供者的所有 traits。
DELETE /resource_providers/{uuid}/traits删除特定资源提供者的任何现有 trait 关联
自定义 traits 必须以 CUSTOM_ 前缀开头，并且仅包含字母 A 到 Z，数字 0 到 9 以及下划线 _ 字符。
1.7 - 幂等的 ‘PUT /resource_classes/{name}’¶
添加于 Pike 版本。
1.7 版本更改了 PUT /resource_classes/{name} 的处理方式，使其成为使用 {name} 创建或验证资源类。如果资源类是自定义资源类并且尚不存在，则将创建它并返回 201 响应代码。如果类已经存在，则响应代码将为 204。这使得可以在一个请求中检查或创建资源类。
1.8 - 要求 placement 在 ‘PUT /allocations’ 中包含 ‘project_id’ 和 ‘user_id’¶
添加于 Pike 版本。
1.8 版本增加了对 PUT /allocations 的请求参数 project_id 和 user_id 的必需要求。
1.9 - 添加 ‘GET /usages’¶
添加于 Pike 版本。
1.9 版本增加了可以通过项目或项目/用户查询的 usages。
添加了以下新的路由：
GET /usages?project_id=<project_id>返回给定项目的所有 usages。
GET /usages?project_id=<project_id>&user_id=<user_id>返回给定项目和用户的 usages。
1.10 - 分配候选者¶
添加于 Pike 版本。
1.10 版本带来了用于获取分配候选者列表的新 REST 资源端点。分配候选者是可能的分配集合，这些分配针对资源提供者，可以满足特定资源请求。
Queens¶
1.11 - 在 ‘GET /resource_providers’ 响应中添加 ‘allocations’ 链接¶
添加于 Queens 版本。
自 1.0 版本以来，/resource_providers/{rp_uuid}/allocations 端点可用，但未在 GET /resource_providers 响应的 links 部分中列出。该链接在 1.11 版本中包含。
1.12 - ‘PUT’ 字典格式到 ‘/allocations/{consumer_uuid}’¶
添加于 Queens 版本。
在 1.12 版本中，PUT /allocations/{consumer_uuid} 请求的主体预计具有 allocations 属性的 object，而不是早期微版本中的 array。这使请求主体与 GET /allocations/{consumer_uuid} 响应主体结构更加一致。由于 PUT 请求需要在请求主体中包含 user_id 和 project_id，因此这些字段被添加到 GET 响应中。此外，GET /allocation_candidates 响应主体已更新，以便 allocation_requests 对象中的分配与新的 PUT 格式一起工作。
1.13 - ‘POST’ 多个分配到 ‘/allocations’¶
添加于 Queens 版本。
1.13 版本提供了使用 POST /allocations 请求为多个消费者 UUID 设置或清除分配的能力。
1.14 - 添加嵌套资源提供者¶
添加于 Queens 版本。
1.14 版本引入了嵌套资源提供者的概念。资源提供者资源现在包含两个新的属性：
parent_provider_uuid指示提供者的直接父级，或者如果没有父级则为 null。如果该属性尚未设置为非 NULL 值（即，我们不支持“重新父级”提供者），则可以在调用POST /resource_providers和PUT /resource_providers/{uuid}时设置此属性。root_provider_uuid指示提供者树中根资源提供者的 UUID。这是一个只读属性
一个新的 in_tree=<UUID> 参数现在在 GET /resource-providers API 调用中可用。为 in_tree 参数提供 UUID 值将导致返回提供者树中与 <UUID> 匹配的提供者的所有资源提供者。
1.15 - 添加 ‘last-modified’ 和 ‘cache-control’ 标头¶
添加于 Queens 版本。
在整个 API 中，‘last-modified’ 标头已添加到 GET 响应以及具有主体的 PUT 和 POST 响应。该值是最近修改的关联数据库实体实际的最后修改时间，或者如果没有直接映射到数据库，则为当前时间。此外，在添加了 ‘last-modified’ 标头的地方，添加了 ‘cache-control: no-cache’ 标头，以防止意外缓存资源。
1.16 - 限制分配候选者¶
添加于 Queens 版本。
添加对发出 GET /allocation_candidates 请求时使用 limit 查询参数的支持。该参数接受一个整数值，N，它限制了返回的最大候选者数量。
1.17 - 将 ‘required’ 参数添加到分配候选者¶
添加于 Queens 版本。
添加了 required 参数到 GET /allocation_candidates API。它接受用 , 分隔的 traits 列表。在指定时，响应中的提供者摘要将包含附加的 traits。
Rocky¶
1.18 - 支持 ‘?required=<traits>’ 查询参数在 ‘GET /resource_providers’ 上¶
添加于 Rocky 版本。
为 GET /resource_providers API 添加了对 required 查询参数的支持。它接受一个逗号分隔的字符串 trait 名称列表。当指定时，API 结果将被过滤为仅包含标记了所有指定 traits 的资源提供者。这除了（逻辑 AND）基于其他查询参数的任何过滤之外。
空、不存在或无效的 trait 名称将导致 400 错误。
1.19 - 在提供者聚合 API 中包含生成和冲突检测¶
添加于 Rocky 版本。
增强 GET /resource_providers/{uuid}/aggregates 响应和 PUT /resource_providers/{uuid}/aggregates 请求和响应的有效负载，使其相同，并包含 resource_provider_generation。与其他基于生成数的 API 一样，如果在 PUT 请求中指定的 resource_provider_generation 与服务器已知的生成数不匹配，则返回 409 Conflict 错误。
1.20 - 从 ‘POST /resource_providers’ 返回带有提供者负载的 200¶
添加于 Rocky 版本。
成功的 POST /resource_providers API 返回 200，并带有表示新创建的资源提供者的负载，格式与相应的 GET /resource_providers/{uuid} 调用相同。这样调用方无需后续 GET 请求即可自动获取自动设置的字段，例如 UUID 和生成版本。
1.21 - 支持 ‘?member_of=<aggregates>’ 查询参数在 ‘GET /allocation_candidates’ 上¶
添加于 Rocky 版本。
为 GET /allocation_candidates API 添加对 member_of 查询参数的支持。它接受用逗号分隔的聚合体的 UUID 列表。请注意，如果传递了多个聚合体 UUID，则用逗号分隔的列表必须以“in:”运算符为前缀。如果提供了此参数，则返回的资源提供者将仅限于位于指定聚合体之一中的资源提供者，并且满足请求的其他部分。
1.22 - 支持资源提供者和分配候选者的禁用特性¶
添加于 Rocky 版本。
为在过滤 GET /resource_providers 或 GET /allocation_candidates 时表达禁用特性添加支持。禁用特性是在现有的 required 参数中正确格式化的特性，前面加上 !。例如 required=!STORAGE_DISK_SSD 要求结果不包含提供固态硬盘的任何资源提供者。
1.23 - 在 JSON 错误响应中包含 ‘code’ 属性¶
添加于 Rocky 版本。
JSON 格式的错误响应获得了一个新的属性 code，其值为标识此错误类型的代码。这可用于区分使用相同 HTTP 状态代码的不同错误。任何未明确定义代码的错误响应都将具有代码 placement.undefined_code。
1.24 - 支持多个 ‘?member_of’ 查询参数¶
添加于 Rocky 版本。
为 GET /resource_providers API 添加支持，以指定多个 member_of 查询参数。找到多个 member_of 查询参数时，它们将在最终查询中进行 AND 操作。例如，发出 GET /resource_providers?member_of=agg1&member_of=agg2 请求意味着获取与 agg1 和 agg2 都关联的资源提供者。发出 GET /resource_providers?member_of=in:agg1,agg2&member_of=agg3 请求意味着获取与 agg3 关联的资源提供者，并且也与 (agg1, agg2) 中的任何一个关联。
1.25 - 对 ‘GET /allocation_candidates’ 进行细粒度的资源请求¶
添加于 Rocky 版本。
GET /allocation_candidates 增强了对资源、所需/禁止特性和聚合体关联请求的编号分组的支持。带有正整数后缀的 resources 查询参数键（例如 resources42）将在逻辑上与具有相同后缀的 required 和/或 member_of 查询参数键（例如 required42、member_of42）关联。响应中的资源提供者将通过同一资源提供者满足该组中的资源、所需/禁止特性和聚合体关联。当提供多个编号分组时，需要 group_policy 查询参数来指示组应如何交互。对于 group_policy=none，单独的编号或未编号分组可能由相同的提供者满足，也可能不满足。对于 group_policy=isolate，保证编号组由不同的提供者满足 - 但仍可能与未编号组重叠。在所有情况下，每个 allocation_request 都将由同一非共享提供者树中的提供者或通过聚合体与该树中的任何提供者关联的提供者满足。
对于给定的组，required 和 member_of 查询参数是可选的。也就是说，您可以指定 resources42=XXX 而没有相应的 required42=YYY 或 member_of42=ZZZ。但是，反之（指定 required42=YYY 或 member_of42=ZZZ 而没有 resources42=XXX）将导致错误。
(未编号的) resources、required 和 member_of 查询参数的语义未更改：由此指定的资源、特性和聚合体关联可以由同一非共享树中的任何提供者或通过指定的聚合体满足。
1.26 - 允许库存的保留值等于总值¶
添加于 Rocky 版本。
从这个版本开始，允许将资源提供者库存的保留值设置为等于总值。
1.27 - 在 ‘provider_summaries’ 中包含所有资源类库存¶
添加于 Rocky 版本。
即使资源类未在请求的资源中，也将在 GET /allocation_candidates API 的响应中的 provider_summaries 字段中包含所有资源类库存。
1.28 - 消费者生成支持¶
添加于 Rocky 版本。
已向消费者概念添加一个新的生成字段。消费者是在放置 API 中分配资源的参与者。创建分配时，将指定消费者 UUID。从微版本 1.8 开始，还需要项目和用户 ID。如果使用早于 1.8 的微版本，则这些 ID 将从 [placement] 部分的 incomplete_consumer_project_id 和 incomplete_consumer_user_id 配置选项中填充。
消费者生成有助于安全地并发修改分配。
现在从以下 URI 返回消费者生成版本
GET /resource_providers/{uuid}/allocations
响应仍然是一个字典，其中包含一个键 allocations，它本身是一个字典，按消费者 UUID 键控，对应于资源提供者的分配。对于这些字典中的每一个，现在将显示一个 consumer_generation 字段。
GET /allocations/{consumer_uuid}
响应仍然是一个字典，其中包含一个键 allocations，它本身是一个字典，按资源提供者 UUID 键控，对应于由具有 {consumer_uuid} 的消费者的分配。顶层字典现在也将包含一个 consumer_generation 字段。
consumer_generation 字段的值是不透明的，只能用于发送到后续操作的消费者分配。
已修改 PUT /allocations/{consumer_uuid} URI，现在需要在请求负载中需要一个 consumer_generation 字段。如果调用者期望消费者没有现有的分配，则此字段必须为 null。否则，它应该包含调用者在调用时理解的消费者的生成版本。
如果提供的生成版本与服务器已知消费者的生成版本不匹配，则将从 PUT /allocations/{consumer_uuid} 返回 409 Conflict。同样，如果在替换消费者的分配过程中，另一个进程同时更改了消费者的分配，将返回 409 Conflict。这允许调用者通过重新读取消费者的分配并根据需要重新发出调用分配的请求来响应并发写入。
已修改 PUT /allocations/{consumer_uuid} URI，还允许接受一个空的分配对象，从而使其与 POST /allocations 的行为相同，后者使用一个空的分配对象来指示应删除特定消费者的分配。连同 consumer_generation 一起传递一个空的分配对象使 PUT /allocations/{consumer_uuid} 成为删除消费者分配的安全方式。DELETE /allocations/{consumer_uuid} URI 在多个调用者可能同时尝试修改消费者分配的部署中仍然不安全。
已更改 POST /allocations URI 变体，要求在请求负载中为涉及请求的每个消费者提供一个 consumer_generation 字段。当任何消费者的生成版本与服务器对这些消费者的视图冲突时，或者如果请求中涉及的任何消费者被另一个进程修改，则返回与 PUT /allocations/{consumer_uuid} 类似的响应。
警告
在所有情况下，使用不同的微版本（其中一个微版本早于 1.28）创建和修改消费者的分配是绝对不安全的。安全修改消费者分配并满足您对这些分配的先前存在性（或不存在性）的期望的唯一方法是在调用分配 API 端点时始终使用微版本 1.28+。
1.29 - 支持具有嵌套资源提供者的分配候选者¶
添加于 Rocky 版本。
添加了对嵌套资源提供者的支持，包括以下两个特性。1) GET /allocation_candidates 了解嵌套提供者。也就是说，当存在提供者树时，GET /allocation_candidates 响应中的 allocation_requests 可以包括对同一树中多个资源提供者的组合的分配。2) root_provider_uuid 和 parent_provider_uuid 已添加到 GET /allocation_candidates 响应中的 provider_summaries 中。
1.30 - 提供一个 ‘/reshaper’ 资源¶
添加于 Rocky 版本。
添加了对 POST /reshaper 资源的支持，该资源提供了一种以原子方式迁移资源提供者库存和相关分配的方法，当一些库存从一个资源提供者移动到另一个资源提供者时（例如，当一类库存从父提供者移动到新的子提供者时）。
注意
这是一个特殊操作，仅应在资源提供者拓扑发生变化且库存正在使用时才使用。只有在您确定自己在做什么时才使用此操作。
Stein¶
1.31 - 在 ‘GET /allocation_candidates’ 上添加 ‘in_tree’ 查询参数¶
在 Stein 版本中添加。
为 GET /allocation_candidates API 添加了对 in_tree 查询参数的支持。它接受资源提供者的 UUID。如果提供了此参数，则返回的资源提供者将仅限于与给定资源提供者位于同一树中的那些资源提供者。还支持编号语法 in_tree<N>。这将把满足第 N 个细粒度请求组的提供者限制为指定提供者的树。这可能与其他 in_tree<N> 值冗余，这些值在其他组（包括未编号组）中指定。但是，在需要来自特定共享提供者（例如共享存储）的特定资源（例如 DISK_GB）的情况下，这可能很有用。
例如，从 myhost 请求 VCPU 和 VGPU 资源，从 sharing1 请求 DISK_GB 资源，可能如下所示
?resources=VCPU:1&in_tree=<myhost_uuid>
&resources1=VGPU:1&in_tree1=<myhost_uuid>
&resources2=DISK_GB:100&in_tree2=<sharing1_uuid>
Train¶
1.32 - 支持禁止的聚合¶
在 Train 版本中添加。
在 GET /resource_providers 和 GET /allocation_candidates 中，为 member_of queryparam 添加对禁止聚合的支持。禁止的聚合以 ! 为前缀。
此否定表达式也可以在多个 member_of 参数中使用
?member_of=in:<agg1>,<agg2>&member_of=<agg3>&member_of=!<agg4>
逻辑上会转换为
“候选资源提供者必须至少是 agg1 或 agg2 的一个，绝对在 agg3 中，并且绝对不在 agg4 中。”
我们不支持在 in: 列表中使用 !
?member_of=in:<agg1>,<agg2>,!<agg3>
但我们支持 !in: 前缀
?member_of=!in:<agg1>,<agg2>,<agg3>
这等效于
?member_of=!<agg1>&member_of=!<agg2>&member_of=!<agg3>``
其中候选资源提供者不能在 agg1、agg2 或 agg3 中。
1.33 - 支持字符串请求组后缀¶
在 Train 版本中添加。
在 1.25 中引入的资源、所需/禁止特征和聚合关联请求的精细分组语法已扩展为允许使用 1 到 64 个字符的字符串，这些字符串由 a-z、A-Z、0-9、_ 和 - 组成，除了数字之外。这样做是为了允许在多个服务协作发出请求时出现命名约定（例如 resources_COMPUTE 和 resources_NETWORK）。
例如，除了已经支持的
resources42=XXX&required42=YYY&member_of42=ZZZ
现在可以使用更复杂的字符串，包括 UUID
resources_PORT_fccc7adb-095e-4bfd-8c9b-942f41990664=XXX
&required_PORT_fccc7adb-095e-4bfd-8c9b-942f41990664=YYY
&member_of_PORT_fccc7adb-095e-4bfd-8c9b-942f41990664=ZZZ
1.34 - 请求组映射在分配候选对象中¶
在 Train 版本中添加。
对 GET /allocation_candidates 请求的响应主体已扩展为包含每个分配请求的 mappings 字段。该值是一个字典，将请求组后缀与满足已识别请求组的资源提供者的 UUID 关联起来。为了方便起见，此映射可以包含在 POST /allocations、PUT /allocations/{consumer_uuid} 和 POST /reshaper 的请求有效负载中，但会被忽略。
1.35 - 支持 GET /allocation_candidates 上的 ‘root_required’ queryparam¶
在 Train 版本中添加。
为 GET /allocation_candidates API 添加对 root_required query 参数的支持。它接受一个逗号分隔的特征名称列表，每个特征名称可以选择性地以 ! 为前缀，以指示禁止的特征，格式与 required query 参数相同。这将响应中的分配请求限制为仅那些其（非共享）树的根资源提供者满足指定特征要求的请求。有关详细信息，请参阅 按根提供者特征过滤。
1.36 - 支持 GET /allocation_candidates 上的 ‘same_subtree’ queryparam¶
在 Train 版本中添加。
为 GET /allocation_candidates API 添加对 same_subtree query 参数的支持。它接受一个逗号分隔的请求组后缀字符串 $S 列表。每个字符串必须与请求中的某个地方的精细组上的后缀完全匹配。重要的是，识别的请求组不一定具有 resources$S。如果提供了此参数，则至少有一个满足指定请求组的资源提供者必须是其余资源的祖先。same_subtree query 参数可以重复，并且每个重复组都被独立对待。
Xena¶
1.37 - 允许通过 PUT /resource_providers/{uuid} 进行重新父级化和取消父级化¶
在 Xena 版本中添加。
通过允许将 parent_provider_uuid 更改为任何现有提供者（同一子树中的提供者除外），通过 PUT /resource_providers/{uuid} API 支持重新父级化和取消父级化资源提供者。可以通过将 parent_provider_uuid 设置为 null 来实现取消父级化。这意味着该提供者将成为新的根提供者。
1.38 - 支持 allocations、usage 和 reshaper 中的 consumer_type¶
在 Xena 版本中添加。
为 POST /allocations、PUT /allocations/{consumer_uuid} 的请求主体以及 GET /allocations/{consumer_uuid} 的响应中添加对 consumer_type（必需）键的支持。GET /usages 请求获得一个 consumer_type 键作为可选的 query 参数，以根据 consumer_types 过滤 usages。GET /usages 响应将根据 consumer 类型对结果进行分组，并将包含一个名为 consumer_count 的新键，无论是否在请求中指定了 consumer_type。如果提供了 all consumer_type 键，则所有结果都将分组在一个键 all 下。较旧的分配，如果没有使用 consumer 类型创建，则被认为具有 unknown consumer_type。如果提供了 unknown consumer_type 键，则所有结果都将分组在一个键 unknown 下。
对 POST /reshaper 的相应更改也包括在内。
1.39 - 支持 required 参数中的 any-traits 语法¶
在 Yoga 版本中添加。
为 GET /resource_providers API 以及 GET /allocation_candidates API 的 required 和 requiredN query 参数中添加对 in: 语法的支持。此外，还支持在各自的 API 中重复 required 和 requiredN 参数。所以
required=in:T3,T4&required=T1,!T2
受支持，这意味着 T1 且非 T2 且 (T3 或 T4)。
