Image Service API v2 (CURRENT)

显示全部

镜像

创建、列出、显示、更新、删除以及对镜像执行其他操作。

通用信息

镜像

一个镜像由 JSON 对象表示，即一组键值对。其中一些键是 基本属性，由 Image 服务管理。其余属性由操作员或镜像所有者放置在镜像上。

注意

“镜像属性”的另一个常用术语是“镜像元数据”，因为我们这里讨论的是描述镜像数据的属性，这些数据可以被各种 OpenStack 服务使用（例如，Compute 服务用于启动服务器，或 Volume 服务用于创建可引导卷）。

以下是关于镜像属性的一些重要信息

• 基本属性始终包含在镜像表示中。没有值的基本属性将显示其值设置为 null（即 JSON null 数据类型）。

• 附加属性，其值始终是字符串数据类型，仅在它们具有值时才包含在响应中。

• 自 2.2 版本以来，Images API 允许操作员配置属性保护，通过这种方式，对特定镜像属性的创建、读取、更新和删除操作可以限制为特定的用户角色。有关详细信息，请参阅您的云操作员的文档。

• 一个镜像最重要的属性可能是它的 id，它唯一标识镜像，它的 status，它指示镜像的当前状态（反过来，指示您可以对镜像执行的操作），以及它的 visibility，它指示谁可以访问镜像。

• 一些属性由 glance 内部使用，API 用户不允许设置或修改它们。这些示例包括 id、status 以及任何以 os_glance 命名空间为前缀的属性。

注意

除了镜像属性之外，通常还有一个可通过镜像访问的数据有效负载。为了向镜像使用者保证数据有效负载（例如，与镜像 06b73bc7-9d62-4d37-ad95-d4708f37734f 关联的数据今天与昨天用于启动服务器时相同），Image 服务控制特定的镜像属性（例如，checksum），这些属性无法修改。将镜像数据有效负载与 Images API 中的镜像表示相关联的一种简写方式是说“镜像是不变的”。（这显然适用于镜像数据有效负载，而不是它在 Image 服务中的表示。）有关更多信息，请参阅本文档的 Image Data 部分。

镜像状态

镜像的可能状态值显示在下表中。

状态	描述
queued	Image 服务已为镜像保留了目录中的镜像 ID，但尚未上传任何镜像数据。
saving	Image 服务正在将镜像的原始数据保存到后端存储中。
active	镜像处于活动状态，可在 Image 服务中使用。
killed	发生镜像数据上传错误。
deleted	Image 服务保留有关镜像的信息，但镜像不再可供使用。
pending_delete	类似于 deleted 状态。处于此状态的镜像无法恢复。
deactivated	镜像数据不可供使用。
uploading	数据已作为可互操作镜像导入过程的一部分进行暂存。它尚未可供使用。（自 Image API 2.6 起）
importing	镜像数据正在作为可互操作镜像导入过程的一部分进行处理，但尚未可供使用。（自 Image API 2.6 起）

镜像可见性

镜像可见性的可能值显示在下表中。

可见性	描述
public	任何用户都可以读取镜像及其数据有效负载。此外，镜像出现在所有用户的默认镜像列表中。
community	任何用户都可以读取镜像及其数据有效负载，但镜像不出现在任何用户（所有者除外）的默认镜像列表中。 （此可见性值是在 Image API v2.5 中添加的）
shared	为了添加镜像成员，镜像必须具有此可见性。只有所有者和添加到镜像的特定镜像成员才能读取镜像或其数据有效负载。 镜像出现在所有者的默认镜像列表中。它也出现在已接受镜像的成员的默认镜像列表中。有关更多信息，请参阅本文档的 Image Sharing 部分。 如果您在创建镜像时未指定可见性值，则默认分配此可见性。但是，非所有者在将其添加为镜像成员之前将无法访问镜像。 （此可见性值是在 Image API v2.5 中添加的）
private	只有所有者镜像可以读取镜像或其数据有效负载。此外，镜像出现在所有者的默认镜像列表中。 自 Image API v2.5 起，具有私有可见性的镜像不能添加成员。

请注意，上述描述讨论了对镜像的读取访问权限。只有镜像所有者（或管理员）才有权写入镜像属性和镜像数据有效负载。此外，为了保证镜像不变性，Image 服务将仅允许所有者（或管理员）对特定的镜像属性和镜像数据有效负载进行一次写入权限。

POST

/v2/images

创建镜像

详情

创建操作系统磁盘镜像的目录记录。（自 Image API v2.0 起）

响应头中的 Location 包含镜像的 URI。

Rocky 版本中引入了多存储后端支持，作为 EXPERIMENTAL Image API v2.8 的一部分。自 Image API v2.8 起，响应中将包含一个包含可用存储列表的新的头 OpenStack-image-store-ids。仅当支持多个后端存储时，才会包含此标头。

响应体包含新的镜像实体。

同步后置条件

• 在具有正确权限的情况下，您可以通过 API 调用看到镜像状态为 queued。

正常响应代码：201

错误响应代码：400、401、403、409、413、415

请求

名称	入参	类型	描述
container_format (可选)	body	enum	镜像容器的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 容器格式。 示例格式包括：ami、ari、aki、bare、ovf、ova、docker 或 compressed。 该值可能是 null（JSON null 数据类型）。 Train 变更：compressed 容器格式是一个受支持的值。
disk_format (可选)	body	enum	磁盘的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 磁盘格式。 示例格式包括：ami、ari、aki、vhd、vhdx、vmdk、raw、qcow2、vdi、ploop 或 iso。 该值可能是 null（JSON null 数据类型）。 Newton 变更：vhdx 磁盘格式是一个受支持的值。 Ocata 变更：ploop 磁盘格式是一个受支持的值。
id (可选)	body	字符串	一个唯一的、用户定义的镜像 UUID，格式为 nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn 其中 n 是从 0 到 f 或 F 的十六进制数字。 例如 b2173dd3-7ad6-4362-baa6-a68bce3565cb 如果您省略此值，API 将为镜像生成 UUID。如果您指定的值已被分配，则请求将以 409 响应代码失败。
min_disk (可选)	body	整数	启动镜像所需的磁盘空间量，以 GB 为单位。
min_ram (可选)	body	整数	启动镜像所需的 RAM 数量，以 MB 为单位。
name (可选)	body	字符串	镜像的名称。
protected (可选)	body	布尔值	镜像删除保护。有效值为 true 或 false。默认值为 false。
tags (可选)	body	数组	此镜像的标签列表。每个标签最多为 255 个字符。镜像允许的最大标签数由操作员设置。
visibility (可选)	body	字符串	此镜像的可见性。有效值为：public、private、shared 或 community。在大多数站点，只有管理员才能使镜像变为 public。某些站点可能会限制用户使镜像变为 community 的权限。某些站点可能会限制用户对 shared 镜像执行成员操作的权限。自 Image API v2.5 起，默认值为 ``shared``。

此外，您还可以包含作为键值对指定的其他属性，其中值必须是字符串数据类型。键的长度限制为 255 个字符。可用的键名称可能受云的属性保护配置和保留命名空间（如 os_glance）的限制。

请求示例

{
    "container_format": "bare",
    "disk_format": "raw",
    "name": "Ubuntu",
    "id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb"
}

响应参数

名称	入参	类型	描述
位置	标头	字符串	从外部存储访问镜像文件的 URL。
OpenStack-image-import-methods (可选)	标头	字符串	一个逗号分隔的导入方法标识符列表。仅当您的云中启用了镜像导入时，才包含此列表。自 Image API v2.6 起
OpenStack-image-store-ids (可选)	标头	字符串	一个逗号分隔的可用存储标识符列表。如果缺少此标头，则云不支持多个后端存储。
checksum	body	字符串	镜像数据的 MD5 哈希值。该值可能是 null（JSON null 数据类型），因为从 Victoria 版本开始，Image 服务不再填充此字段。为了与旧镜像兼容，它仍然存在。要验证镜像数据，请改用安全多哈希字段 os_hash_algo 和 os_hash_value。
container_format	body	enum	镜像容器的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 容器格式。 示例格式包括：ami、ari、aki、bare、ovf、ova、docker 或 compressed。 该值可能是 null（JSON null 数据类型）。 Train 变更：compressed 容器格式是一个受支持的值。
created_at	body	字符串	创建资源的时间和日期。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 例如，2015-08-27T09:49:58-05:00。 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。
disk_format	body	enum	磁盘的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 磁盘格式。 示例格式包括：ami、ari、aki、vhd、vhdx、vmdk、raw、qcow2、vdi、ploop 或 iso。 该值可能是 null（JSON null 数据类型）。 Newton 变更：vhdx 磁盘格式是一个受支持的值。 Ocata 变更：ploop 磁盘格式是一个受支持的值。
file	body	字符串	虚拟机的镜像文件的 URL。
id	body	字符串	一个唯一的、用户定义的镜像 UUID，格式为 nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn 其中 n 是从 0 到 f 或 F 的十六进制数字。 例如 b2173dd3-7ad6-4362-baa6-a68bce3565cb 如果您省略此值，API 将为镜像生成 UUID。
min_disk	body	整数	启动镜像所需的磁盘空间量，以 GB 为单位。该值可能是 null（JSON null 数据类型）。
min_ram	body	整数	启动镜像所需的 RAM 数量，以 MB 为单位。该值可能是 null（JSON null 数据类型）。
name	body	字符串	镜像的名称。该值可能是 null（JSON null 数据类型）。
os_hash_algo	body	字符串	用于计算此镜像的镜像数据的安全哈希的算法。计算结果显示为 os_hash_value 属性的值。该算法由云操作员选择；它可能不由最终用户配置。（自 Image API v2.7 起）
os_hash_value	body	字符串	使用 os_hash_algo 属性的值作为名称的算法计算的镜像数据的安全哈希的十六进制摘要。该值可能是 null（JSON null 数据类型），如果尚未与此镜像关联数据，或者如果使用 Image 服务 API 的早期版本创建镜像，则可能是如此。（自 Image API v2.7 起）
os_hidden	body	布尔值	此字段控制是否在默认镜像列表响应中显示镜像。 “隐藏”镜像在某种程度上已过时（例如，它可能未应用最新的更新），因此不应是用户的首选，但它不会被删除，因为它可能需要用于服务器重建。通过将其隐藏在默认镜像列表中，最终用户更容易找到并使用此镜像的更新版本。（自 Image API v2.7 起）
owner	body	字符串	镜像所有者的标识符，通常是项目（也称为“租户”）ID。该值可能是 null（JSON null 数据类型）。
protected	body	布尔值	一个布尔值，必须为 false，否则无法删除镜像。
schema	body	字符串	描述虚拟机的镜像模式的 URL。
self	body	字符串	虚拟机的镜像的 URL。
size	body	整数	镜像数据的大小，以字节为单位。该值可能是 null（JSON null 数据类型）。
status	body	字符串	镜像状态。
tags	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。
virtual_size	body	整数	镜像的虚拟大小。该值可能是 null（JSON null 数据类型）。
visibility	body	字符串	镜像可见性，即镜像的访问权限。
direct_url (可选)	body	字符串	从外部存储访问镜像文件的 URL。仅当 Image 服务配置文件中的 show_image_direct_url 选项为 true 时才存在。 由于存在安全风险，默认情况下禁用此选项。
locations (可选)	body	数组	一系列对象，每个对象描述一个镜像位置。每个对象包含一个 url 键，其值为指定位置的 URL，以及一个 metadata 键，其值为一个键值对字典，包含适用于由 URL 指示的任何外部存储使用信息。此列表仅在 show_multiple_locations 选项在 Image 服务的配置文件中设置为 true 时出现。 由于存在安全风险，此选项默认禁用。

响应还可能包含作为键值对指定的其他属性，如果请求中指定了其他属性的话。

响应示例

{
    "status": "queued",
    "name": "Ubuntu",
    "tags": [],
    "container_format": "bare",
    "created_at": "2015-11-29T22:21:42Z",
    "size": null,
    "disk_format": "raw",
    "updated_at": "2015-11-29T22:21:42Z",
    "visibility": "private",
    "locations": [],
    "self": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb",
    "min_disk": 0,
    "protected": false,
    "id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb",
    "file": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb/file",
    "checksum": null,
    "os_hash_algo": null,
    "os_hash_value": null,
    "os_hidden": false,
    "owner": "bab7d5c60cd041a0a36f7c4b6e1dd978",
    "virtual_size": null,
    "min_ram": 0,
    "schema": "/v2/schemas/image"
}

GET

/v2/images/{image_id}

显示镜像

详情

显示镜像的详细信息。（自 Image API v2.0 起）

