3.7. 検索
一部のサービスの list メソッドには、検索 条件の指定に使用できる search パラメーターがあります。これを使用すると、サーバーは上記の基準を満たすコレクション内のオブジェクトのみを返します。たとえば、以下の要求では myvm という名前の仮想マシンのみを返します。
GET /ovirt-engine/api/vms?search=name%3Dmyvm
3.7.1. 最大結果パラメーター
max パラメーターを使用して、返されるオブジェクトの数を制限します。たとえば、以下の要求は、システムで利用可能なものに関係なく、仮想マシンが 1 つだけ返されます。
GET /ovirt-engine/api/vms?max=1
max パラメーターのない検索要求は、すべてのオブジェクトを返します。システムの全体的なパフォーマンスにおける要求の影響を減らすために、max パラメーターを指定することが推奨されます。
3.7.2. ケースの機密性
デフォルトでは、クエリーは大文字と小文字を区別しません。たとえば、以下の要求は、myvm、MyVM、および MYVM という名前の仮想マシンを返します。
GET /ovirt-engine/api/vms?search=name%3Dmyvm
この動作を変更するには、任意の case_sensitive boolean パラメーターを使用できます。たとえば、MyHost または MYHOST ではなく myhost という名前の仮想マシンを取得するには、以下のように要求を送信します。
GET /ovirt-engine/api/vms?search=name%3D=myvm&case_sensitive=true
3.7.3. 検索構文
search パラメーターは、Red Hat Virtualization クエリー言語と同じ構文を使用します。
(criteria) [sortby (element) asc|desc]
sortby 句はオプションで、結果を順序付ける場合にのみ必要です。
検索クエリーの例
| コレクション | 基準 | 結果 |
|---|---|---|
|
|
|
|
|
|
| 指定されたドメインで稼働しているすべての仮想マシンの一覧を返します。 |
|
|
|
ユーザー名が |
|
|
|
重大度が |
|
|
|
重大度が |
search パラメーターの値は、演算子やスペースなどの予約済み文字を変換するために URL エンコード されている必要があります。たとえば、等号は %3D としてエンコードする必要があります。
GET /ovirt-engine/api/vms?search=name%3Dmyvm
3.7.4. ワイルドカード
アスタリスクは値の一部として使用して、empty の文字列が含まれる文字列を検索できます。たとえば、以下のリクエストでは、myvm、myvm2、myvma、myvm-webserver など、myvm で始まる名前の仮想マシンをすべて返します。
GET /ovirt-engine/api/vms?search=name%3Dmyvm*
3.7.5. ページネーション
一部の Red Hat Virtualization 環境には、大規模なオブジェクトが含まれます。一度のリクエストですべてを取得するのは現実的ではなく、パフォーマンスも悪くなります。ページ単位での検索を可能にするため、search パラメーターはオプションで page 句をサポートしています。これは、max パラメーターと組み合わせてページングの基礎となります。たとえば、ページサイズが 10 の仮想マシンの最初のページを取得するには、以下のように要求を送信します。
GET /ovirt-engine/api/vms?search=page%201&max=10
search パラメーターは URL エンコードされており、エンコード前の実際の search パラメーターの値は page 1 なので、実際には 1 ページ目を要求していることになります。
page 値を増やして、次のページを取得します。
GET /ovirt-engine/api/vms?search=page%202&max=10
page 句は、search パラメーター内の他の句と組み合わせて使用できます。たとえば、以下の要求は仮想マシンの 2 ページ目を返しますが、名前で並べ替えます。
GET /ovirt-engine/api/vms?search=sortby%20name%20page%202&max=10
API はステートレスで、すべての要求が互いに独立しているため、異なる要求間で状態を維持することはできません。その結果、要求間でステータスが変更されると、ページの結果に一貫性がなくなることがあります。
たとえば、仮想マシンの一覧から特定のページを要求し、次のページを要求する前に仮想マシンが作成または削除された場合には、結果の一部が欠落しているか、または重複が含まれる可能性があります。
