Red Hat Summit Red Hat Summit지원콘솔개발자평가판 시작연락처

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

7.3. Collections

7.3.1. Collections
링크 복사

A collection is a set of resources of the same type. The API provides both top-level collections and sub-collections. An example of a top-level collection is the hosts collection which contains all virtualization hosts in the environment. An example of a sub-collection is the host.nics collection which contains resources for all network interface cards attached to a host resource.

7.3.2. Listing All Resources in a Collection
링크 복사

Obtain a listing of resources in a collection with a GET request on the collection URI obtained from the entry point.
Include an Accept HTTP header to define the MIME type for the response format. 
GET /ovirt-engine/api/[collection] HTTP/1.1
Accept: [MIME type]
Copy to Clipboard Toggle word wrap

7.3.3. Listing Extended Resource Sub-Collections
링크 복사

The API extends collection representations to include sub-collections when the Accept header includes the detail parameter. 
GET /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml; detail=subcollection
Copy to Clipboard Toggle word wrap
This includes multiple sub-collection requests using either separated detail parameters: 
GET /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1; detail=subcollection2
Copy to Clipboard Toggle word wrap
Or one detail parameter that separates the sub-collection with the + operator: 
GET /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
Copy to Clipboard Toggle word wrap
The API supports extended sub-collections for the following main collections.
Expand
Table 7.4. Collections that use extended sub-collections
Collection Extended Sub-Collection Support
hosts statistics
vms statistics, nics, disks

Example 7.1. A request for extended statistics, NICs and disks sub-collections in the vms collection

GET /ovirt-engine/api/vms HTTP/1.1
Accept: application/xml; detail=statistics+nics+disks
Copy to Clipboard Toggle word wrap

7.3.4. Searching Collections with Queries
링크 복사

A GET request on a "collection/search" link results in a search query of that collection. The API only returns resources within the collection that satisfy the search query constraints. 
GET /ovirt-engine/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="/ovirt-engine/api/collection/resource_id">
        ...
    </resource>
    ...
</collection>
Copy to Clipboard Toggle word wrap

7.3.5. Maximum Results Parameter
링크 복사

Use the max URL parameter to limit the list of results. An API search query without specifying the max parameter will return all values. Specifying the max parameter is recommended to prevent API search queries from slowing UI performance. 
GET /ovirt-engine/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="/ovirt-engine/api/collection/resource_id">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </resource>
</collection>
Copy to Clipboard Toggle word wrap

7.3.6. Case Sensitivity
링크 복사

All search queries are case sensitive by default. The URL syntax provides a Boolean option to toggle case sensitivity.

Example 7.2. Case insensitive search query

GET /ovirt-engine/api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap

7.3.7. Query Syntax
링크 복사

The API uses the URI templates to perform a search query with a GET request: 
GET /ovirt-engine/api/collection?search={query} HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
The query template value refers to the search query the API directs to the collection. This query uses the same format as Red Hat Virtualization Query Language:
(criteria) [sortby (element) asc|desc]
The sortby clause is optional and only needed when ordering results.
Expand
Table 7.5. Example search queries
Collection Criteria Result
hosts vms.status=up Displays a list of all hosts running virtual machines that are up.
vms domain=qa.company.com Displays a list of all virtual machines running on the specified domain.
vms users.name=mary Displays a list of all virtual machines belonging to users with the user name mary.
events severity>normal sortby time Displays the list of all events with severity higher than normal and sorted by the time element values.
events severity>normal sortby time desc Displays the list of all events with severity higher than normal and sorted by the time element values in descending order.
The API requires the query template to be URL-encoded to translate reserved characters, such as operators and spaces.

Example 7.3. URL-encoded search query

GET /ovirt-engine/api/vms?search=name%3Dvm1 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap

7.3.8. Wildcards
링크 복사

Search queries substitute part of a value with an asterisk as a wildcard.

Example 7.4. Wildcard search query for name=vm*

GET /ovirt-engine/api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
This query would result in all virtual machines with names beginning with vm, such as vm1, vm2, vma or vm-webserver.

Example 7.5. Wildcard search query for name=v*1

GET /ovirt-engine/api/vms?search=name%3Dv*1 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
This query would result in all virtual machines with names beginning with v and ending with 1, such as vm1, vr1 or virtualmachine1.

7.3.9. Pagination
링크 복사

Some Red Hat Virtualization environments contain large collections of resources. However, the API only displays a default number of resources for one search query to a collection. To display more than the default, the API separates collections into pages via a search query containing the page command.

Example 7.6. Paginating resources

This example paginates resources in a collection. The URL-encoded request is: 
GET /ovirt-engine/api/collection?search=page%201 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
Increase the page value to view the next page of results: 
GET /ovirt-engine/api/collection?search=page%202 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
Use the page command in conjunction with other commands in a search query. For example: 
GET /ovirt-engine/api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1
Accept: application/xml
Copy to Clipboard Toggle word wrap
This query displays the second page in a collection listing ordered by a chosen element.

Important

The REST APIs are stateless; it is not possible to retain a state between different requests since all requests are independent from each other. As a result, if a status change occurs between your requests, then the page results may be inconsistent.
For example, if you request a specific page from a list of VMs, and a status change occurs before you can request the next page, then your results may be missing entries or contain duplicated entries.

7.3.10. Creating a Resource in a Collection
링크 복사

Create a new resource with a POST request to the collection URI containing a representation of the new resource.
A POST request requires a Content-Type header. This informs the API of the representation MIME type in the body content as part of the request.
Include an Accept HTTP header to define the MIME type for the response format.
Each resource type has its own specific required properties. The client supplies these properties when creating a new resource. Refer to the individual resource type documentation for more details.
If a required property is absent, the creation fails with a representation indicating the missing elements. 
POST /ovirt-engine/api/[collection] HTTP/1.1
Accept: [MIME type]
Content-Type: [MIME type]

[body]
Copy to Clipboard Toggle word wrap

7.3.11. Asynchronous Requests
링크 복사

The API performs asynchronous POST requests unless the user overrides them with an Expect: 201-created header.
For example, certain resources, such as Virtual Machines, Disks, Snapshots and Templates, are created asynchronously. A request to create an asynchronous resource results in a 202 Accepted status. The initial document structure for a 202 Accepted resource also contains a creation_status element and link for creation status updates. For example: 
POST /ovirt-engine/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="/ovirt-engine/api/collection/resource_id">
    <name>Resource-Name</name>
    <creation_status>
        <state>pending</state>
    </creation status>
    <link rel="creation_status" 
      href="/ovirt-engine/api/collection/resource_id/creation_status/creation_status_id"/>
      ...
</resource>
Copy to Clipboard Toggle word wrap
A GET request to the creation_status link provides a creation status update: 
GET /ovirt-engine/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="/ovirt-engine/api/collection/resource_id/creation_status/creation_status_id">
    <status>
        <state>complete</state>
    </status>
</creation>
Copy to Clipboard Toggle word wrap
Overriding the asynchronous resource creation requires an Expect: 201-created header: 
POST /ovirt-engine/api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

<resource>
    <name>Resource-Name</name>
</resource>
Copy to Clipboard Toggle word wrap
맨 위로 이동
Red Hat logoGithubredditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2025 Red Hat