7.3. 集合

7.3.1. 集合

集合就是相同类型的一组资源。API 提供了顶级集合和子集合。hosts 集合是一个顶级集合的例子，它包括了虚拟环境中的所有虚拟主机。host.nics 集合是子集合的一个例子，它包括了附加到一个主机资源上的所有网络接口卡。

7.3.2. 列出一个集合中的所有资源

使用一个从进入点获得的集合 URI 的 GET 请求来得到一个集合中的资源列表。

包括一个 Accept HTTP 头来定义响应格式的 MIME 类型。

GET /api/[collection] HTTP/1.1
Accept: [MIME type]

7.3.3. 列出扩展的资源子集合

当 Accept 头包括了 detail 参数时，API 会扩展它的集合表述来包括子集合信息。

GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection

使用多个 detail 参数来包括多个子集合请求：

GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1; detail=subcollection2

或在一个 detail 参数中包括由 + 操作符分隔的多个子集合：

GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1+subcollection2+subcollection3

API 支持以下主集合中的扩展子集合。

表 7.4. 使用扩展子集合的集合
集合	支持的扩展子集合
`hosts`	`statistics`
`vms`	`statistics`、`nics`、`disks`

例 7.1. 对 vms 集合中的 statistics、NICs 和 disks 扩展子集合的请求

GET /api/vms HTTP/1.1
Accept: application/xml; detail=statistics+nics+disks

7.3.4. 使用查询条件来搜索集合

对 "collection/search" 链接的 GET 请求会执行一个对所指定集合的查询。API 只返回那些满足查询条件的集合。

GET /api/collection?search={query} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        ...
    </resource>
    ...
</collection>

7.3.5. 最大结果参数

使用 max URL 参数可以限制返回结果的数量。在 Red Hat Enterprise Virtualization 3.4 以前，返回结果的数量限制是由 SearchResultsLimit 参数指定的。从 Red Hat Enterprise Virtualization 3.4 开始，这个参数将不对 REST API 起作用，如果 API 搜索查询中没有指定 max 参数，它会返回所有结果。我们推荐用户使用 max 参数来防止因大量 API 搜索查询结果可能造成的、对 UI 性能的影响。

GET /api/collection;max=1 HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </resource>
</collection>

7.3.6. 区分大小写

在默认的情况下，所有搜索查询都是区分大小写的。URL 提供了一个布尔选项来切换区分大小写或不区分大小写的查询。

例 7.2. 不区分大小写的搜索查询

GET /api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml

7.3.7. 查询语法

API 使用 URI 模板来执行带有搜索 query 的 GET 请求：

GET /api/collection?search={query} HTTP/1.1
Accept: application/xml

query 模板值指向 API 对 collection 的搜索查询。这个 query 使用和 Red Hat Enterprise Virtualization Query Language 相同的格式：

(criteria) [sortby (element) asc|desc]

sortby 是可选的，它只在需要对结果进行排序时才使用。

表 7.5. 搜索查询实例
集合	条件	结果
`hosts`	`vms.status=up`	显示所有运行的虚拟机的状态为 `up` 的主机列表。
`vms`	`domain=qa.company.com`	显示运行于指定域中的所有虚拟机列表。
`vms`	`users.name=mary`	显示属于用户 `mary` 的所有虚拟机列表。
`events`	`severity>normal sortby time`	显示所有 severity 的值高于 `normal` 的`事件`，并以`时间`顺序排序。
`events`	`severity>normal sortby time desc`	显示所有 severity 的值高于 `normal` 的`事件`，并以`时间`进行倒序排序。

API 需要 query 模板使用 URL 编码来翻译那些保留的字符，如操作符和空格。

例 7.3. URL 编码的搜索查询

GET /api/vms?search=name%3Dvm1 HTTP/1.1
Accept: application/xml

7.3.8. 通配符

在搜索查询中可以使用星号作为通配符。

例 7.4. 在搜索查询中使用通配符 name=vm*

GET /api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml

这个查询的结果将包括所有名称以 vm 开头的虚拟机，如 vm1、vm2、vma 和 vm-webserver。

例 7.5. 在搜索查询中使用通配符 name=v*1

GET /api/vms?search=name%3Dv*1 HTTP/1.1
Accept: application/xml

这个查询的结果将包括所有名称以 v 开头并以1 结束的虚拟机，如 vm1、vr1 和 virtualmachine1。

7.3.9. 分页

一些 Red Hat Enterprise Virtualization 环境会包括大量资源集合，但是 API 只会显示默认数量的集合搜索查询结果。要显示更多的结果，在搜索查询中包括 page 命令，API 会把返回的集合分为不同的页。

例 7.6. 为资源分页

这个实例对一个机器中的资源进行分页。使用 URL 编码的请求是：

GET /api/collection?search=page%201 HTTP/1.1
Accept: application/xml

增加 page 的值来查看结果的下一页：

GET /api/collection?search=page%202 HTTP/1.1
Accept: application/xml

在其它命令中使用 page 命令。例如：

GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1
Accept: application/xml

这个查询会显示集合的第 2 页（结果以所选项排序）。

重要

REST API 是无状态的，每个请求都独立于其它请求，它们无法保持其它请求的状态。因此，如果在不同的请求间发生了状态改变，结果页的内容可能会不一致。

例如，您请求了一组 VM 的一个特定页，而在您请求下一页前，发生了一些状态改变，您所获得的结果可能就会缺少一些数据，或包括了一些重复的数据。

7.3.10. 在集合中创建一个资源

使用一个到包括了一个新资源表述的集合 URI 的 POST 请求来创建一个新资源。

POST 请求需要一个 Content-Type 头。它会告诉 API 在内容数据中使用的表述 MIME 类型。

包括一个 Accept HTTP 头来定义响应格式的 MIME 类型。

每个资源类型都有它们特定的属性。客户端需要在创建新资源时提供这些属性。请参阅具体资源的相关文档来获得详细的信息。

如果缺少了一个所需的属性，创建操作会失败，一个包括了所缺属性信息的表述会返回。

POST /api/[collection] HTTP/1.1
Accept: [MIME type]
Content-Type: [MIME type]

[body]

7.3.11. 异步请求

如果用户没有使用 Expect: 201-created 头，API 将会执行异步 POST 请求。

例如，特定资源（如虚拟机、磁盘、快照和模板）会以异步的形式创建。异步创建资源的请求会获得一个 202 Accepted 状态。202 Accepted 资源的初始文档结构中也包括了一个 creation_status 项，以及到创建状态更新的链接。例如：

POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <name>Resource-Name</name>
</resource>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    <name>Resource-Name</name>
    <creation_status>
        <state>pending</state>
    </creation status>
    <link rel="creation_status" 
      href="/api/collection/resource_id/creation_status/creation_status_id"/>
      ...
</resource>

到 creation_status 链接的 GET 请求提供了创建状态的更新信息：

GET /api/collection/resource_id/creation_status/creation_status_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<creation id="creation_status_id"
  href="/api/collection/resource_id/creation_status/creation_status_id">
    <status>
        <state>complete</state>
    </status>
</creation>

如果不以异步的形式创建资源，使用 Expect: 201-created 头：

POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

<resource>
    <name>Resource-Name</name>
</resource>