使用 Glance 的镜像公共 API¶

Glance 是 OpenStack Images API 的参考实现。因此，Glance 完全实现了 Images API 的版本 1 和 2。

注意

Images API v1 在 Newton 版本中已被弃用，并已移除。

过去曾有一句话说：“Images API 规范是与 Glance 一起开发的，但它不被认为是 Glance 项目的一部分。” 这只在某种程度上是正确的（或者完全是错误的，取决于你对这些事情的严格程度）。从概念上讲，OpenStack Images API 是一个 REST API 的独立定义。但在实践中，参与 Images API 演进的唯一方法是与 Glance 社区合作，定义新的功能并提供其参考实现。此外，Glance 属于 OpenStack Interop（以前称为 DefCore）指南中的“指定部分”条款，这意味着为了被定义为“OpenStack”，暴露 OpenStack Images API 的云必须包含 Glance Images API 实现代码。因此，尽管在概念上是独立的，但 OpenStack Images API 与 Glance 紧密相关。

参考文献

Glance 和 Images API：过去、现在和未来¶

以下是 Glance 已经实现过的 Images API 的快速总结。如果您对更多细节感兴趣，可以查阅所有 OpenStack 版本的发行说明（从“Bexar”开始），以跟踪 Glance 和 Images API 中功能的演进。

Images v1 API¶

v1 API 最初被设计为 Nova 和其他 OpenStack 服务使用的服务 API。在 Kilo 版本中，v1.1 API 从 CURRENT 降级为 SUPPORTED。在 Newton 版本中，版本 1 API 正式声明为 DEPRECATED。

在弃用期间，Images v1 API 不再接受进一步开发。Glance 代码实现 v1 API 仅接受重要的错误修复。

从 Folsom 开始，可以部署不向最终用户暴露 Images v1 API 的 OpenStack。Compute v2 API 包含与镜像相关的 API 调用，允许用户列出镜像、列出镜像详情、显示特定镜像的镜像详情、删除镜像以及操作镜像元数据。Nova 作为这些与镜像相关的调用的 Glance 代理。重要的是要注意，Compute v2 API 中的与镜像相关的调用是 Images API 中可用调用的适当子集。

在 Newton 版本中，Nova（以及其他消耗镜像的 OpenStack 服务）已修改为默认使用 Images v2 API。

参考

OpenStack 标准弃用要求

Images v2 API¶

v2 API 是当前的 OpenStack Images API。与 v1 API 相比，它为消费者提供了更友好的接口，因为它专门设计为将与镜像相关的功能作为面向公众的端点公开。它是当前开放开发的版本。

一种常见的策略是部署多个 Glance 节点：面向内部的节点为 Nova 等内部消费者提供 Images API，面向外部的节点为公共使用提供 Images v2 API。

未来¶

在成为名为“Glare”（Glance Artifacts Repository）的独立服务漫长而动荡的设计阶段期间，Glance 社区松散地谈论 Artifacts API 是“Glance v3”。然而，这只是对 Artifacts 工作的一种简写。Artifacts API 不能是 Images v3 API，因为 Artifacts 与 Images 不同。从概念上讲，虚拟机镜像可以是 Artifact，Glare 代码被设计为与 Images v2 API 兼容。但目前，没有计划实现 Images v3 API。

在 Newton 开发周期期间，Glare 成为一个独立的 OpenStack 项目。虽然很明显，OpenStack 需要一个 Artifact Repository，但它是否会像对 Images Repository 的需求一样普遍尚不清楚。另一方面，行业趋势可能会朝着相反的方向发展，每个人都需要 Artifacts，部署者将镜像视为另一种类型的数字 Artifact。正如一位经验丰富的经理 Yogi Berra 曾经说过：“预测很难，尤其是关于未来。”

身份验证¶

Glance 依赖 Keystone 和 OpenStack Identity API 来处理客户端身份验证。您必须从 Keystone 获取身份验证令牌，并通过 X-Auth-Token 标头将其发送给 Glance 的所有 API 请求。Glance 将与 Keystone 通信以验证令牌的有效性并获取您的身份凭据。

有关与 Keystone 集成的更多信息，请参阅使用 Keystone 进行身份验证。

