通用镜像 API v2.x 信息¶
镜像服务 API v2 允许您存储和检索磁盘和服务器镜像。
版本控制¶
两部分版本控制方案
镜像服务 API v2 模仿 API v1，并使用主版本号和次版本号。例如，v2.3 是主版本号 2 和次版本号 3。
向后兼容性
次版本发布会扩展接口，而不会减少接口。例如，v2.1 中的所有内容在 v2.2 中可用。
属性保护
镜像 API v2.2 允许云提供商使用属性保护，这是一种可选功能，通过该功能可以对镜像属性应用 CRUD 保护。
因此，在特定部署中，非管理员用户可能无法查看、更新或删除某些镜像属性。
此外，非管理员用户在创建自定义镜像属性时可能被迫遵循特定的命名约定。
云提供商负责向用户传达有关属性保护的策略。
HTTP 响应状态码¶
以下 HTTP 状态码都是有效的响应
200 - 通用成功响应，期望有响应体
201 - 已创建实体，期望有响应体和一个 Location 标头
204 - 成功响应，没有响应体
301 - 重定向
400 - 无效请求（语法、值等）
401 - 未认证的客户端
403 - 已认证的客户端无法执行操作
409 - 由于某种（可能永久）情况，该操作是不可能的
415 - 不支持的媒体类型
没有 200 级别响应码的响应不保证有响应体。如果响应恰好返回响应体，则它不属于此规范，并且不能依赖它。
请求和响应内容格式¶
镜像服务 API v2 主要接受和提供 JSON 编码的数据。在某些情况下，它还接受和提供二进制镜像数据。大多数发送 JSON 编码数据的请求必须在 Content-Type 标头中具有适当的媒体类型：‘application/json’。HTTP PATCH 请求必须使用为他们打算修改的实体定义的 patch 媒体类型。上传镜像数据的请求应使用媒体类型 ‘application/octet-stream’。
每个调用仅以一种格式响应，因此客户端无需担心发送 Accept 标头。它会被忽略。响应格式为 ‘application/json’，除非此规范另有说明。
镜像实体¶
镜像实体由 JSON 编码的数据结构及其原始二进制数据表示。
镜像实体具有一个标识符（ID），该标识符保证在其所属的端点内是唯一的。ID 用作请求 URI 中的令牌，以与特定镜像交互。
镜像始终保证具有以下属性：id、status、visibility、protected、tags、created_at、file 和 self。在 image 模式中定义的其他属性保证被定义，但仅当它们已被显式设置时才与镜像实体一起返回。
如果 image json-schema 允许，客户端可以在其镜像上设置任意命名的属性。这些用户定义的属性看起来就像任何其他镜像属性一样。请参阅 文档 关于 additionalProperties json-schema 属性。
JSON 模式¶
必要的 json-schema 文档在可预测的 URI 处提供。消费者应能够根据已发布的模式验证服务器响应和客户端请求。本文档中包含的模式仅为示例，不应用于验证您的请求。客户端**始终**应从服务器获取模式。
属性保护
镜像 API 的版本 2.2 确认云提供商使用属性保护的能力。因此，对于非管理员用户，某些镜像属性可能不会出现在列出镜像的响应中。