响应体包含单个镜像实体。

先决条件

• 镜像必须存在。

正常响应代码：200

错误响应代码：400、401、403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

响应参数

名称	入参	类型	描述
checksum	body	字符串	镜像数据的 MD5 哈希值。该值可能是 null（JSON null 数据类型），因为从 Victoria 版本开始，Image 服务不再填充此字段。为了与旧镜像兼容，它仍然存在。要验证镜像数据，请改用安全多哈希字段 os_hash_algo 和 os_hash_value。
container_format	body	enum	镜像容器的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 容器格式。 示例格式包括：ami、ari、aki、bare、ovf、ova、docker 或 compressed。 该值可能是 null（JSON null 数据类型）。 Train 变更：compressed 容器格式是一个受支持的值。
created_at	body	字符串	创建资源的时间和日期。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 例如，2015-08-27T09:49:58-05:00。 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。
disk_format	body	enum	磁盘的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 磁盘格式。 示例格式包括：ami、ari、aki、vhd、vhdx、vmdk、raw、qcow2、vdi、ploop 或 iso。 该值可能是 null（JSON null 数据类型）。 Newton 变更：vhdx 磁盘格式是一个受支持的值。 Ocata 变更：ploop 磁盘格式是一个受支持的值。
file	body	字符串	虚拟机的镜像文件的 URL。
id	body	字符串	一个唯一的、用户定义的镜像 UUID，格式为 nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn 其中 n 是从 0 到 f 或 F 的十六进制数字。 例如 b2173dd3-7ad6-4362-baa6-a68bce3565cb 如果您省略此值，API 将为镜像生成 UUID。
min_disk	body	整数	启动镜像所需的磁盘空间量，以 GB 为单位。该值可能是 null（JSON null 数据类型）。
min_ram	body	整数	启动镜像所需的 RAM 数量，以 MB 为单位。该值可能是 null（JSON null 数据类型）。
name	body	字符串	镜像的名称。该值可能是 null（JSON null 数据类型）。
os_hash_algo	body	字符串	用于计算此镜像的镜像数据的安全哈希的算法。计算结果显示为 os_hash_value 属性的值。该算法由云操作员选择；它可能不由最终用户配置。（自 Image API v2.7 起）
os_hash_value	body	字符串	使用 os_hash_algo 属性的值作为名称的算法计算的镜像数据的安全哈希的十六进制摘要。该值可能是 null（JSON null 数据类型），如果尚未与此镜像关联数据，或者如果使用 Image 服务 API 的早期版本创建镜像，则可能是如此。（自 Image API v2.7 起）
os_hidden	body	布尔值	此字段控制是否在默认镜像列表响应中显示镜像。 “隐藏”镜像在某种程度上已过时（例如，它可能未应用最新的更新），因此不应是用户的首选，但它不会被删除，因为它可能需要用于服务器重建。通过将其隐藏在默认镜像列表中，最终用户更容易找到并使用此镜像的更新版本。（自 Image API v2.7 起）
owner	body	字符串	镜像所有者的标识符，通常是项目（也称为“租户”）ID。该值可能是 null（JSON null 数据类型）。
protected	body	布尔值	一个布尔值，必须为 false，否则无法删除镜像。
schema	body	字符串	描述虚拟机的镜像模式的 URL。
self	body	字符串	虚拟机的镜像的 URL。
size	body	整数	镜像数据的大小，以字节为单位。该值可能是 null（JSON null 数据类型）。
status	body	字符串	镜像状态。
tags	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。
virtual_size	body	整数	镜像的虚拟大小。该值可能是 null（JSON null 数据类型）。
visibility	body	字符串	镜像可见性，即镜像的访问权限。
direct_url (可选)	body	字符串	从外部存储访问镜像文件的 URL。仅当 Image 服务配置文件中的 show_image_direct_url 选项为 true 时才存在。 由于存在安全风险，默认情况下禁用此选项。
locations (可选)	body	数组	一系列对象，每个对象描述一个镜像位置。每个对象包含一个 url 键，其值为指定位置的 URL，以及一个 metadata 键，其值为一个键值对字典，包含适用于由 URL 指示的任何外部存储使用信息。此列表仅在 show_multiple_locations 选项在 Image 服务的配置文件中设置为 true 时出现。 由于存在安全风险，此选项默认禁用。

响应还可能包含作为键值对指定的其他属性，如果这些属性已由所有者或管理员添加到镜像中。

响应示例

{
    "status": "active",
    "name": "cirros-0.3.2-x86_64-disk",
    "tags": [],
    "container_format": "bare",
    "created_at": "2014-05-05T17:15:10Z",
    "disk_format": "qcow2",
    "updated_at": "2014-05-05T17:15:11Z",
    "visibility": "public",
    "self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
    "min_disk": 0,
    "protected": false,
    "id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
    "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
    "checksum": "64d7c1cd2b6f60c92c14662941cb7913",
    "os_hash_algo": "sha512",
    "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09",
    "os_hidden": false,
    "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
    "size": 13167616,
    "min_ram": 0,
    "schema": "/v2/schemas/image",
    "virtual_size": null
}

GET

/v2/images/{image_id}/tasks

显示与镜像关联的任务

详情

显示与镜像关联的任务。（自 Image API v2.12 起）

响应体包含与指定镜像关联的任务列表，可能为空。

先决条件

• 镜像必须存在。

正常响应代码：200

错误响应代码：404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

响应参数

名称	入参	类型	描述
tasks	body	数组	一个任务对象列表，与给定的镜像关联。

响应示例

{
  "tasks": [
    {
      "id": "ee22890e-8948-4ea6-9668-831f973c84f5",
      "image_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "request-id": "rrrrrrr-rrrr-rrrr-rrrr-rrrrrrrrrrrr",
      "user": "uuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuu",
      "type": "api_image_import",
      "status": "processing",
      "owner": "64f0efc9955145aeb06f297a8a6fe402",
      "expires_at": null,
      "created_at": "2020-12-18T05:20:38.000000",
      "updated_at": "2020-12-18T05:25:39.000000",
      "deleted_at": null,
      "deleted": false,
      "input": {
        "image_id": "829c729b-ebc4-4cc7-a164-6f43f1149b17",
        "import_req": {
          "method": {
            "name": "copy-image"
          },
          "all_stores": true,
          "all_stores_must_succeed": false
        },
        "backend": [
          "fast",
          "cheap",
          "slow",
          "reliable",
          "common"
        ]
      },
      "result": null,
      "message": "Copied 15 MiB"
    }
  ]
}

GET

/v2/images

列出镜像

详情

列出公共虚拟机 (VM) 镜像。（自 Image API v2.0 起）

分页

返回更大的镜像集合的子集，以及可用于获取下一组镜像的链接。您应始终检查是否存在 next 链接，并将其用作后续 HTTP GET 请求中的 URI。您应遵循此模式，直到不再提供 next 链接为止。

next 链接保留您在初始请求中发送的任何查询参数。您可以使用 first 链接跳转回集合的第一页。如果您希望手动分页浏览镜像，请使用 limit 和 marker 参数。

查询过滤器

列表操作接受查询参数以过滤响应。

客户端可以使用大多数镜像属性提供直接比较过滤器，例如 name=Ubuntu、visibility=public 等。

要使用镜像标签进行过滤，请使用过滤器 tag（注意单数）。要过滤多个标签，请在查询中单独包含每个标签。例如，要查找带有标签 ready 的镜像，请在查询字符串中包含 tag=ready。要查找标记为 ready 和 approved 的镜像，请在查询字符串中包含 tag=ready&tag=approved。（请注意，只有包含两个标签的镜像才会包含在响应中。）

客户端不能使用 json-schema 中的任何 link，例如 self、file 或 schema，来过滤响应。

您可以列出状态为 active、queued 或 saving 的 VM 镜像。

in 操作符

为了方便起见，您可以通过使用 in 操作符指定以下字段的多个值

• container_format

• disk_format

• id

• name

• status

对于大多数这些字段，用法很简单。例如，要列出处于 queued 或 saving 状态的镜像，请使用

GET /v2/images?status=in:saving,queued

要查找具有特定镜像 ID 列表的镜像，请使用

GET /v2/images?id=in:3afb79c1-131a-4c38-a87c-bc4b801d14e6,2e011209-660f-44b5-baf2-2eb4babae53d