使用 v1.X¶

注意

Images API v1 在 Newton 版本中已被弃用，并已移除。

为了方便示例，假设 Glance API 服务器正在 URL http://glance.openstack.example.org 上的默认端口 80 运行。

列出可用镜像¶

我们想要查看经过身份验证的用户可以访问的可用镜像列表。这包括用户拥有的镜像、与用户共享的镜像和公共镜像。

我们向 http://glance.openstack.example.org/v1/images 发送 GET 请求，以检索此可用镜像列表。数据以以下格式的 JSON 编码映射返回

{'images': [
  {'uri': 'http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
   'name': 'Ubuntu 10.04 Plain',
   'disk_format': 'vhd',
   'container_format': 'ovf',
   'size': '5368709120'}
  ...]}

以更多细节列出可用镜像¶

我们想要查看经过身份验证的用户可以访问的可用镜像的更详细列表。这包括用户拥有的镜像、与用户共享的镜像和公共镜像。

我们向 http://glance.openstack.example.org/v1/images/detail 发送 GET 请求，以检索此可用镜像列表。数据以以下格式的 JSON 编码映射返回

{'images': [
  {'uri': 'http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
   'name': 'Ubuntu 10.04 Plain 5GB',
   'disk_format': 'vhd',
   'container_format': 'ovf',
   'size': '5368709120',
   'checksum': 'c2e5db72bd7fd153f53ede5da5a06de3',
   'created_at': '2010-02-03 09:34:01',
   'updated_at': '2010-02-03 09:34:01',
   'deleted_at': '',
   'status': 'active',
   'is_public': true,
   'min_ram': 256,
   'min_disk': 5,
   'owner': null,
   'properties': {'distro': 'Ubuntu 10.04 LTS'}},
  ...]}

注意

所有时间戳均以 UTC 格式返回。

updated_at 时间戳是上次更新镜像元数据的时刻，而不是镜像数据，因为所有镜像数据在存储在 Glance 中后都是不可变的。

properties 字段是已与镜像元数据一起保存的自由格式键/值对的映射。

checksum 字段是镜像文件数据的 MD5 校验和。

is_public 字段是一个布尔值，指示镜像是否公开可用。

min_ram 字段是一个整数，指定在实例上运行此镜像所需的最小 RAM 大小，以兆字节为单位。

min_disk 字段是一个整数，指定在实例上运行此镜像所需的最小磁盘空间大小，以千兆字节为单位。

owner 字段是一个字符串，可以是 null，也可以指示镜像的所有者。

过滤镜像列表¶

GET /v1/images 和 GET /v1/images/detail 请求都接受查询参数，这些参数用于过滤返回的镜像列表。以下列表详细介绍了这些查询参数。

name=NAME

过滤 name 属性与 NAME 匹配的镜像。
container_format=FORMAT

过滤 container_format 属性与 FORMAT 匹配的镜像

有关更多信息，请参阅磁盘和容器格式
disk_format=FORMAT

过滤 disk_format 属性与 FORMAT 匹配的镜像

有关更多信息，请参阅磁盘和容器格式
status=STATUS

过滤 status 属性与 STATUS 匹配的镜像

有关更多信息，请参阅镜像状态
size_min=BYTES

过滤 size 属性大于或等于 BYTES 的镜像
size_max=BYTES

过滤 size 属性小于或等于 BYTES 的镜像

这两个资源还接受其他查询参数

sort_key=KEY

结果将按指定的镜像属性 KEY 排序。允许的值包括 id、name、status、disk_format、container_format、size、created_at（默认）和 updated_at。
sort_dir=DIR

结果将按方向 DIR 排序。允许的值是 asc（升序）或 desc（降序，默认）。
marker=ID

可以指定镜像标识符标记。如果存在，则仅列出发生在该标识符 ID 之后的镜像。（这些是 sort_dir 方向中晚于该标记 ID 的 sort_key 的镜像。）
limit=LIMIT

如果存在，则返回的结果的最大数量将不超过 LIMIT。

注意

如果指定的 LIMIT 超过操作程序定义的限制 (api_limit_max)，则返回的结果数量可能少于 LIMIT。

is_public=PUBLIC

