微版本

随着 openstacksdk 开始支持使用微版本，它将根据需要逐个调用地进行支持。 就像主版本一样，openstacksdk 应该为它发出的每个 REST 调用处理每个微版本，并牢记以下规则

  • 如果 openstack 执行的某个活动可以使用新的微版本以不同的方式或更有效地完成，则应将支持添加到 openstack.cloud 和相应的 Proxy 类中。

  • openstacksdk 应该始终尝试使用它知道的给定调用的最新微版本，除非某个微版本删除了重要数据。

  • 在 Python API 调用或 openstack.cloud 层中，绝不应将微版本选择暴露给用户，在资源层或 openstack.cloud 层均不应暴露。

  • 微版本选择通过 REST 层中的 microversion 参数暴露给用户，每个 REST 调用都有此参数。

  • REST 层的用户可以通过在 clouds.yaml 中设置 {service_type}_default_microversion 或设置 OS_{service_type|upper}_DEFAULT_MICROVERSION 环境变量来设置默认微版本。

注意

在任何情况下，除非使用 REST 层，否则设置默认微版本强烈不建议这样做。 openstacksdk 中的两个较高层都提供数据规范化以及关于要发出哪个 REST 调用的逻辑。 设置默认微版本可能会以 openstacksdk 不理解的方式更改相关服务的行为。 如果某个服务的功能需要一个微版本，并且该功能尚未在 openstacksdk 中透明地暴露，请提交一个错误报告。

  • 如果某个功能仅在给定的微版本中公开，并且无法在没有该微版本的旧云中模拟，则可以添加该功能，但应向用户提供明确的错误消息，说明该功能在其云上不可用。（例如：“此云支持服务 YYY 的最大微版本为 XXX，而此功能仅存在于微版本为 ZZZ 的云上。 请联系您的云提供商，了解有关何时可用此功能的更多信息。”）

  • 在添加仅存在于新微版本中的功能时，应尽一切努力找出如何提供相同的功能，即使这样做效率低下。 如果使用了效率低下的解决方法，应向用户提供警告。（用户的解决方法是停止使用该 openstacksdk API 调用）。 一个例子是 nova 的“为我获取网络”功能。 “为我获取网络”的逻辑可以在客户端完成，尽管效率较低。 通过 nova 微版本添加对“为我获取网络”功能的支持，还应添加对执行客户端解决方法的支持。

  • 如果 openstacksdk 知道一个以上微版本的逻辑，它应该始终尝试使用该调用针对该服务可用的最新版本。

  • 从 openstacksdk 返回的对象应始终通过规范化，因此应始终符合 openstacksdk 记录的数据模型。 无论 REST 调用使用哪个微版本，对象对用户来说都不应有所不同。

  • 如果微版本向对象添加了新字段，则应将这些字段添加到 openstacksdk 的该对象的数据模型契约中，并且如果可以通过执行其他 REST 调用获得数据，则应填充数据，否则该字段应具有默认值 None，用户在尝试使用新值时应预期对其进行测试。

  • 如果微版本删除了对象中的字段，而这些字段是现有数据模型契约的一部分，则应小心不要为该调用使用新的微版本，除非由于问题云上旧微版本不可用而被迫使用。 在不再提供旧微版本的情况下，必须小心找到来自其他来源的数据并填充它，或者将 None 值放入该字段并记录给用户，说明在某些云上该值可能不存在。

  • 如果微版本删除了一个字段，并且结果特别棘手且无法在不从根本上破坏用户的情况下解决，则应向相关服务团队提出问题。 希望在云仍然具有旧微版本期间可以找到解决方案。

  • 在添加新的调用或对象时，重要的是与相关服务团队核实对象预期的稳定性。 如果已知将来会发生变化，即使可能还需要几年时间，openstacksdk 也应小心不要对其数据模型中的这些字段/功能添加承诺。 openstacksdk 没有某些东西是可以的。

    注意

    openstacksdk 目前没有一种“实验性”选择加入的 API，可以允许将可能不受正常兼容性契约支持的事物暴露给用户。 如果将来出现冲突，并且强烈希望某个功能但又缺乏对其长期稳定性的确定性，则可以探索一个实验性 API……但应在出现具体用例后才启动此类 API。