使用 in 操作符与镜像的 name 属性可能会有点棘手，具体取决于您命名镜像的方式。一般规则是，如果镜像名称包含逗号 (,)，则必须将整个名称括在引号 (") 中。像往常一样，您必须对需要它的任何字符进行 URL 编码。

例如，要查找名为 glass, darkly 或 share me 的镜像，您将使用以下过滤器规范

GET v2/images?name=in:"glass,%20darkly",share%20me

与按名称进行常规过滤一样，您必须指定您正在查找的完整名称。因此，例如，查询字符串 name=in:glass,share 将仅匹配名称确切为 glass 或名称确切为 share 的镜像。它不会找到名为 glass, darkly 或名为 share me 的镜像。

大小比较过滤器

您可以使用 size_min 和 size_max 查询参数来过滤大于或小于镜像大小的镜像。大小（以字节为单位）是镜像在磁盘上的大小。

例如，要过滤容器以仅包含从 1 到 4 MB 的镜像，请将 size_min 查询参数设置为 1048576，并将 size_max 查询参数设置为 4194304。

时间比较过滤器

您可以使用比较运算符以及 created_at 或 updated_at 字段来过滤结果。首先指定运算符，冒号 (:) 作为分隔符，然后在 ISO 8601 格式 中指定时间。可用的比较运算符是

操作员	描述
gt	返回指定时间之后的结果。
gte	返回与指定时间匹配的任何结果以及任何较新的结果。
eq	返回与指定时间完全匹配的任何结果。
neq	返回与指定时间不匹配的任何结果。
lt	返回早于指定时间的结果。
lte	返回与指定时间匹配的任何结果以及任何较旧的结果。

例如

GET v2/images?created_at=gt:2016-04-18T21:38:54Z

排序

您可以使用查询参数来对此操作的结果进行排序。

• sort_key。按镜像属性排序。按镜像属性的自然排序方向排序。

• sort_dir。按排序方向排序。

• sort。按一个或多个属性和排序方向组合进行排序。如果您在集合中省略排序方向，则默认值为 desc。

要对响应进行排序，请使用 sort_key 和 sort_dir 查询参数

GET /v2/images?sort_key=name&sort_dir=asc&sort_key=status&sort_dir=desc

或者，指定 sort 查询参数

GET /v2/images?sort=name:asc,status:desc

注意

虽然此调用自此 API 的 2.0 版本以来一直可用，但它已从发布到发布不断增强。上述过滤和排序功能和语法适用于最新版本（Newton）。上述并非所有内容都将在早期版本中可用。

正常响应代码：200

错误响应代码：400、401、403

请求

名称	入参	类型	描述
limit (可选)	查询	整数	请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。
name (可选)	查询	字符串	按名称过滤响应，作为一个字符串。有效值是镜像的名称。
owner（可选）	查询	字符串	按项目（也称为“租户”）ID 过滤响应。仅显示由指定所有者与您共享的镜像。
protected (可选)	查询	布尔值	按镜像的“protected”属性过滤响应。有效值为“true”、“false”（必须全部小写）。任何其他值都将导致 400 响应。
status (可选)	查询	整数	按镜像状态过滤响应。
tag（可选）	查询	字符串	按指定的标签值过滤响应。可以重复，但请记住您正在进行合取查询，因此只有包含所有指定标签的镜像才会出现在响应中。
visibility (可选)	查询	字符串	按镜像可见性值过滤响应。有效值为 public、private、community、shared 或 all。（请注意，如果您过滤 shared，响应中包含的镜像将仅是您的成员状态为 accepted 的镜像，除非您在请求中显式包含 member_status 过滤器。）如果您省略此参数，响应将显示 public、private 以及成员状态为 accepted 的 shared 镜像。
os_hidden（可选）	查询	布尔值	当 true 时，过滤响应以仅显示“隐藏”镜像。默认情况下，“隐藏”镜像不包含在镜像列表响应中。（自 Image API v2.7 起）
member_status（可选）	查询	字符串	按成员状态过滤响应。有效值为 accepted、pending、rejected 或 all。默认值为 accepted。
size_max（可选）	查询	字符串	按最大镜像大小（以字节为单位）过滤响应。
size_min（可选）	查询	字符串	按最小镜像大小（以字节为单位）过滤响应。
created_at (可选)	查询	字符串	指定基于资源创建日期和时间的比较过滤器。（请参阅 时间比较过滤器）。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。 例如，2015-08-27T09:49:58-05:00。 如果省略时区，则假定为 UTC 时区。
updated_at (可选)	查询	字符串	指定基于资源最近修改日期和时间的比较过滤器。（请参阅 时间比较过滤器）。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。 例如，2015-08-27T09:49:58-05:00。 如果省略时区，则假定为 UTC 时区。
sort_dir (可选)	查询	字符串	按一组一个或多个排序方向和属性（sort_key）组合对响应进行排序。排序方向的有效值为 asc（升序）或 desc（降序）。如果您在集合中省略排序方向，则默认值为 desc。
sort_key (可选)	查询	字符串	按属性（例如 name、id 或 updated_at）对响应进行排序。默认值为 created_at。API 使用镜像 sort_key 属性的自然排序方向。
sort (可选)	查询	字符串	按一个或多个属性和排序方向组合对响应进行排序。您还可以设置多个排序键和方向。默认方向为 desc。 使用逗号 (,) 分隔多个值。例如 GET /v2/images?sort=name:asc,status:desc

响应参数

名称	入参	类型	描述
images	body	数组	一个镜像对象列表，如 镜像架构 中所述。
first	body	字符串	响应第一页的 URI。
下一个	body	字符串	响应下一页的 URI。不会出现在响应的最后一页上。
schema	body	字符串	描述镜像列表的模式的 URL。

响应示例

{
    "images": [
        {
            "status": "active",
            "name": "cirros-0.3.2-x86_64-disk",
            "tags": [],
            "container_format": "bare",
            "created_at": "2014-11-07T17:07:06Z",
            "disk_format": "qcow2",
            "updated_at": "2014-11-07T17:19:09Z",
            "visibility": "public",
            "self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
            "min_disk": 0,
            "protected": false,
            "id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
            "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
            "checksum": "64d7c1cd2b6f60c92c14662941cb7913",
            "os_hash_algo": "sha512",
            "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09",
            "os_hidden": false,
            "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
            "size": 13167616,
            "min_ram": 0,
            "schema": "/v2/schemas/image",
            "virtual_size": null
        },
        {
            "status": "active",
            "name": "F17-x86_64-cfntools",
            "tags": [],
            "container_format": "bare",
            "created_at": "2014-10-30T08:23:39Z",
            "disk_format": "qcow2",
            "updated_at": "2014-11-03T16:40:10Z",
            "visibility": "public",
            "self": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c",
            "min_disk": 0,
            "protected": false,
            "id": "781b3762-9469-4cec-b58d-3349e5de4e9c",
            "file": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c/file",
            "checksum": "afab0f79bac770d61d24b4d0560b5f70",
            "os_hash_algo": "sha512",
            "os_hash_value": "ea3e20140df1cc65f53d4c5b9ee3b38d0d6868f61bbe2230417b0f98cef0e0c7c37f0ebc5c6456fa47f013de48b452617d56c15fdba25e100379bd0e81ee15ec",
            "os_hidden": false,
            "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
            "size": 476704768,
            "min_ram": 0,
            "schema": "/v2/schemas/image",
            "virtual_size": null
        }
    ],
    "schema": "/v2/schemas/images",
    "first": "/v2/images"
}

PATCH

/v2/images/{image_id}

更新镜像

详情

更新一个镜像。(自 Image API v2.0)

从概念上讲，您通过修补镜像的 JSON 表示来更新镜像记录，传递符合以下媒体类型之一的请求体

• application/openstack-images-v2.0-json-patch (已弃用)

• application/openstack-images-v2.1-json-patch (自 Image API v2.1)

尝试使用其他媒体类型进行 PATCH 调用将导致响应代码 415（不支持的媒体类型）。

application/openstack-images-v2.1-json-patch 媒体类型提供了 JavaScript Object Notation (JSON) Patch RFC6902 中定义的有用且兼容的功能子集，该标准定义了 application/json-patch+json 媒体类型。

注意

application/openstack-images-v2.0-json-patch 媒体类型基于标准的草案 4。其使用已被弃用。

有关 PATCH 方法和可用媒体类型的更多信息，请参阅 Image API v2 HTTP PATCH 媒体类型。

尝试修改某些镜像属性将导致整个请求因 403（禁止）响应代码而失败

• 尝试修改由 Image Service 管理的“基本”镜像属性。这些属性在 镜像 Schema 中指定为只读。

• 尝试创建或修改您没有权限执行的镜像属性 (自 Image API v2.2)。这取决于 OpenStack 云中属性保护的配置方式。有关详细信息，请参阅您的云的文档。

• 尝试删除唯一的镜像位置，或将镜像位置替换为空列表 (自 Image API v2.4)。

• 尝试设置或修改具有保留名称的属性，例如任何以 os_glance 命名空间为前缀的属性。

尝试将位置路径添加到状态不是 queued 或 active 的镜像将导致 409（冲突）响应代码 (自 Image API v2.4)。

正常响应代码：200

错误响应代码：400、401、403、404、409、413、415

请求

名称	入参	类型	描述
Content-Type	标头	字符串	请求体的媒体类型描述符。使用 application/openstack-images-v2.1-json-patch。（您也可以使用 application/openstack-images-v2.0-json-patch，但请记住它已被弃用。）
image_id	路径	字符串	镜像的 UUID。

请求体必须符合 application/openstack-images-v2.1-json-patch 媒体类型定义（见上文）。

请求示例

[
    {
        "op": "replace",
        "path": "/name",
        "value": "Fedora 17"
    },
    {
        "op": "replace",
        "path": "/tags",
        "value": [
            "fedora",
            "beefy"
        ]
    }
]

响应参数

名称	入参	类型	描述
checksum	body	字符串	镜像数据的 MD5 哈希值。该值可能是 null（JSON null 数据类型），因为从 Victoria 版本开始，Image 服务不再填充此字段。为了与旧镜像兼容，它仍然存在。要验证镜像数据，请改用安全多哈希字段 os_hash_algo 和 os_hash_value。
container_format	body	enum	镜像容器的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 容器格式。 示例格式包括：ami、ari、aki、bare、ovf、ova、docker 或 compressed。 该值可能是 null（JSON null 数据类型）。 Train 变更：compressed 容器格式是一个受支持的值。
created_at	body	字符串	创建资源的时间和日期。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 例如，2015-08-27T09:49:58-05:00。 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。
disk_format	body	enum	磁盘的格式。 值可能因特定 OpenStack 云中可用的配置而异。请参阅云本身的 Image Schema 响应以获取可用的有效值。有关更多信息，请参阅 Glance 文档中的 磁盘格式。 示例格式包括：ami、ari、aki、vhd、vhdx、vmdk、raw、qcow2、vdi、ploop 或 iso。 该值可能是 null（JSON null 数据类型）。 Newton 变更：vhdx 磁盘格式是一个受支持的值。 Ocata 变更：ploop 磁盘格式是一个受支持的值。
file	body	字符串	虚拟机的镜像文件的 URL。
id	body	字符串	一个唯一的、用户定义的镜像 UUID，格式为 nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn 其中 n 是从 0 到 f 或 F 的十六进制数字。 例如 b2173dd3-7ad6-4362-baa6-a68bce3565cb 如果您省略此值，API 将为镜像生成 UUID。
min_disk	body	整数	启动镜像所需的磁盘空间量，以 GB 为单位。该值可能是 null（JSON null 数据类型）。
min_ram	body	整数	启动镜像所需的 RAM 数量，以 MB 为单位。该值可能是 null（JSON null 数据类型）。
name	body	字符串	镜像的名称。该值可能是 null（JSON null 数据类型）。
owner	body	字符串	镜像所有者的标识符，通常是项目（也称为“租户”）ID。该值可能是 null（JSON null 数据类型）。
os_hash_algo	body	字符串	用于计算此镜像的镜像数据的安全哈希的算法。计算结果显示为 os_hash_value 属性的值。该算法由云操作员选择；它可能不由最终用户配置。（自 Image API v2.7 起）
os_hash_value	body	字符串	使用 os_hash_algo 属性的值作为名称的算法计算的镜像数据的安全哈希的十六进制摘要。该值可能是 null（JSON null 数据类型），如果尚未与此镜像关联数据，或者如果使用 Image 服务 API 的早期版本创建镜像，则可能是如此。（自 Image API v2.7 起）
os_hidden	body	布尔值	此字段控制是否在默认镜像列表响应中显示镜像。 “隐藏”镜像在某种程度上已过时（例如，它可能未应用最新的更新），因此不应是用户的首选，但它不会被删除，因为它可能需要用于服务器重建。通过将其隐藏在默认镜像列表中，最终用户更容易找到并使用此镜像的更新版本。（自 Image API v2.7 起）
protected	body	布尔值	一个布尔值，必须为 false，否则无法删除镜像。
schema	body	字符串	描述虚拟机的镜像模式的 URL。
self	body	字符串	虚拟机的镜像的 URL。
size	body	整数	镜像数据的大小，以字节为单位。该值可能是 null（JSON null 数据类型）。
status	body	字符串	镜像状态。
tags	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。
visibility	body	字符串	镜像可见性，即镜像的访问权限。
direct_url (可选)	body	字符串	从外部存储访问镜像文件的 URL。仅当 Image 服务配置文件中的 show_image_direct_url 选项为 true 时才存在。 由于存在安全风险，默认情况下禁用此选项。
locations (可选)	body	数组	一系列对象，每个对象描述一个镜像位置。每个对象包含一个 url 键，其值为指定位置的 URL，以及一个 metadata 键，其值为一个键值对字典，包含适用于由 URL 指示的任何外部存储使用信息。此列表仅在 show_multiple_locations 选项在 Image 服务的配置文件中设置为 true 时出现。 由于存在安全风险，此选项默认禁用。

响应示例

{
    "checksum": "710544e7f0c828b42f51207342622d33",
    "container_format": "ovf",
    "created_at": "2016-06-29T16:13:07Z",
    "disk_format": "vhd",
    "file": "/v2/images/2b61ed2b-f800-4da0-99ff-396b742b8646/file",
    "id": "2b61ed2b-f800-4da0-99ff-396b742b8646",
    "min_disk": 20,
    "min_ram": 512,
    "name": "Fedora 17",
    "owner": "02a7fb2dd4ef434c8a628c511dcbbeb6",
    "os_hash_algo": "sha512",
    "os_hash_value": "ef7d1ed957ffafefb324d50ebc6685ed03d0e64549762ba94a1c44e92270cdbb69d7437dd1e101d00dd41684aaecccad1edc5c2e295e66d4733025b052497844",
    "os_hidden": false,
    "protected": false,
    "schema": "/v2/schemas/image",
    "self": "/v2/images/2b61ed2b-f800-4da0-99ff-396b742b8646",
    "size": 21909,
    "status": "active",
    "tags": [
        "beefy",
        "fedora"
    ],
    "updated_at": "2016-07-25T14:48:18Z",
    "virtual_size": null,
    "visibility": "private"
}

DELETE

/v2/images/{image_id}

删除镜像

详情

(自 Image API v2.0) 删除一个镜像。

您无法删除 protected 属性设置为 true (布尔值) 的镜像。

先决条件

• 您可以删除任何状态的镜像，除了 deleted。

• 镜像的 protected 属性不能为 true。

• 您有权根据配置的镜像删除策略执行镜像删除操作。

同步后置条件

• 响应为空，并返回 HTTP 204 响应代码。

• API 从镜像索引中删除镜像。

• 如果镜像在存储后端具有关联的二进制镜像数据，OpenStack Image 服务将删除该数据。

正常响应代码：204

错误响应代码：400、401、403、404、409

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

POST

/v2/images/{image_id}/actions/deactivate

停用镜像

详情

停用一个镜像。(自 Image API v2.3)

默认情况下，此操作仅限于管理员。

如果您尝试下载已停用的镜像，您将收到 403（禁止）响应代码。此外，只有管理员才能查看已停用镜像的镜像位置。

停用操作如果镜像状态不是 active 或 deactivated，则会返回错误。

先决条件

• 镜像必须存在。

正常响应代码：204

错误响应代码：400、403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

POST

/v2/images/{image_id}/actions/reactivate

重新激活镜像

详情

重新激活一个镜像。(自 Image API v2.3)

默认情况下，此操作仅限于管理员。

重新激活操作如果镜像状态不是 active 或 deactivated，则会返回错误。

先决条件

• 镜像必须存在。

正常响应代码：204

错误响应代码：400、403、404

Request

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

POST

/v2/images/{image_id}/locations

添加位置

详情

将位置添加到状态为 queued 的镜像。接受位置 URL、JSON 主体中的验证数据。

仅当您是镜像的所有者或具有服务角色时，才能添加位置。如果不满足这些条件，将返回 403（禁止）。

尝试将位置路径添加到状态不是 queued 的镜像将导致 409（冲突）响应代码

尝试在验证数据中提供不正确的哈希值（在 http 存储的情况下）到镜像将导致 400（错误请求）响应代码。

正常响应代码：200

错误响应代码：400、403、404、409

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
url	body	字符串	要添加到镜像中的新位置的 URL。
validation_data（可选）	body	对象	包含 os_hash_value 和 os_hash_algo 值的键值对形式的镜像元数据，要添加到镜像中。如果未传递 do_secure_hash，则位置添加 API 的使用者有责任在 validation_data 中提供正确的值。

请求示例

{
    "url": "cinder://lvmdriver-1/39e6ffab-7502-4199-9609-416601615ca3",
    "validation_data": {
        "os_hash_algo": "sha512",
        "os_hash_value": "c5041ae163cf0f65600acfe7f6a63f212101687d41a57a4e18ffd2a07a452cd8175b8f5a4868dd2330bfe5ae123f18216bdbc9e0f80d131e64b94913a7b40bb5"
    }
}

GET

/v2/images/{image_id}/locations

获取位置

详情

列出与镜像关联的所有位置，包括位置 URL 和存储 ID，仅服务用户可访问，对于非服务用户，API 将返回禁止。

正常响应代码：200

错误响应代码：403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

此调用不允许请求体。

响应参数

名称	入参	类型	描述
locations (可选)	body	数组	一系列对象，每个对象描述一个镜像位置。每个对象包含一个 url 键，其值为指定位置的 URL，以及一个 metadata 键，其值为一个键值对字典，包含适用于由 URL 指示的任何外部存储使用信息。此列表仅在 show_multiple_locations 选项在 Image 服务的配置文件中设置为 true 时出现。 由于存在安全风险，此选项默认禁用。

响应示例

[
    {
        "url": "cinder://lvmdriver-1/39e6ffab-7502-4199-9609-416601615ca3",
        "metadata": {
            "store": "lvmdriver-1"
        }
    }
]

共享

可以通过在镜像上创建成员来在项目之间共享镜像。镜像成员对镜像具有只读权限。以下调用允许您创建、列出、更新和删除镜像成员。

注意

镜像成员是与镜像共享的消费者的标识符。在 OpenStack 云中，如果镜像的 owner 属性的值是项目 ID，则用于 member_id 的适当标识符是目标项目的消费者项目 ID（以前称为“租户 ID”）。

• 镜像共享是项目到项目的。因此，目标项目中的所有用户都有权访问该镜像。您无法仅与目标项目中的特定用户共享镜像。

当共享镜像时，成员会立即获得对镜像的访问权限。为了防止向其他用户的镜像列表发送垃圾邮件，共享的镜像不会出现在成员的镜像列表中，直到成员“接受”该镜像为止。

只有镜像所有者才能创建成员。只有镜像成员才能修改其成员状态。

有关镜像共享的概念性概述，包括建议的工作流程，请参阅 Image API v2 共享。

注意

如果您不想维护与特定镜像消费者的共享关系，而是想让镜像对所有用户可用，您可以将镜像的 visibility 属性更新为 community。

• 在某些云中，可能禁止“社区化”镜像或仅限于受信任的用户。有关详细信息，请参阅您的云的本地文档。

POST

/v2/images/{image_id}/members

创建镜像成员

详情

添加租户 ID 作为镜像成员。(自 Image API v2.1)

先决条件

• 镜像必须存在。

• 镜像必须具有 visibility 值为 shared。

• 您必须是镜像的所有者。

同步后置条件

• 在正确的权限下，您可以通过 API 调用查看镜像成员的状态为 pending。

故障排除

• 即使您具有正确的权限，如果 visibility 属性未设置为 shared，服务将返回 HTTP 403 响应代码。确保您满足先决条件并再次运行请求。如果请求再次失败，请查看您的 API 请求。

• 如果成员已经是镜像的成员，服务将返回 Conflict (409) 响应代码。如果您打算指定不同的成员，请再次运行请求。

正常响应代码：200

错误响应代码：400、401、403、404、409、413

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
member（成员）	body	字符串	镜像成员的 ID。镜像成员通常是与镜像共享的项目（也称为“租户”）。

请求示例

{
    "member": "8989447062e04a818baf9e073fd04fa7"
}

响应参数

名称	入参	类型	描述
created_at	body	字符串	创建资源的时间和日期。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 例如，2015-08-27T09:49:58-05:00。 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。
image_id	body	字符串	镜像的 UUID。
member_id	body	字符串	镜像成员的 ID。镜像成员通常是与镜像共享的项目（也称为“租户”）。
schema	body	字符串	描述镜像成员的模式的 URL。
status	body	字符串	此镜像成员的状态。值为 pending、accepted、rejected 中的一个。
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。

响应示例

{
    "created_at": "2013-09-20T19:22:19Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member",
    "status": "pending",
    "updated_at": "2013-09-20T19:25:31Z"
}

GET

/v2/images/{image_id}/members/{member_id}

显示镜像成员详细信息

详情

显示镜像成员详细信息。(自 Image API v2.1)

响应体是单个镜像成员实体。

先决条件

• 镜像必须存在。

• 镜像必须具有 visibility 值为 shared。

• 您必须是调用中引用的镜像的所有者或成员。

正常响应代码：200

错误响应代码：400、401、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
member_id	路径	字符串	镜像成员的 ID。镜像成员通常是与镜像共享的项目（也称为“租户”）。

响应参数

名称	入参	类型	描述
created_at	body	字符串	创建资源的时间和日期。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 例如，2015-08-27T09:49:58-05:00。 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。
image_id	body	字符串	镜像的 UUID。
member_id	body	字符串	镜像成员的 ID。镜像成员通常是与镜像共享的项目（也称为“租户”）。
schema	body	字符串	描述镜像成员的模式的 URL。
status	body	字符串	此镜像成员的状态。值为 pending、accepted、rejected 中的一个。
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。

响应示例

{
    "status": "pending",
    "created_at": "2013-11-26T07:21:21Z",
    "updated_at": "2013-11-26T07:21:21Z",
    "image_id": "0ae74cc5-5147-4239-9ce2-b0c580f7067e",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member"
}

GET

/v2/images/{image_id}/members

列出镜像成员

详情

列出共享此镜像的租户。(自 Image API v2.1)

如果镜像所有者发出此调用，将返回完整的成员列表。

如果作为镜像成员的用户发出此调用，成员列表中仅包含该用户的信息。

如果不是镜像成员的用户发出此调用，则调用将返回 HTTP 404 响应代码。

先决条件

• 镜像必须存在。

• 镜像必须具有 visibility 值为 shared。

• 您必须是镜像的所有者或成员。

正常响应代码：200

错误响应代码：400、401、403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

响应参数

名称	入参	类型	描述
members	body	数组	一个成员对象列表，如 镜像成员 Schema 中所述。每个成员对象描述一个与该镜像共享的成员。
schema	body	字符串	描述镜像成员列表的模式的 URL。

响应示例

{
    "members": [
        {
            "created_at": "2013-10-07T17:58:03Z",
            "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
            "member_id": "123456789",
            "schema": "/v2/schemas/member",
            "status": "pending",
            "updated_at": "2013-10-07T17:58:03Z"
        },
        {
            "created_at": "2013-10-07T17:58:55Z",
            "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
            "member_id": "987654321",
            "schema": "/v2/schemas/member",
            "status": "accepted",
            "updated_at": "2013-10-08T12:08:55Z"
        }
    ],
    "schema": "/v2/schemas/members"
}

PUT

/v2/images/{image_id}/members/{member_id}

更新镜像成员

详情

设置镜像成员的状态。(自 Image API v2.1)

此调用允许镜像成员更改其成员状态。

当镜像与您共享时，您会立即获得对镜像的访问权限。更新镜像上的成员状态对您的影响是，它会影响镜像是否会出现在您的镜像列表响应中。

• 当镜像与您共享时，您的 member_status 为 pending。除非您通过使用镜像的 ID 发出 show image detail 请求，或发出专门查找状态为 pending 的共享镜像的镜像列表调用来查找它，否则您将看不到该镜像。这样，其他用户就无法用您可能不想看到的镜像“发送垃圾邮件”到您的镜像列表中。

• 如果您想在您的镜像列表中看到特定的共享镜像，那么您必须使用此调用将您的成员状态更改为 accepted。

• 镜像所有者可以看到您的镜像成员状态，但所有者无法更改状态。只有您（或管理员）才能执行此操作。

• 有三种成员状态值：pending、accepted 和 rejected。pending 和 rejected 状态在功能上是相同的。区别在于 pending 表示所有者您尚未更新镜像，因此您可能不知道它已与您共享。 rejected 状态表示您知道镜像存在，并且您明确决定不想在镜像列表响应中看到它。

有关图像共享的更详细讨论，请参阅 Image API v2 Sharing。

先决条件

• 镜像必须存在。

• 镜像必须具有 visibility 值为 shared。

• 您必须是调用中引用的镜像的成员。

同步后置条件

• 如果您将成员状态更新为 accepted 并且具有正确的权限，您将在列出镜像响应中看到该镜像。

• 在具有正确权限的情况下，您可以发出 API 调用来查看镜像的更新成员状态。

正常响应代码：200

错误响应代码：400、401、404、403

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
member_id	路径	字符串	镜像成员的 ID。镜像成员通常是与镜像共享的项目（也称为“租户”）。
status	body	字符串	此镜像成员的状态。值为 pending、accepted、rejected 中的一个。

请求示例

{
    "status": "accepted"
}

响应参数

名称	入参	类型	描述
created_at	body	字符串	创建资源的时间和日期。 日期和时间戳格式为 ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm 例如，2015-08-27T09:49:58-05:00。 如果包含 ±hh:mm 值，则为 UTC 的时区偏移量。
image_id	body	字符串	镜像的 UUID。
member_id	body	字符串	镜像成员的 ID。镜像成员通常是与镜像共享的项目（也称为“租户”）。
schema	body	字符串	描述镜像成员的模式的 URL。
status	body	字符串	此镜像成员的状态。值为 pending、accepted、rejected 中的一个。
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。

响应示例

{
    "created_at": "2013-09-20T19:22:19Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member",
    "status": "accepted",
    "updated_at": "2013-09-20T20:15:31Z"
}

DELETE

/v2/images/{image_id}/members/{member_id}

删除镜像成员

详情

从镜像的成员列表中删除租户 ID。(自 Image API v2.1 起)

先决条件

• 镜像必须存在。

• 镜像必须具有 visibility 值为 shared。

• 您必须是镜像的所有者。

同步后置条件

• API 会从镜像成员中删除该成员。

故障排除

• 即使您具有正确的权限，如果您不是镜像的所有者，或者指定了错误的镜像 ID 或成员 ID，该调用将返回 HTTP 403 或 404 响应代码。请确保您满足先决条件并再次运行请求。如果请求再次失败，请检查您的 API 请求 URI。

正常响应代码：204

错误响应代码：400、401、403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
member_id	路径	字符串	镜像成员的 ID。镜像成员通常是与镜像共享的项目（也称为“租户”）。

镜像标签

添加和删除镜像标签。

镜像标签也可以通过 更新镜像 调用进行修改。

PUT

/v2/images/{image_id}/tags/{tag}

添加镜像标签

详情

将标签添加到镜像。(自 Image API v2.0 起)

正常响应代码：204

错误响应代码：400、401、403、404、413

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
tag	路径	字符串	镜像标签。标签的长度限制为 255 个字符。您可能希望使用可以在 URL 中轻松编写的字符。

DELETE

/v2/images/{image_id}/tags/{tag}

删除镜像标签

详情

从镜像中删除标签。(自 Image API v2.0 起)

正常响应代码：204

错误响应代码：400、401、403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
tag	路径	字符串	镜像标签。标签的长度限制为 255 个字符。您可能希望使用可以在 URL 中轻松编写的字符。

镜像模式

获取表示 Images v2 API 中各种实体的 JSON 模式文档。

GET

/v2/schemas/images

显示镜像模式

详情

(自 Images v2.0 起)

显示表示 images 实体的 JSON 模式文档。

images 实体是镜像实体的容器。

以下模式仅为示例。请仅将 API 调用的响应视为权威。

正常响应代码：200

错误响应代码：400, 401

请求

此操作没有请求参数，也不接受请求体。

响应示例

{
    "links": [
        {
            "href": "{first}",
            "rel": "first"
        },
        {
            "href": "{next}",
            "rel": "next"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "images",
    "properties": {
        "first": {
            "type": "string"
        },
        "images": {
            "items": {
                "additionalProperties": {
                    "type": "string"
                },
                "links": [
                    {
                        "href": "{self}",
                        "rel": "self"
                    },
                    {
                        "href": "{file}",
                        "rel": "enclosure"
                    },
                    {
                        "href": "{schema}",
                        "rel": "describedby"
                    }
                ],
                "name": "image",
                "properties": {
                    "architecture": {
                        "description": "Operating system architecture as specified in https://docs.openstack.org/python-glanceclient/2025.2/cli/property-keys.html",
                        "is_base": false,
                        "type": "string"
                    },
                    "checksum": {
                        "description": "md5 hash of image contents.",
                        "maxLength": 32,
                        "readOnly": true,
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "container_format": {
                        "description": "Format of the container",
                        "enum": [
                            null,
                            "ami",
                            "ari",
                            "aki",
                            "bare",
                            "ovf",
                            "ova",
                            "docker",
                            "compressed"
                        ],
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "created_at": {
                        "description": "Date and time of image registration",
                        "readOnly": true,
                        "type": "string"
                    },
                    "direct_url": {
                        "description": "URL to access the image file kept in external store",
                        "readOnly": true,
                        "type": "string"
                    },
                    "disk_format": {
                        "description": "Format of the disk",
                        "enum": [
                            null,
                            "ami",
                            "ari",
                            "aki",
                            "vhd",
                            "vhdx",
                            "vmdk",
                            "raw",
                            "qcow2",
                            "vdi",
                            "iso",
                            "ploop"
                        ],
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "file": {
                        "description": "An image file url",
                        "readOnly": true,
                        "type": "string"
                    },
                    "id": {
                        "description": "An identifier for the image",
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": "string"
                    },
                    "instance_uuid": {
                        "description": "Metadata which can be used to record which instance this image is associated with. (Informational only, does not create an instance snapshot.)",
                        "is_base": false,
                        "type": "string"
                    },
                    "kernel_id": {
                        "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
                        "is_base": false,
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "locations": {
                        "description": "A set of URLs to access the image file kept in external store",
                        "items": {
                            "properties": {
                                "metadata": {
                                    "type": "object"
                                },
                                "url": {
                                    "maxLength": 255,
                                    "type": "string"
                                }
                            },
                            "required": [
                                "url",
                                "metadata"
                            ],
                            "type": "object"
                        },
                        "type": "array"
                    },
                    "min_disk": {
                        "description": "Amount of disk space (in GB) required to boot image.",
                        "type": "integer"
                    },
                    "min_ram": {
                        "description": "Amount of ram (in MB) required to boot image.",
                        "type": "integer"
                    },
                    "name": {
                        "description": "Descriptive name for the image",
                        "maxLength": 255,
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "os_distro": {
                        "description": "Common name of operating system distribution as specified in https://docs.openstack.org/python-glanceclient/2025.2/cli/property-keys.html",
                        "is_base": false,
                        "type": "string"
                    },
                    "os_hash_algo": {
                        "description": "Algorithm to calculate the os_hash_value",
                        "maxLength": 64,
                        "readOnly": true,
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "os_hash_value": {
                        "description": "Hexdigest of the image contents using the algorithm specified by the os_hash_algo",
                        "maxLength": 128,
                        "readOnly": true,
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "os_hidden": {
                        "description": "If true, image will not appear in default image list response.",
                        "type": "boolean"
                    },
                    "os_version": {
                        "description": "Operating system version as specified by the distributor",
                        "is_base": false,
                        "type": "string"
                    },
                    "owner": {
                        "description": "Owner of the image",
                        "maxLength": 255,
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "protected": {
                        "description": "If true, image will not be deletable.",
                        "type": "boolean"
                    },
                    "ramdisk_id": {
                        "description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
                        "is_base": false,
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "schema": {
                        "description": "An image schema url",
                        "readOnly": true,
                        "type": "string"
                    },
                    "self": {
                        "description": "An image self url",
                        "readOnly": true,
                        "type": "string"
                    },
                    "size": {
                        "description": "Size of image file in bytes",
                        "readOnly": true,
                        "type": [
                            "null",
                            "integer"
                        ]
                    },
                    "status": {
                        "description": "Status of the image",
                        "enum": [
                            "queued",
                            "saving",
                            "active",
                            "killed",
                            "deleted",
                            "pending_delete",
                            "deactivated",
                            "uploading",
                            "importing"
                        ],
                        "readOnly": true,
                        "type": "string"
                    },
                    "tags": {
                        "description": "List of strings related to the image",
                        "items": {
                            "maxLength": 255,
                            "type": "string"
                        },
                        "type": "array"
                    },
                    "updated_at": {
                        "description": "Date and time of the last image modification",
                        "readOnly": true,
                        "type": "string"
                    },
                    "virtual_size": {
                        "description": "Virtual size of image in bytes",
                        "readOnly": true,
                        "type": [
                            "null",
                            "integer"
                        ]
                    },
                    "visibility": {
                        "description": "Scope of image accessibility",
                        "enum": [
                            "public",
                            "private"
                        ],
                        "type": "string"
                    }
                }
            },
            "type": "array"
        },
        "next": {
            "type": "string"
        },
        "schema": {
            "type": "string"
        }
    }
}

GET

/v2/schemas/image

显示镜像模式

详情

(自 Images v2.0 起)

显示表示 image 实体的 JSON 模式文档。

以下模式仅为示例。请仅将 API 调用的响应视为权威。

正常响应代码：200

错误响应代码：400, 401

请求

此操作没有请求参数，也不接受请求体。

响应示例

{
    "additionalProperties": {
        "type": "string"
    },
    "links": [
        {
            "href": "{self}",
            "rel": "self"
        },
        {
            "href": "{file}",
            "rel": "enclosure"
        },
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "image",
    "properties": {
        "architecture": {
            "description": "Operating system architecture as specified in https://docs.openstack.org/python-glanceclient/2025.2/cli/property-keys.html",
            "is_base": false,
            "type": "string"
        },
        "checksum": {
            "description": "md5 hash of image contents.",
            "maxLength": 32,
            "readOnly": true,
            "type": [
                "null",
                "string"
            ]
        },
        "container_format": {
            "description": "Format of the container",
            "enum": [
                null,
                "ami",
                "ari",
                "aki",
                "bare",
                "ovf",
                "ova",
                "docker",
                "compressed"
            ],
            "type": [
                "null",
                "string"
            ]
        },
        "created_at": {
            "description": "Date and time of image registration",
            "readOnly": true,
            "type": "string"
        },
        "direct_url": {
            "description": "URL to access the image file kept in external store",
            "readOnly": true,
            "type": "string"
        },
        "disk_format": {
            "description": "Format of the disk",
            "enum": [
                null,
                "ami",
                "ari",
                "aki",
                "vhd",
                "vhdx",
                "vmdk",
                "raw",
                "qcow2",
                "vdi",
                "iso",
                "ploop"
            ],
            "type": [
                "null",
                "string"
            ]
        },
        "file": {
            "description": "An image file url",
            "readOnly": true,
            "type": "string"
        },
        "id": {
            "description": "An identifier for the image",
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": "string"
        },
        "instance_uuid": {
            "description": "Metadata which can be used to record which instance this image is associated with. (Informational only, does not create an instance snapshot.)",
            "is_base": false,
            "type": "string"
        },
        "kernel_id": {
            "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
            "is_base": false,
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": [
                "null",
                "string"
            ]
        },
        "locations": {
            "description": "A set of URLs to access the image file kept in external store",
            "items": {
                "properties": {
                    "metadata": {
                        "type": "object"
                    },
                    "url": {
                        "maxLength": 255,
                        "type": "string"
                    },
                    "validation_data": {
                        "description": "Values to be used to populate the corresponding image properties. If the image status is not queued, values must exactly match those already contained in the image properties.",
                        "type": "object",
                        "writeOnly": true,
                        "additionalProperties": false,
                        "properties": {
                            "checksum": {
                                "type": "string",
                                "minLength": 32,
                                "maxLength": 32
                            },
                            "os_hash_algo": {
                                "type": "string",
                                "maxLength": 64
                            },
                            "os_hash_value": {
                                "type": "string",
                                "maxLength": 128
                            }
                        },
                        "required": [
                            "os_hash_algo",
                            "os_hash_value"
                        ]
                    }
                },
                "required": [
                    "url",
                    "metadata"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "min_disk": {
            "description": "Amount of disk space (in GB) required to boot image.",
            "type": "integer"
        },
        "min_ram": {
            "description": "Amount of ram (in MB) required to boot image.",
            "type": "integer"
        },
        "name": {
            "description": "Descriptive name for the image",
            "maxLength": 255,
            "type": [
                "null",
                "string"
            ]
        },
        "os_distro": {
            "description": "Common name of operating system distribution as specified in https://docs.openstack.org/python-glanceclient/2025.2/cli/property-keys.html",
            "is_base": false,
            "type": "string"
        },
        "os_hash_algo": {
            "description": "Algorithm to calculate the os_hash_value",
            "maxLength": 64,
            "readOnly": true,
            "type": [
                "null",
                "string"
            ]
        },
        "os_hash_value": {
            "description": "Hexdigest of the image contents using the algorithm specified by the os_hash_algo",
            "maxLength": 128,
            "readOnly": true,
            "type": [
                "null",
                "string"
            ]
        },
        "os_hidden": {
            "description": "If true, image will not appear in default image list response.",
            "type": "boolean"
        },
        "os_version": {
            "description": "Operating system version as specified by the distributor",
            "is_base": false,
            "type": "string"
        },
        "owner": {
            "description": "Owner of the image",
            "maxLength": 255,
            "type": [
                "null",
                "string"
            ]
        },
        "protected": {
            "description": "If true, image will not be deletable.",
            "type": "boolean"
        },
        "ramdisk_id": {
            "description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
            "is_base": false,
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": [
                "null",
                "string"
            ]
        },
        "schema": {
            "description": "An image schema url",
            "readOnly": true,
            "type": "string"
        },
        "self": {
            "description": "An image self url",
            "readOnly": true,
            "type": "string"
        },
        "size": {
            "description": "Size of image file in bytes",
            "readOnly": true,
            "type": [
                "null",
                "integer"
            ]
        },
        "status": {
            "description": "Status of the image",
            "enum": [
                "queued",
                "saving",
                "active",
                "killed",
                "deleted",
                "pending_delete",
                "deactivated",
                "uploading",
                "importing"
            ],
            "readOnly": true,
            "type": "string"
        },
        "tags": {
            "description": "List of strings related to the image",
            "items": {
                "maxLength": 255,
                "type": "string"
            },
            "type": "array"
        },
        "updated_at": {
            "description": "Date and time of the last image modification",
            "readOnly": true,
            "type": "string"
        },
        "virtual_size": {
            "description": "Virtual size of image in bytes",
            "readOnly": true,
            "type": [
                "null",
                "integer"
            ]
        },
        "visibility": {
            "description": "Scope of image accessibility",
            "enum": [
                "public",
                "private"
            ],
            "type": "string"
        }
    }
}

GET

/v2/schemas/members

显示镜像成员模式

详情

(自 Images v2.1 起)

显示表示 image members 实体的 JSON 模式文档。

image members 实体是镜像成员实体的容器。

以下模式仅为示例。请仅将 API 调用的响应视为权威。

正常响应代码：200

错误响应代码：400, 401

请求

此操作没有请求参数，也不接受请求体。

响应示例

{
    "links": [
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "members",
    "properties": {
        "members": {
            "items": {
                "name": "member",
                "properties": {
                    "created_at": {
                        "description": "Date and time of image member creation",
                        "type": "string"
                    },
                    "image_id": {
                        "description": "An identifier for the image",
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": "string"
                    },
                    "member_id": {
                        "description": "An identifier for the image member (tenantId)",
                        "type": "string"
                    },
                    "schema": {
                        "readOnly": true,
                        "type": "string"
                    },
                    "status": {
                        "description": "The status of this image member",
                        "enum": [
                            "pending",
                            "accepted",
                            "rejected"
                        ],
                        "type": "string"
                    },
                    "updated_at": {
                        "description": "Date and time of last modification of image member",
                        "type": "string"
                    }
                }
            },
            "type": "array"
        },
        "schema": {
            "type": "string"
        }
    }
}

GET

/v2/schemas/member

显示镜像成员模式

详情

(自 Images v2.1 起)

显示表示 image member 实体的 JSON 模式文档。

以下模式仅为示例。请仅将 API 调用的响应视为权威。

正常响应代码：200

错误响应代码：400, 401

请求

此操作没有请求参数，也不接受请求体。

响应示例

{
    "name": "member",
    "properties": {
        "created_at": {
            "description": "Date and time of image member creation",
            "type": "string"
        },
        "image_id": {
            "description": "An identifier for the image",
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": "string"
        },
        "member_id": {
            "description": "An identifier for the image member (tenantId)",
            "type": "string"
        },
        "schema": {
            "readOnly": true,
            "type": "string"
        },
        "status": {
            "description": "The status of this image member",
            "enum": [
                "pending",
                "accepted",
                "rejected"
            ],
            "type": "string"
        },
        "updated_at": {
            "description": "Date and time of last modification of image member",
            "type": "string"
        }
    }
}

镜像数据

上传和下载原始镜像数据。

这些操作可能仅限于管理员。请参阅您的云操作员的文档以获取详细信息。

PUT

/v2/images/{image_id}/file

上传二进制镜像数据

详情

上传二进制镜像数据。(自 Image API v2.0 起)

将 Content-Type 请求标头设置为 application/octet-stream。

在 Rocky 版本中引入了多存储后端作为 EXPERIMENTAL Image API v2.8 的一部分。

从 API 版本 2.8 开始，可以将可选的 X-Image-Meta-Store 标头添加到请求中。如果存在，镜像数据将被放置到标识符为该标头值的后端存储中。如果指定的存储标识符不被识别，则返回 400（错误请求）响应。如果未提供标头，则镜像数据将被放置在默认后端存储中。

可以向请求添加可选的 x-openstack-image-size 标头。如果存在，服务器将验证上传的数据大小是否与此值匹配。如果实际大小与预期大小不匹配，则返回 400（错误请求）响应。如果未提供，服务器将根据实际请求体大小计算镜像大小。

• 存储标识符是特定于站点的。使用 存储发现 调用来确定特定云中可用的存储。

• 默认存储可以从 存储发现 响应中确定。

• 始终定义默认存储，因此如果您不需要使用特定的存储，只需省略此标头，即可使用默认存储。

• 对于 API 版本早于版本 2.8，此标头将被静默忽略。

示例调用

curl -i -X PUT -H "X-Auth-Token: $token" \
   -H "X-Image-Meta-Store: {store_identifier}" \
   -H "Content-Type: application/octet-stream" \
   -H "x-openstack-image-size: 5368709120" \
   -d @/home/glance/ubuntu-12.10.qcow2 \
   $image_url/v2/images/{image_id}/file

先决条件

在存储二进制镜像数据之前，您必须满足以下先决条件

• 镜像必须存在。

• 您必须在镜像中设置磁盘和容器格式。

• 镜像状态必须为 queued。

• 您的镜像存储配额必须足够。

• 您想要存储的数据大小不得超过 OpenStack Image 服务允许的大小。

同步后置条件

• 在具有正确权限的情况下，您可以通过 API 调用将镜像状态看到为 active。

• 在具有正确访问权限的情况下，您可以在 OpenStack Image 服务管理的存储系统中看到存储的数据。

故障排除

• 如果您无法存储数据，则您的请求缺少必要的信息，或者您超出了分配的配额。请确保您满足先决条件并再次运行请求。如果请求再次失败，请检查您的 API 请求。

• 用于存储数据的存储后端必须有足够的可用存储空间来容纳数据的大小。

正常响应代码：204

错误响应代码：400、401、403、404、409、410、413、415、503

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的媒体类型描述符。使用 application/octet-stream
X-Image-Meta-Store (可选)	标头	字符串	用于上传或导入镜像数据的存储标识符。仅当向支持多个后端存储的云发出请求时才应包含此项。使用 存储发现 调用来确定合适的存储标识符。只需省略此标头即可使用默认存储。(自 Image API v2.8 起)
x-openstack-image-size (可选)	标头	字符串	以字节为单位的预期镜像数据大小。如果存在，服务器将验证上传的数据大小是否与此值匹配。如果实际大小与预期大小不匹配，则返回 400（错误请求）响应。如果未提供，服务器将根据实际请求体大小计算镜像大小。
image_id	路径	字符串	镜像的 UUID。

GET

/v2/images/{image_id}/file

下载二进制镜像数据

详情

下载二进制镜像数据。(自 Image API v2.0 起)

示例调用：curl -i -X GET -H "X-Auth-Token: $token" $image_url/v2/images/{image_id}/file

响应体包含表示实际虚拟磁盘的原始二进制数据。Content-Type 标头包含 application/octet-stream 值。Content-MD5 标头包含镜像数据的 MD5 校验和。使用此校验和来验证镜像数据的完整性。

先决条件

• 镜像必须存在。

同步后置条件

• 如果镜像具有镜像数据，您可以将二进制镜像数据下载到您的机器上。

• 如果存在镜像数据，该调用将返回 HTTP 200 响应代码，用于完全镜像下载请求。

• 如果存在镜像数据，该调用将返回 HTTP 206 响应代码，用于部分下载请求。

• 如果不存在镜像数据，该调用将返回 HTTP 204（无内容）响应代码。

• 如果不存在镜像记录，该调用将返回 HTTP 404 响应代码，用于尝试完全镜像下载请求。

• 对于无法满足的部分下载请求，该调用将返回 HTTP 416 响应代码。

正常响应代码：200、204、206

错误响应代码：400、403、404、416

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。
Range (可选)	标头	字符串	请求的镜像数据范围。请注意，不支持多范围请求。有关详细信息，请参阅 超文本传输协议 (HTTP/1.1)：范围请求。

响应

名称	入参	类型	描述
Content-Type	标头	字符串	响应体的媒体类型描述符，即 application/octet-stream
Content-Md5	标头	字符串	主体的 MD5 校验和。
Content-Length	标头	字符串	主体的大小（以八位字节为单位）
Content-Range (可选)	标头	字符串	镜像数据的内容范围。有关详细信息，请参阅 超文本传输协议 (HTTP/1.1)：范围请求。

可互操作的镜像导入

可互操作的镜像导入过程在 Image API v2.6 中引入。

使用 API 版本 调用来确定您的云中可用的 API 版本。

常规信息

您用于可互操作镜像导入的确切工作流程取决于您想要导入镜像的云中可用的导入方法。这些方法定义明确（这使得此过程在不同的 OpenStack 云之间可互操作）。

定义了四种导入方法

• glance-direct

• web-download

• copy-image

• glance-download

注意

使用 导入方法发现 调用来确定您想要导入镜像的云中可用的导入方法。

每种可互操作镜像导入方法的第一个步骤相同：您必须创建一个镜像记录。这将为您提供一个镜像 ID 以供使用。此镜像 ID 是 OpenStack Image 服务将理解您发出的其他调用是指特定镜像的方式。

因此，第一步是

1. 使用 创建镜像 API 调用创建镜像记录。您必须首先执行此操作，以便为其他调用提供一个镜像 ID。

   在启用可互操作镜像导入的云中，创建镜像 响应将包含一个 OpenStack-image-import-methods 标头，其中列出了该云中可用的导入方法类型。或者，这些方法可以独立于创建镜像通过发出 导入方法发现 调用来确定。

   在云中可用多个存储后端的情况下，创建镜像 响应将包含一个 OpenStack-image-store-ids 标头，其中列出了该云中可用的存储。或者，这些存储可以独立于创建镜像通过发出 存储发现 调用来确定。

glance-direct 导入方法

glance-direct 工作流程具有 三个 部分

1. 如上所述创建镜像记录。

2. 使用 镜像暂存 API 调用将镜像数据上传到暂存区域。请注意，在第三步成功完成之前，此镜像数据不可访问。

3. 发出 镜像导入 调用以完成导入过程。您将在导入调用的主体中指定您正在使用 glance-direct 导入方法。

web-download 导入方法

web-download 工作流程具有 两个 部分

1. 如上所述创建镜像记录。

2. 发出 镜像导入 调用以完成导入过程。您将在导入调用的主体中指定您正在使用 web-download 导入方法。

copy-image 导入方法

“copy-image”工作流包含两个部分

1. 识别要将数据复制到其他存储的现有镜像。

2. 发出镜像导入调用以完成导入过程。您将在导入调用的主体中指定您使用的是copy-image导入方法。

glance-download 导入方法

“glance-download”工作流包含两个部分

1. 如上所述创建镜像记录。

2. 发出镜像导入调用以完成导入过程。您将在导入调用的主体中指定您使用的是glance-download导入方法。

PUT

/v2/images/{image_id}/stage

暂存二进制镜像数据

详情

将二进制镜像数据放置在暂存区域。它未存储在存储后端中，在发出镜像导入调用之前无法下载。(自 Image API v2.6 起)

将 Content-Type 请求标头设置为 application/octet-stream。

可以向请求添加可选的 x-openstack-image-size 标头。如果存在，服务器将验证上传的数据大小是否与此值匹配。如果实际大小与预期大小不匹配，则返回 400（错误请求）响应。如果未提供，服务器将根据实际请求体大小计算镜像大小。

示例调用

curl -i -X PUT -H "X-Auth-Token: $token" \
   -H "Content-Type: application/octet-stream" \
   -H "x-openstack-image-size: 5368709120" \
   -d @/home/glance/my.to-import.qcow2 \
   $image_url/v2/images/{image_id}/stage

先决条件

在暂存二进制镜像数据之前，您必须满足以下先决条件

• 镜像记录必须存在。

• 镜像状态必须为 queued。

• 您的镜像存储配额必须足够。

• 您想要存储的数据大小不得超过 OpenStack Image 服务允许的大小。

同步后置条件

• 在具有正确权限的情况下，您可以通过 API 调用查看镜像状态为uploading。

故障排除

• 如果您无法存储数据，则您的请求缺少必要的信息，或者您超出了分配的配额。请确保您满足先决条件并再次运行请求。如果请求再次失败，请检查您的 API 请求。

• 用于存储数据的存储后端必须有足够的可用存储空间来容纳数据的大小。

正常响应代码：204

错误响应代码：400、401、403、404、405、409、410、413、415、503

如果您的云中未启用镜像导入过程，则此请求将导致带有相应消息的 404 响应代码。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的媒体类型描述符。使用 application/octet-stream
x-openstack-image-size (可选)	标头	字符串	以字节为单位的预期镜像数据大小。如果存在，服务器将验证上传的数据大小是否与此值匹配。如果实际大小与预期大小不匹配，则返回 400（错误请求）响应。如果未提供，服务器将根据实际请求体大小计算镜像大小。
image_id	路径	字符串	镜像的 UUID。

POST

/v2/images/{image_id}/import

导入镜像

详情

通过处理已提供给 OpenStack 镜像服务的镜像数据，向镜像服务发出信号以完成镜像导入工作流。(自 Image API v2.6 起)

在glance-direct工作流中，通过暂存二进制镜像数据API 调用将数据提供给镜像服务。

在web-download工作流中，数据通过发布到具有您知道的 URL 的可访问位置提供给镜像服务。

在copy-image工作流中，数据通过将现有镜像数据复制到暂存区域提供给镜像服务。

在glance-download工作流中，数据通过从您知道的区域名称和镜像 ID 指定的另一个 glance 服务中获取镜像提供给镜像服务。

从 API 版本 2.8 开始，可以将可选的stores参数添加到请求主体中。如果存在，它包含要将镜像二进制数据导入到的后端存储标识符列表。如果指定了至少一个未识别的存储标识符，则返回 409（冲突）响应。如果未提供该参数，则将镜像数据放置在默认后端存储中。

• 存储标识符是特定于站点的。使用 存储发现 调用来确定特定云中可用的存储。

• 默认存储可以从 存储发现 响应中确定。

• 始终定义一个默认存储，因此如果您不需要使用特定的存储，只需省略此参数，系统将使用默认存储。

• 对于 API 版本早于 2.8，此参数将被静默忽略。

为了向后兼容，如果未指定stores参数，则将评估标头“X-Image-Meta-Store”。

要将数据导入到您可以从 Glance 的此特定部署中使用的整个存储集，您可以使用可选的布尔主体参数all_stores。请注意，不能同时使用此参数和stores参数。

要设置在发生错误时导入工作流的行为，您可以使用可选的布尔主体参数all_stores_must_succeed。设置为 True（默认值）时，如果在至少一个存储中发生错误，工作流将失败，数据将被从已完成复制的存储中删除，并且镜像的状态保持不变。设置为 False 时，只有当所有指定的存储中的上传都失败时，工作流才会失败。在部分成功的情况下，添加到镜像的存储位置将是已正确上传数据的位置。

JSON 请求主体指定您希望在此镜像请求中使用哪种导入方法。

先决条件

在完成可互操作的镜像导入工作流之前，您必须满足以下先决条件

• 镜像记录必须存在。

• 您必须在镜像记录中设置磁盘和容器格式。（这可以在创建镜像时完成，或者您可以发出镜像更新API 调用。）

• 您的镜像存储配额必须足够。

• 您想要存储的数据大小不得超过 OpenStack Image 服务允许的大小。

附加先决条件

如果您使用的是glance-direct导入方法

• 镜像状态必须为uploading。（这表示已将镜像数据上传到暂存区。）

• 您的请求主体必须指示您正在使用glance-direct导入方法。

如果您使用的是web-download导入方法

• 镜像状态必须为queued。（这表示尚未将任何镜像数据与镜像关联。）

• 您的请求主体必须指示您正在使用web-download导入方法，并且必须包含要找到数据的 URL。

  注意

  特定云中可能会限制web-download导入方法的可接受 URL 集合。有关详细信息，请参阅云的本地文档。

如果您使用的是copy-image导入方法

• 镜像状态必须为active。（这表示镜像数据与镜像关联。）

• 您的请求主体必须指示您正在使用copy-image导入方法，并且必须包含您想要复制镜像的存储列表或 all_stores，这将把镜像复制到 glance_api.conf 中使用enabled_backends配置选项设置的所有可用存储中。

• 如果您的请求主体包含all_stores_must_succeed（默认值为 True），并且在至少一个存储中发生错误，则请求将被拒绝，数据将被从新存储中删除（非暂存），并且镜像的状态保持不变。

• 如果您的请求主体包含将all_stores_must_succeed设置为 False，并且发生错误，则请求将失败（数据从存储中删除，…），仅当用户指定的所有存储中的复制都失败时。在部分成功的情况下，添加到镜像的存储位置将是已正确上传数据的位置。

• 默认情况下，您只能对您拥有的镜像执行 copy-image 操作。此操作受策略控制，因此某些用户可能会被授予复制非拥有镜像的权限。有关详细信息，请参阅您的云的本地文档。

如果您使用的是glance-download导入方法

• 镜像状态必须为queued。（这表示尚未将任何镜像数据与镜像关联。）

• 您的请求主体必须指示您正在使用glance-download导入方法，并且必须包含远程 OpenStack 区域的区域名称和要获取的镜像 ID。您可以选择性地请求设置服务接口名称（默认值为 public）。

同步后置条件

• 在具有正确权限的情况下，您可以通过 API 调用查看镜像状态为importing（仅适用于 glance-direct、web-download 和 glance-download 导入方法）。（请注意，但是，如果导入过程在您发出 API 调用之前完成，则镜像可能已经显示为active。）

正常响应代码：202

错误响应代码：400、401、403、404、405、409、410、413、415、503

如果您的云中未启用镜像导入过程，则此请求将导致带有相应消息的 404 响应代码。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求主体的媒体类型描述符。使用application/json。
X-Image-Meta-Store (可选)	标头	字符串	用于上传或导入镜像数据的存储标识符。仅当向支持多个后端存储的云发出请求时才应包含此项。使用 存储发现 调用来确定合适的存储标识符。只需省略此标头即可使用默认存储。(自 Image API v2.8 起)
image_id	路径	字符串	镜像的 UUID。
method	body	对象	JSON 对象指示您希望使用哪种导入方法来导入镜像。此 JSON 对象的内容是另一个 JSON 对象，其中包含一个name字段，其值为导入方法的标识符。
all_stores（可选）	body	布尔值	设置为 True 时，数据将被导入到您可以从 Glance 的此特定部署中使用的存储集（即：击中 glance-api 的请求返回的相同存储集）。不能同时使用此参数和stores参数。
all_stores_must_succeed（可选）	body	布尔值	一个布尔参数，指示在发生错误时导入工作流的行为。设置为 True（默认值）时，如果在至少一个存储中发生错误，工作流将失败，数据将被从已完成复制的存储中删除，并且镜像的状态保持不变。设置为 False 时，只有当用户指定的指定的所有存储中的导入都失败时，工作流才会失败。在部分成功的情况下，添加到镜像的存储位置将是已正确上传数据的位置。默认值为 True。
stores（可选）	body	数组	如果存在，则包含要将镜像二进制数据导入到的存储 ID 列表。

请求示例 - glance-direct 导入方法

{
    "method": {
        "name": "glance-direct"
    },
    "stores": ["common", "cheap", "fast", "reliable"],
    "all_stores_must_succeed": false
}

请求示例 - web-download 导入方法

{
    "method": {
        "name": "web-download",
        "uri": "https://download.cirros-cloud.net/0.4.0/cirros-0.4.0-ppc64le-disk.img"
    },
    "all_stores": true,
    "all_stores_must_succeed": true
}

请求示例 - copy-image 导入方法

{
    "method": {
        "name": "copy-image"
    },
    "stores": ["common", "cheap", "fast", "reliable"],
    "all_stores_must_succeed": false,
    "all_stores": false
}

请求示例 - glance-download 导入方法

{
  "method": {
    "name": "glance-download",
    "glance_image_id": "c4705b36-b281-40f6-a01d-bf98883ead8e",
    "glance_region": "REGION2",
    "glance_service_interface": "public"
  }
}

存储

多存储后端支持将镜像的副本存储在多个位置。

DELETE

/v2/stores/{store_id}/{image_id}

从存储中删除镜像

详情

此 API 允许您从特定存储中删除镜像的副本。(自 Image API v2.10 起)

注意

• 此 API 不允许删除镜像的最后一个位置。

正常响应代码：204

错误响应代码：400、401、403、404、409

请求

名称	入参	类型	描述
store_id	路径	字符串	要从中删除镜像的存储的 ID。
image_id	路径	字符串	镜像的 UUID。

镜像服务信息（发现）

常规信息

这些调用允许您发现有关您可以从 OpenStack 镜像服务的特定部署中使用的服务的有用信息。

GET

/v2/info/import

导入方法和值发现

详情

返回有关云中镜像导入限制的信息，例如支持的容器格式、支持的磁盘格式、最大镜像大小等。此调用包含一个import-methods字段，该字段由一个字符串标识符数组组成，指示在调用所做的云中支持哪些导入方法。(自 Image API v2.6 起)

注意

在 Image API v2.6-2.8 中，此发现调用仅包含import-methods字段。

正常响应代码：200

错误响应代码：400、401、403

请求

没有请求参数。

此调用不允许请求体。

响应参数

名称	入参	类型	描述
import-methods	body	对象	一个 JSON 对象，包含一个value元素，该元素是一个字符串标识符数组，指示在调用所做的云中可用的导入方法。此列表可能为空。

响应示例

{
    "import-methods": {
        "description": "Import methods available.",
        "type": "array",
        "value": [
            "glance-direct",
            "web-download"
        ]
    }
}

GET

/v2/info/stores

列出存储

详情

在 Rocky 版本中引入了多存储后端作为 EXPERIMENTAL Image API v2.8 的一部分。

在 API 的 2.7 版本中，此调用将返回 404（未找到）。使用API 版本调用来确定您的云中可用的 API 版本。

正常响应代码：200

错误响应代码：404

请求

没有请求参数。

此调用不允许请求体。

响应参数

名称	入参	类型	描述
stores	body	数组	一个存储对象列表，其中每个存储对象可能包含以下字段 id 操作员定义的存储标识符。 description 操作员提供的此存储的描述。 default（可选） 仅存在于默认存储中。如果您在向镜像服务提供数据时未指定特定的存储，则这是放置镜像数据的位置。（有关更多信息，请参阅镜像数据和可互操作的镜像导入部分。） read-only（可选） 仅在存储为只读时包含。

响应示例

{
    "stores": [
        {
            "id":"reliable",
            "description": "More expensive store with data redundancy"
        },
        {
            "id":"fast",
            "description": "Provides quick access to your image data",
            "default": true
        },
        {
            "id":"cheap",
            "description": "Less expensive store for seldom-used images"
        },
        {
            "id":"special",
            "description": "Need a plausible description here that doesn't expose the store type",
            "read-only": true
        }
    ]
}

GET

/v2/info/usage

配额使用情况

详情

如果服务器端配置启用，将显示用户的配额和当前使用情况。

正常响应代码：200

请求

没有请求参数。

此调用不允许请求体。

响应示例

{
    "usage": {
        "image_size_total": {
            "limit": 1024,
            "usage": 256
        },
        "image_count_total": {
            "limit": 10,
            "usage": 2
        },
        "image_stage_total": {
            "limit": 512,
            "usage": 0
        },
        "image_count_uploading": {
            "limit": 2,
            "usage": 0
        }
    }
}

GET

/v2/info/stores/detail

列出存储详细信息

详情

列出管理员可访问的所有后端存储，对于非管理员用户 API 将返回错误请求。

正常响应代码：200

错误响应代码：403、404

请求

没有请求参数。

此调用不允许请求体。

响应参数

名称	入参	类型	描述
stores	body	数组	一个存储对象列表，其中每个存储对象可能包含以下字段 id 操作员定义的存储标识符。 type 指定存储的类型。 description 操作员提供的此存储的描述。 default（可选） 仅存在于默认存储中。如果您在向镜像服务提供数据时未指定特定的存储，则这是放置镜像数据的位置。（有关更多信息，请参阅镜像数据和可互操作的镜像导入部分。） read-only（可选） 仅在存储为只读时包含。 weight（默认值为 0） 包含权重（正整数）以对镜像位置进行偏好排序。 properties 包含存储特定属性

响应示例

{
    "stores": [
        {
            "id":"reliable",
            "type": "rbd",
            "description": "More expensive store with data redundancy",
            "default": true,
            "weight": 100,
            "properties": {
                "pool": "pool1",
                "chunk_size": 65536,
                "thin_provisioning": false,
                "fsid": "ddf1b25f-1907-449e-89f6-cd30a679c8dc",
            }
        },
        {
            "id":"cheap",
            "type": "file",
            "description": "Less expensive store for seldom-used images",
            "weight": 200,
            "properties": {
                "datadir": "fdir",
                "chunk_size": 65536,
                "thin_provisioning": false
            }
        },
        {
            "id":"fast",
            "type": "cinder",
            "description": "Reasonably-priced fast store",
            "weight": 300,
            "properties": {
                "volume_type": "volume1",
                "use_multipath": false
            }
        },
        {
            "id":"slow",
            "type": "swift",
            "description": "Entry-level store balancing price and speed",
            "weight": 400,
            "properties": {
                "container": "container1",
                "large_object_size": 52428,
                "large_object_chunk_size": 204800
            }
        }


    ]
}

任务

创建、列出和显示任务的详细信息。

(自 API v2.2 起)

常规信息

API 状态

此 API 在 OpenStack Mitaka 版本中默认设置为仅限管理员。因此，以下调用可能无法在您的云中提供给最终用户。请参阅您的云提供商的文档以获取更多信息。

概念概述

请参阅 Glance 开发人员文档的任务部分，以了解任务的概念概述。

任务状态

任务的可能状态值显示在下表中。

状态	描述
待定	任务正在等待执行。
processing	任务的执行正在进行中。
success	任务已成功完成。应填充result元素。
failure	任务未能完成。应将非空字符串填充到message元素中。

POST

/v2/tasks

创建任务

详情

创建一项任务。

正常响应代码：201

错误响应代码：401, 413, 415

请求

名称	入参	类型	描述
type	body	字符串	此内容所代表的任务类型。
输入	body	对象	一个 JSON 对象，指定任务的输入参数。请参阅您的云服务提供商的文档以获取详细信息。

请求示例

{
    "type": "import",
    "input": {
        "import_from": "http://app-catalog.openstack.example.org/groovy-image",
        "import_from_format": "qcow2",
        "image_properties": {
            "disk_format": "vhd",
            "container_format": "ovf"
        }
    }
}

响应参数

名称	入参	类型	描述
created_at	body	字符串	任务创建的日期和时间。 日期和时间戳格式为 ISO 8601。
id	body	字符串	任务的 UUID。
输入	body	对象	一个 JSON 对象，指定任务的输入参数。请参阅您的云服务提供商的文档以获取详细信息。
message	body	字符串	人类可读的文本，可能为空字符串，通常在错误情况下显示，以提供有关发生情况的更多信息。
owner	body	字符串	任务所有者的标识符，通常是租户 ID。
result	body	对象	一个 JSON 对象，指定有关任务最终结果的信息。请参阅您的云服务提供商的文档以获取详细信息。
schema	body	字符串	描述图像任务的模式的 URI。
self	body	字符串	此任务的 URI。
status	body	字符串	此任务的当前状态。该值可以是 pending、processing、success 或 failure。
type	body	字符串	此内容所代表的任务类型。
updated_at	body	字符串	任务更新的日期和时间。 日期和时间戳格式为 ISO 8601。 如果未设置 updated_at 日期和时间戳，则其值为 null。

响应示例

{
    "created_at": "2016-06-24T14:57:19Z",
    "id": "bb480de2-7077-4ea9-bbe9-be1891290d3e",
    "input": {
        "image_properties": {
            "container_format": "ovf",
            "disk_format": "vhd"
        },
        "import_from": "http://app-catalog.openstack.example.org/groovy-image",
        "import_from_format": "qcow2"
    },
    "message": "",
    "owner": "fa6c8c1600f4444281658a23ee6da8e8",
    "result": null,
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/bb480de2-7077-4ea9-bbe9-be1891290d3e",
    "status": "pending",
    "type": "import",
    "updated_at": "2016-06-24T14:57:19Z"
}

GET

/v2/tasks

列出任务

详情

列出任务。

正常响应代码：200

错误响应代码：403, 404, 413

请求

名称	入参	类型	描述
limit (可选)	查询	整数	请求项目页面大小。返回最多限制值数量的项目。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 limit 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 marker 参数值。
sort_dir (可选)	查询	字符串	按一组一个或多个排序方向和属性（sort_key）组合对响应进行排序。排序方向的有效值为 asc（升序）或 desc（降序）。如果您在集合中省略排序方向，则默认值为 desc。
sort_key (可选)	查询	字符串	按以下属性之一对响应进行排序：created_at、expires_at、status、type、updated_at。默认值为 created_at。
status (可选)	查询	字符串	按任务状态过滤响应。有效值为 pending、processing、success 或 failure。
type (可选)	查询	字符串	按任务类型过滤响应。有效值为 import。

响应参数

名称	入参	类型	描述
first	body	字符串	响应第一页的 URI。
下一个	body	字符串	响应下一页的 URI。不会出现在响应的最后一页上。
schema	body	字符串	描述图像任务列表的模式的 URI。
tasks	body	数组	一个稀疏的任务对象列表。每个对象包含以下字段 created_at id owner schema self status type updated_at

响应示例

{
    "first": "/v2/tasks",
    "schema": "/v2/schemas/tasks",
    "tasks": [
        {
            "created_at": "2016-06-24T14:44:19Z",
            "id": "08b7e1c8-3821-4f54-b3b8-d6655d178cdf",
            "owner": "fa6c8c1600f4444281658a23ee6da8e8",
            "schema": "/v2/schemas/task",
            "self": "/v2/tasks/08b7e1c8-3821-4f54-b3b8-d6655d178cdf",
            "status": "processing",
            "type": "import",
            "updated_at": "2016-06-24T14:44:19Z"
        },
        {
            "created_at": "2016-06-24T14:40:19Z",
            "id": "231c311d-3557-4e23-afc4-6d98af1419e7",
            "owner": "fa6c8c1600f4444281658a23ee6da8e8",
            "schema": "/v2/schemas/task",
            "self": "/v2/tasks/231c311d-3557-4e23-afc4-6d98af1419e7",
            "status": "processing",
            "type": "import",
            "updated_at": "2016-06-24T14:40:20Z"
        }
    ]
}

GET

/v2/tasks/{task_id}

显示任务详情

详情

显示任务的详细信息。

正常响应代码：200

错误响应代码：404

请求

名称	入参	类型	描述
task_id	路径	字符串	任务的标识符，一个 UUID。

响应参数

名称	入参	类型	描述
created_at	body	字符串	任务创建的日期和时间。 日期和时间戳格式为 ISO 8601。
expires_at	body	字符串	任务被删除的日期和时间。虽然任务对象，即描述任务的记录会受到删除，但任务的结果（例如，导入的图像）仍然存在。 日期和时间戳格式为 ISO 8601。 仅当任务达到 success 或 failure 状态时，才会设置此值。否则其值为 null。当其值为 null 时，它可能不会出现在响应中。
id	body	字符串	任务的 UUID。
输入	body	对象	一个 JSON 对象，指定任务的输入参数。请参阅您的云服务提供商的文档以获取详细信息。
message	body	字符串	人类可读的文本，可能为空字符串，通常在错误情况下显示，以提供有关发生情况的更多信息。
owner	body	字符串	任务所有者的标识符，通常是租户 ID。
result	body	对象	一个 JSON 对象，指定有关任务最终结果的信息。请参阅您的云服务提供商的文档以获取详细信息。
schema	body	字符串	描述图像任务的模式的 URI。
self	body	字符串	此任务的 URI。
status	body	字符串	此任务的当前状态。该值可以是 pending、processing、success 或 failure。
type	body	字符串	此内容所代表的任务类型。
updated_at	body	字符串	任务更新的日期和时间。 日期和时间戳格式为 ISO 8601。 如果未设置 updated_at 日期和时间戳，则其值为 null。

响应示例（任务状态：processing）

{
    "created_at": "2016-06-24T14:40:19Z",
    "id": "231c311d-3557-4e23-afc4-6d98af1419e7",
    "input": {
        "image_properties": {
            "container_format": "ovf",
            "disk_format": "vhd"
        },
        "import_from": "http://example.com",
        "import_from_format": "qcow2"
    },
    "message": "",
    "owner": "fa6c8c1600f4444281658a23ee6da8e8",
    "result": null,
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/231c311d-3557-4e23-afc4-6d98af1419e7",
    "status": "processing",
    "type": "import",
    "updated_at": "2016-06-24T14:40:20Z"
}

响应示例（任务状态：success）

{
    "created_at": "2016-06-29T16:13:07Z",
    "expires_at": "2016-07-01T16:13:07Z",
    "id": "805f47d2-8814-4cd7-bef3-37037389a998",
    "input": {
        "image_properties": {
            "container_format": "ovf",
            "disk_format": "vhd"
        },
        "import_from": "https://apps.openstack.org/excellent-image",
        "import_from_format": "qcow2"
    },
    "message": "",
    "owner": "02a7fb2dd4ef434c8a628c511dcbbeb6",
    "result": {
        "image_id": "2b61ed2b-f800-4da0-99ff-396b742b8646"
    },
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/805f47d2-8814-4cd7-bef3-37037389a998",
    "status": "success",
    "type": "import",
    "updated_at": "2016-06-29T16:13:07Z"
}

响应示例（任务状态：failure）

{
    "created_at": "2016-06-24T14:57:20Z",
    "expires_at": "2016-06-26T14:57:20Z",
    "id": "bb480de2-7077-4ea9-bbe9-be1891290d3e",
    "input": {
        "image_properties": {
            "container_format": "ovf",
            "disk_format": "vhd"
        },
        "import_from": "http://app-catalog.openstack.example.org/groovy-image",
        "import_from_format": "qcow2"
    },
    "message": "Task failed due to Internal Error",
    "owner": "fa6c8c1600f4444281658a23ee6da8e8",
    "result": null,
    "schema": "/v2/schemas/task",
    "self": "/v2/tasks/bb480de2-7077-4ea9-bbe9-be1891290d3e",
    "status": "failure",
    "type": "import",
    "updated_at": "2016-06-24T14:57:20Z"
}

任务模式

获取一个 JSON-schema 文档，该文档表示单个任务和任务列表。

GET

/v2/schemas/tasks

显示任务模式

详情

(自 Images v2.2 起)

显示一个 JSON schema 文档，该文档表示任务列表。

任务列表实体是包含有关单个任务的简短信息的实体容器。

以下模式仅为示例。请仅将 API 调用的响应视为权威。

正常响应代码：200

错误响应代码：401

请求

此操作没有请求参数，也不接受请求体。

响应示例

{
    "links": [
        {
            "href": "{schema}",
            "rel": "describedby"
        }
    ],
    "name": "tasks",
    "properties": {
        "schema": {
            "type": "string"
        },
        "tasks": {
            "items": {
                "name": "task",
                "properties": {
                    "created_at": {
                        "description": "Datetime when this resource was created",
                        "type": "string"
                    },
                    "expires_at": {
                        "description": "Datetime when this resource would be subject to removal",
                        "type": [
                            "null",
                            "string"
                        ]
                    },
                    "id": {
                        "description": "An identifier for the task",
                        "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
                        "type": "string"
                    },
                    "owner": {
                        "description": "An identifier for the owner of this task",
                        "type": "string"
                    },
                    "schema": {
                        "readOnly": true,
                        "type": "string"
                    },
                    "self": {
                        "readOnly": true,
                        "type": "string"
                    },
                    "status": {
                        "description": "The current status of this task",
                        "enum": [
                            "pending",
                            "processing",
                            "success",
                            "failure"
                        ],
                        "type": "string"
                    },
                    "type": {
                        "description": "The type of task represented by this content",
                        "enum": [
                            "import"
                        ],
                        "type": "string"
                    },
                    "updated_at": {
                        "description": "Datetime when this resource was updated",
                        "type": "string"
                    }
                }
            },
            "type": "array"
        }
    }
}

GET

/v2/schemas/task

显示任务模式

详情

(自 Images v2.2 起)

显示一个 JSON schema 文档，该文档表示一个任务实体。

以下模式仅为示例。请仅将 API 调用的响应视为权威。

正常响应代码：200

错误响应代码：401

请求

此操作没有请求参数，也不接受请求体。

响应示例

{
    "name": "task",
    "properties": {
        "created_at": {
            "description": "Datetime when this resource was created",
            "type": "string"
        },
        "expires_at": {
            "description": "Datetime when this resource would be subject to removal",
            "type": [
                "null",
                "string"
            ]
        },
        "id": {
            "description": "An identifier for the task",
            "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
            "type": "string"
        },
        "input": {
            "description": "The parameters required by task, JSON blob",
            "type": [
                "null",
                "object"
            ]
        },
        "message": {
            "description": "Human-readable informative message only included when appropriate (usually on failure)",
            "type": "string"
        },
        "owner": {
            "description": "An identifier for the owner of this task",
            "type": "string"
        },
        "result": {
            "description": "The result of current task, JSON blob",
            "type": [
                "null",
                "object"
            ]
        },
        "schema": {
            "readOnly": true,
            "type": "string"
        },
        "self": {
            "readOnly": true,
            "type": "string"
        },
        "status": {
            "description": "The current status of this task",
            "enum": [
                "pending",
                "processing",
                "success",
                "failure"
            ],
            "type": "string"
        },
        "type": {
            "description": "The type of task represented by this content",
            "enum": [
                "import"
            ],
            "type": "string"
        },
        "updated_at": {
            "description": "Datetime when this resource was updated",
            "type": "string"
        }
    }
}

缓存管理

列出和管理缓存。

GET

/v2/cache

查询缓存状态

详情

列出缓存或队列中的所有图像。(自 Image API v2.14 起)

正常响应代码：200

错误响应代码：400、401、403

请求

没有请求参数。

响应参数

名称	入参	类型	描述
cached_images	body	数组	一个缓存图像 JSON 对象列表，可能为空，其中每个对象包含以下字段 image_id 缓存图像的 ID hits 此图像的缓存命中次数。 last_accessed 最近访问缓存图像的时间戳。 last_modified 将缓存图像安装到缓存的时间戳。 size 缓存图像的大小（以字节为单位）。
queued_images	body	数组	一个图像 ID 列表，可能为空，表示排队进行缓存的图像，按将要处理的顺序排列。

响应示例

{
    "cached_images": [
        {
            "image_id": "fe05d6c9-ef02-4161-9056-81ed046f3024",
            "hits": 0,
            "last_accessed": 1651504844.0860524,
            "last_modified": 1651504844.0860524,
            "size": 987654
        }
    ],
    "queued_images": [
        "e34e6e2f-fe16-420d-ad36-cebf69506106",
        "6b9fbf2b-3031-429a-80b1-b509e4c44046"
    ]
}

PUT

/v2/cache/{image_id}

排队图像

详情

将图像排队进行缓存。(自 Image API v2.14 起)

正常响应代码：202

错误响应代码：400、401、403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

DELETE

/v2/cache/{image_id}

从缓存中删除图像

详情

从缓存中删除图像。(自 Image API v2.14 起)

正常响应代码：204

错误响应代码：400、401、403、404

请求

名称	入参	类型	描述
image_id	路径	字符串	镜像的 UUID。

DELETE

/v2/cache

清除缓存中的图像

详情

清除缓存及其队列。(自 Image API v2.14 起)

正常响应代码：204

错误响应代码：400、401、403

请求

名称	入参	类型	描述
x-image-cache-clear-target (可选)	标头	字符串	一个关键字，指示 ‘cache’、‘queue’ 或空字符串，以指示删除 API 从缓存或队列中删除图像，或者从两者中删除。如果缺少此标头，则将删除缓存和排队的所有图像。