管理员用户可以使用 is_public 参数来控制返回哪些结果。

当 is_public 参数不存在或设置为 True 时，将列出以下镜像：is_public 字段为 True 的镜像、拥有的镜像和共享的镜像。

当 is_public 参数设置为 False 时，将列出以下镜像：is_public 字段为 False 的镜像（拥有的、共享的或非拥有的）。

当 is_public 参数设置为 None 时，将列出所有镜像，无论所有者、共享状态或 is_public 字段如何。

注意

使用 is_public 参数仅限于管理员用户。对于所有其他用户，它将被忽略。

检索镜像元数据¶

我们想要查看 Glance 服务器了解的特定虚拟机镜像的详细信息。

我们已经查询了 Glance 服务器以获取镜像列表，返回的数据包括每个可用镜像的 uri 字段。此 uri 字段值包含获取特定镜像元数据所需的精确位置。

继续上面的示例，为了获取第一个返回镜像的元数据，我们可以向 Glance 服务器发送 HEAD 请求，以获取镜像的 URI。

我们向 http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9 发送 HEAD 请求，以检索该镜像的完整元数据。元数据作为一组以 x-image-meta- 前缀开头的 HTTP 标头返回。以下显示了从上述 HEAD 请求返回的 HTTP 标头的示例

x-image-meta-uri              http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name             Ubuntu 10.04 Plain 5GB
x-image-meta-disk_format      vhd
x-image-meta-container_format ovf
x-image-meta-size             5368709120
x-image-meta-checksum         c2e5db72bd7fd153f53ede5da5a06de3
x-image-meta-created_at       2010-02-03 09:34:01
x-image-meta-updated_at       2010-02-03 09:34:01
x-image-meta-deleted_at
x-image-meta-status           available
x-image-meta-is_public        true
x-image-meta-min_ram          256
x-image-meta-min_disk         0
x-image-meta-owner            null
x-image-meta-property-distro  Ubuntu 10.04 LTS

注意

所有时间戳均以 UTC 格式返回。

x-image-meta-updated_at 时间戳是上次更新镜像元数据的时刻，而不是镜像数据，因为所有镜像数据在存储在 Glance 中后都是不可变的。

可能存在多个以 x-image-meta-property- 前缀开头的标头。这些标头是已与镜像元数据一起保存的自由格式键/值对。键是 x-image-meta-property- 之后的字符串，值是标头的值。

响应的 ETag 标头始终等于 x-image-meta-checksum 值。

响应的 x-image-meta-is_public 值是一个布尔值，指示镜像是否公开可用。

响应的 x-image-meta-owner 值是一个字符串，可以是 null，也可以指示镜像的所有者。

检索原始镜像数据¶

我们想要检索 Glance 服务器了解的特定虚拟机镜像的实际原始数据。

我们已经查询了 Glance 服务器以获取镜像列表，返回的数据包括每个可用镜像的 uri 字段。此 uri 字段值包含获取特定镜像元数据所需的精确位置。

继续上面的示例，为了获取第一个返回镜像的元数据，我们可以向 Glance 服务器发送 HEAD 请求，以获取镜像的 URI。

我们向 http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9 发送 GET 请求，以检索镜像的元数据以及编码到响应主体中的镜像本身。

元数据作为一组以 x-image-meta- 前缀开头的 HTTP 头部返回。以下显示了从上述 GET 请求返回的 HTTP 头部示例

x-image-meta-uri              http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name             Ubuntu 10.04 Plain 5GB
x-image-meta-disk_format      vhd
x-image-meta-container_format ovf
x-image-meta-size             5368709120
x-image-meta-checksum         c2e5db72bd7fd153f53ede5da5a06de3
x-image-meta-created_at       2010-02-03 09:34:01
x-image-meta-updated_at       2010-02-03 09:34:01
x-image-meta-deleted_at
x-image-meta-status           available
x-image-meta-is_public        true
x-image-meta-min_ram          256
x-image-meta-min_disk         5
x-image-meta-owner            null
x-image-meta-property-distro  Ubuntu 10.04 LTS

注意

所有时间戳均以 UTC 格式返回。

x-image-meta-updated_at 时间戳是上次更新镜像元数据的时刻，而不是镜像数据，因为所有镜像数据在存储在 Glance 中后都是不可变的。

响应的 Content-Length 头部应等于 x-image-meta-size 头部的值。

响应的 ETag 标头始终等于 x-image-meta-checksum 值。

响应的 x-image-meta-is_public 值是一个布尔值，指示镜像是否公开可用。

响应的 x-image-meta-owner 值是一个字符串，可以是 null，也可以指示镜像的所有者。

图像数据本身将是来自请求的 HTTP 响应的主体，其 content-type 为 application/octet-stream。

添加新镜像¶

我们已经以某种方式创建了一个新的虚拟机镜像（创建了一个“黄金镜像”或快照/备份了现有镜像），并且我们希望做两件事

将磁盘镜像数据存储在 Glance 中
将有关此镜像的元数据存储在 Glance 中

我们可以通过一次调用 Glance API 来完成上述两个活动。假设，如上面的示例所示，Glance API 服务器正在运行于 http://glance.openstack.example.org，我们向 Glance 发出 POST 请求以添加一个镜像

POST http://glance.openstack.example.org/v1/images

有关镜像的元数据通过 HTTP 头部发送到 Glance。向 Glance API 发出的 HTTP 请求的主体将是 MIME 编码的磁盘镜像数据。

预留新镜像¶

我们还可以使用两次单独的调用 Image API 来执行添加新镜像中描述的活动；第一次注册镜像元数据，第二次添加镜像磁盘数据。这被称为“预留”镜像。

第一次调用应该是向 http://glance.openstack.example.org/v1/images 发出的 POST 请求，这将导致注册一个新的镜像 ID，其状态为 queued

{'image':
 {'status': 'queued',
  'id': '71c675ab-d94f-49cd-a114-e12490b328d9',
  ...}
 ...}

然后可以使用向 http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9 发出的 PUT 请求添加镜像数据。然后 Glance 将镜像状态设置为 active。

HTTP 头部中的镜像元数据

Glance 将在 POST 请求中收到的任何头部，其头部键以字符串 x-image-meta- 和 x-image-meta-property- 开头视为镜像元数据。

Glance 接受的元数据头部列表如下。

x-image-meta-name

除非预留镜像，否则此头部是必需的。其值应该是镜像的名称。

请注意，镜像的名称并非 Glance 节点的唯一名称。期望用户知道所有其他用户所有镜像的所有唯一名称是不现实的。
x-image-meta-id

此头部是可选的。

如果存在，Glance 将使用提供的标识符来标识镜像。如果该标识符已经存在于该 Glance 节点中，Glance 将返回一个 409 Conflict。该头部的取值必须是十六进制字符串表示的 uuid（即 71c675ab-d94f-49cd-a114-e12490b328d9）。

如果此头部不存在，Glance 将为镜像生成一个标识符，并在响应中返回该标识符（如下所示）。
x-image-meta-store

此头部是可选的。有效值是 file、rbd、swift、cinder 或 vsphere 中的一个。

如果存在，Glance 将尝试将磁盘镜像数据存储在头部值指示的后端存储中。如果 Glance 节点不支持后端存储，Glance 将返回一个 400 Bad Request。

如果不存在，Glance 将将磁盘镜像数据存储在标记为默认的后端存储中。有关更多信息，请参见配置选项 default_store。
x-image-meta-disk_format

除非预留镜像，否则此头部是必需的。有效值是 aki、ari、ami、raw、iso、vhd、vhdx、vdi、qcow2、vmdk 或 ploop 中的一个。

有关更多信息，请参见磁盘和容器格式。
x-image-meta-container_format

除非预留镜像，否则此头部是必需的。有效值是 aki、ari、ami、bare、ova、ovf 或 docker。

有关更多信息，请参见磁盘和容器格式。
x-image-meta-size

此头部是可选的。

如果存在，Glance 假定请求主体的预期大小将是此头部的取值。如果请求主体的字节数不匹配此头部的取值，Glance 将返回一个 400 Bad Request。

如果不存在，Glance 将根据请求主体的大小计算镜像的大小。
x-image-meta-checksum

此头部是可选的。如果存在，它指定图像文件数据的 MD5 校验和。

如果存在，Glance 将在存储您的镜像时，将从后端存储生成的校验和与此值进行验证，如果值不匹配，将返回一个 400 Bad Request。
x-image-meta-is_public

此头部是可选的。

当 Glance 找到字符串“true”（不区分大小写）时，该镜像将被标记为公共镜像，这意味着任何用户都可以查看其元数据并从 Glance 读取磁盘镜像。

如果不存在，则假定该镜像不是公共的，并且由用户拥有。
x-image-meta-min_ram

此头部是可选的。如果存在，它指定在服务器上运行此镜像所需的最小 RAM 大小（以兆字节为单位）。

如果不存在，则假定该镜像的最小 RAM 要求为 0。
x-image-meta-min_disk

此头部是可选的。如果存在，它指定在服务器上运行此镜像所需的预期最小磁盘空间（以千兆字节为单位）。

如果不存在，则假定该镜像的最小磁盘空间要求为 0。
x-image-meta-owner

此头部是可选的，仅对管理员有意义。

Glance 将镜像的所有者设置为发出请求的经过身份验证用户的项目。但是，如果经过身份验证的用户具有 Admin 角色，则可以通过将此头部设置为 null 或标识镜像所有者的字符串来覆盖此默认设置。
x-image-meta-property-*

当 Glance 在 POST 请求中收到任何其键以字符串前缀 x-image-meta-property- 开头的 HTTP 头部时，Glance 会将键和值添加到一组与镜像一起存储的自定义、自由格式的镜像属性中。键是紧跟前缀 x-image-meta-property- 的小写字符串，并用下划线替换破折号和标点符号。

例如，如果发送了以下 HTTP 头部
```
x-image-meta-property-distro  Ubuntu 10.10
```
那么一个键/值对“distro”/“Ubuntu 10.10”将被存储在 Glance 中的镜像中。

可以附加到镜像的自由格式键/值属性的数量没有限制。但是，请记住，发送到请求中的所有 HTTP 头部的大小 8K 限制将有效地限制镜像属性的数量。

更新镜像¶

Glance 将在 PUT 请求中收到的任何 HTTP 头部都视为镜像元数据的实例。在这种情况下，头部键应以字符串 x-image-meta- 和 x-image-meta-property- 开头。

如果先前预留了镜像，因此处于 queued 状态，则可以通过将其作为请求主体来添加镜像数据。如果镜像已经关联了数据（例如，它不处于 queued 状态），则包含请求主体将导致 409 Conflict 异常。

成功后，PUT 请求将以 HTTP 头部编码的形式返回镜像元数据。

有关镜像状态的更多信息，请参见：镜像状态

列出镜像成员关系¶

我们想要查看 Glance 服务器了解的给定虚拟机的可以访问该镜像的项目列表。我们获取镜像数据的 uri 字段，在其后附加 /members，并在生成的 URL 上发出 GET 请求。

继续上面的示例，为了获取第一个返回镜像的成员关系，我们可以向 Glance 服务器发出 GET 请求，以获取 http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members。我们将获得如下 JSON 数据

{'members': [
 {'member_id': 'project1',
  'can_share': false}
 ...]}

member_id 字段标识与镜像共享的项目。如果该项目被授权进一步共享镜像，则 can_share 字段为 true。

列出共享镜像¶

我们想要查看与给定项目共享的镜像列表。我们向 http://glance.openstack.example.org/v1/shared-images/project1 发出 GET 请求。我们将获得如下 JSON 数据

{'shared_images': [
 {'image_id': '71c675ab-d94f-49cd-a114-e12490b328d9',
  'can_share': false}
 ...]}

image_id 字段标识与名为 member_id 的项目共享的镜像。如果该项目被授权进一步共享镜像，则 can_share 字段为 true。

将成员添加到镜像¶

我们想要授权项目访问私有镜像。我们向 http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members/project1 发出 PUT 请求。没有主体，这将向镜像添加成员关系，而不会修改现有成员关系，并将新成员关系的 can_share 默认为 false。我们还可以选择附加以下形式的主体

{'member':
 {'can_share': true}
}

如果提供了这样的主体，现有和新成员关系都将具有 can_share 设置为提供的值（true 或 false）。此查询将返回 204（“无内容”）状态码。

从镜像中删除成员¶

我们想要撤销项目访问私有镜像的权利。我们向 http://glance.openstack.example.org/v1/images/1/members/project1 发出 DELETE 请求。此查询将返回 204（“无内容”）状态码。

替换镜像的成员列表¶

给定镜像的完整成员列表可以被替换。我们向 http://glance.openstack.example.org/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members 发出 PUT 请求，并带有以下形式的主体

{'memberships': [
 {'member_id': 'project1',
  'can_share': false}
 ...]}

所有未在替换主体中命名的现有成员关系都将被删除，并且命名成员关系将根据指定的方式更改其 can_share 设置。（可以省略 can_share 设置，这将导致该设置在现有成员关系中保持不变。）所有新成员关系都将被创建，并且 can_share 默认为 false，除非另有说明。

版本 2.0 中的镜像成员关系更改¶

Images API 的版本 2.0 删除了镜像成员关系的 can_share 属性。在版本 2.0 模型中，镜像共享不是传递性的。

在版本 2.0 中，镜像成员具有一个 status 属性，该属性反映了该镜像成员的镜像列表应如何处理该镜像。

“status”属性可能具有以下三个值之一：pending、accepted 或 rejected。
默认情况下，只有状态为 accepted 的共享镜像才会包含在镜像成员的镜像列表中。
只有镜像成员才能更改自己的成员资格状态。
只有镜像所有者才能在镜像上创建成员。新创建的镜像成员的状态为 pending。镜像所有者无法更改成员的状态。

与 1.x API 调用的区别¶

请求列出镜像成员的响应已更改。

调用：对 /v2/images/{imageId}/members 执行 GET

响应：请参阅 /v2/schemas/members 处的 JSON 模式
创建镜像成员的调用的请求体已更改。

调用：向 /v2/images/{imageId}/members 发送 POST

请求体
```
{ "member": "<MEMBER_ID>" }
```
其中 {memberId} 是镜像成员的项目 ID。

新创建的镜像成员的成员状态为 pending。

新的 API 调用¶

更改镜像成员的状态

调用：对 /v2/images/{imageId}/members/{memberId} 执行 PUT

请求体
```
{ "status": "<STATUS_VALUE>" }
```
其中 <STATUS_VALUE> 是 pending、accepted 或 rejected。{memberId} 是镜像成员的项目 ID。

资源限制¶

用户应始终预计任何操作都可能导致 HTTP 413 错误，表明已超出资源消耗限制。以下是一些常见情况的详细说明

创建镜像：如果您的管理员限制了您可以拥有的镜像总数，则镜像创建可能会失败。删除另一个镜像以继续。
将数据上传到镜像：如果您已超过分配给您的镜像存储空间总量，则上传可能会被拒绝。要继续，请删除足够大小的另一个镜像。具有多个位置的镜像会多次计算到您的配额中，因此删除位置也可以释放空间。上传操作（暂存、复制和上传都计入此操作）的数量也有限制，因此您可能需要等待其他操作完成才能继续。
暂存镜像数据：对您可以随时暂存的数据量有单独的配额。要继续，请先完成导入其他镜像或删除具有暂存数据的镜像。
导入镜像：如果从暂存导入到最终目标会超出您的镜像存储空间总量，则导入可能会失败。要继续，请删除其他镜像以腾出空间。

当然，在所有超出限制的情况下，向您的管理员请求更多配额可能是一个选项。

Images v2 Stores API¶

OpenStack Images API 的 2.10 版本引入了新的 /v2/stores/ 端点，用于配置多个存储时。该端点用于从特定存储中删除镜像。

从存储中删除¶

用户想要从特定存储中删除镜像。用户向 /v2/stores/<STORE_ID>/<IMAGE_ID> 发送 DELETE 请求。注意：不接受请求体。

Images v2 Tasks API¶

OpenStack Images API 的第 2 版引入了一个 Task 资源，用于创建和监视长时间运行的异步镜像相关过程。有关更多信息，请参阅 Glance 文档的 Tasks 部分。

可用的 Task 调用如下

创建一个 Task¶

用户想要启动一个 task。用户向 /v2/tasks 发送 POST 请求。请求体的 Content-type 为 application/json，必须包含以下字段

type：由 Task 模式中定义的枚举指定的字符串
input：一个 JSON 对象。内容由公开端点的云提供商定义

响应是一个 Task 实体，由 Task 模式定义。它包括一个 id 字段，可用于后续调用以轮询 task 的状态更改。

Task 以 pending 状态创建。

显示一个 Task¶

用户想要查看用户拥有的 task 的详细信息。用户向 /v2/tasks/{taskId} 发送 GET 请求。

响应采用 application/json 格式。确切结构由位于 /v2/schemas/task 的 task 模式给出。

列出 Tasks¶

用户想要查看在其项目下创建了哪些 task。用户向 /v2/tasks 发送 GET 请求。

响应采用 application/json 格式。确切结构由位于 /v2/schemas/tasks 的 task 模式给出。

请注意，如模式所示，task 列表以稀疏格式提供。要查看列表中特定 task 的更多信息，用户将使用上述的 show task 调用。

过滤和排序 Task 列表¶

GET /v2/tasks 请求接受查询参数，用于过滤返回的 task 列表。以下列表详细介绍了这些查询参数。

status={status}

过滤列表以仅显示指定状态中的 task。请参阅 task 模式或本文档的 Task Statuses 部分，了解 {status} 可以使用的合法值。

例如，向 GET /v2/tasks?status=pending 发送请求将仅返回当前状态为 pending 的 task。
type={type}

过滤列表以仅显示指定类型的 task。请参阅 task 模式中定义的枚举，了解 {type} 可以使用的合法值。

例如，向 GET /v2/tasks?type=import 发送请求将仅返回 import task。
sort_dir={direction}

根据 updated_at 日期时间对 task 列表进行排序。合法值为 asc（升序）和 desc（降序）。默认情况下，task 列表按降序时间顺序对 created_at 时间进行排序。

API 消息本地化¶

Glance 支持 HTTP 消息本地化。例如，即使服务器的区域语言为英语，HTTP 客户端也可以接收中文 API 消息。

如何使用¶

要接收本地化的 API 消息，HTTP 客户端需要指定 Accept-Language 标头，以指示将翻译消息的语言。有关 Accept-Language 的更多信息，请参阅 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

典型的 curl API 请求如下

curl -i -X GET -H 'Accept-Language: zh' -H 'Content-Type: application/json'
http://glance.openstack.example.org/v2/images/aaa

然后响应如下

HTTP/1.1 404 Not Found
Content-Length: 234
Content-Type: text/html; charset=UTF-8
X-Openstack-Request-Id: req-54d403a0-064e-4544-8faf-4aeef086f45a
Date: Sat, 22 Feb 2014 06:26:26 GMT

<html>
<head>
<title>404 Not Found</title>
</head>
<body>
<h1>404 Not Found</h1>
&#25214;&#19981;&#21040;&#20219;&#20309;&#20855;&#26377;&#26631;&#35782; aaa &#30340;&#26144;&#20687;<br /><br />
</body>
</html>

注意

请确保在目标 Glance 服务器的 /usr/share/locale-langpack/ 下有一个语言包。

使用 Glance 的镜像公共 API

使用 Glance 的镜像公共 API¶

Glance 和 Images API：过去、现在和未来¶

Images v1 API¶

Images v2 API¶

未来¶

身份验证¶

使用 v1.X¶

列出可用镜像¶

以更多细节列出可用镜像¶

过滤镜像列表¶

检索镜像元数据¶

检索原始镜像数据¶

添加新镜像¶

预留新镜像¶

更新镜像¶

列出镜像成员关系¶

列出共享镜像¶

将成员添加到镜像¶

从镜像中删除成员¶

替换镜像的成员列表¶

版本 2.0 中的镜像成员关系更改¶

与 1.x API 调用的区别¶

新的 API 调用¶

资源限制¶

Images v2 Stores API¶

从存储中删除¶

Images v2 Tasks API¶

创建一个 Task¶

显示一个 Task¶

列出 Tasks¶

过滤和排序 Task 列表¶

API 消息本地化¶

如何使用¶

glance 31.0.1.dev7

页面内容