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]
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
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection
複数のサブコレクションを追加するには 2 つの方法があります。第 1 の方法では、以下に示したように、複数の
detail
パラメーターを区切って記述します。
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1; detail=subcollection2
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1; detail=subcollection2
第 2 の方法では、以下に示したように、単一の
detail
パラメーターで、サブコレクションを +
演算子で区切ります。
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
API は、以下のメインコレクションで、拡張サブコレクションをサポートしています。
コレクション | 拡張サブコレクションのサポート |
---|---|
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
GET /api/vms HTTP/1.1
Accept: application/xml; detail=statistics+nics+disks
7.3.4. クエリーを使用したコレクションの検索 リンクのコピーリンクがクリップボードにコピーされました!
リンクのコピーリンクがクリップボードにコピーされました!
"collection/search"
リンクに対する GET
要求は、そのコレクションの検索クエリーとなります。API は、検索クエリーの制約を満たすコレクション内のリソースのみを返します。
7.3.5. 検索結果の最大表示件数のパラメーター リンクのコピーリンクがクリップボードにコピーされました!
リンクのコピーリンクがクリップボードにコピーされました!
結果一覧のサイズを制限するには、
max
URL パラメーターを使用します。Red Hat Enterprise Virtualization 3.4 より前のバージョンでは、結果のデフォルトサイズは SearchResultsLimit パラメーターで制限されていました。Red Hat Enterprise Virtualization 3.4 以降のバージョンでは、SearchResultsLimit パラメーターは REST API に効果がないため、max
パラメーターを指定せずに API 検索クエリーを実行すると、すべての値が返されてしまいます。API 検索クエリーによる UI のパフォーマンス低下を防ぐためには、max
パラメーターを指定することを推奨します。
7.3.6. 大文字と小文字の区別 リンクのコピーリンクがクリップボードにコピーされました!
リンクのコピーリンクがクリップボードにコピーされました!
デフォルトでは、検索クエリーはすべて大文字と小文字が区別されます。大文字/小文字の区別を切り替えるためのブール値オプションは、URL 構文で提供されます。
例7.2 大文字/小文字を区別しない検索クエリー
GET /api/collection;case-sensitive=false?search={query} HTTP/1.1 Accept: application/xml
GET /api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml
7.3.7. クエリーの構文 リンクのコピーリンクがクリップボードにコピーされました!
リンクのコピーリンクがクリップボードにコピーされました!
API は、URI テンプレートを使用して
GET
要求による検索 query
を実行します。
GET /api/collection?search={query} HTTP/1.1 Accept: application/xml
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
query
テンプレートの値は、API が collection
に送る検索クエリーを参照します。この query
は、Red Hat Enterprise Virtualization 検索クエリー言語と同じ形式を使用します。
(criteria) [sortby (element) asc|desc]
sortby
句はオプションです。結果をソートする場合にのみ必要となります。
コレクション | 条件 | 結果 |
---|---|---|
hosts | vms.status=up | up 状態の仮想マシンを実行中の全ホストの一覧を表示します。 |
vms | domain=qa.company.com | 指定したドメインで稼働中の全仮想マシンの一覧を表示します。 |
vms | users.name=mary | ユーザー名が mary のユーザーに属する全仮想マシンの一覧を表示します。 |
events | severity>normal sortby time | 重大度が normal を超えるすべての events の一覧を表示し、time 要素値でソートします。 |
events | severity>normal sortby time desc | 重大度が normal を超えるすべての events の一覧を表示し、time 要素値の降順にソートします。 |
API は、
query
テンプレートを URL エンコードして、演算子や空白など予約文字を変換する必要があります。
例7.3 URL エンコードされた検索クエリー
GET /api/vms?search=name%3Dvm1 HTTP/1.1 Accept: application/xml
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
GET /api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml
このクエリーは、
vm1
、vm2
、vma
、vm-webserver
など vm
で始まる仮想マシン名をすべて表示します。
例7.5 ワイルドカードを使用した name=v*1 の検索クエリー
GET /api/vms?search=name%3Dv*1 HTTP/1.1 Accept: application/xml
GET /api/vms?search=name%3Dv*1 HTTP/1.1
Accept: application/xml
このクエリーは、
vm1
、vr1
、virtualmachine1
など v
で始まり 1
で終わる仮想マシン名をすべて表示します。
7.3.9. ページネーション リンクのコピーリンクがクリップボードにコピーされました!
リンクのコピーリンクがクリップボードにコピーされました!
Red Hat Enterprise Virtualization 環境の中には、リソースのコレクションが大量に含まれている場合がありますが、API は 1 つのコレクションに対する 1 回の検索クエリーに設定されているデフォルト数のリソースのみを表示します。デフォルト数以上のリソースを表示するには、
page
コマンドを検索クエリーに追加すると、API はコレクションを複数のページに分割します。
例7.6 リソースのページネーション
以下の例では、1 つのコレクション内の複数のリソースをページネーションします。URL エンコードされた要求は次のようになります。
GET /api/collection?search=page%201 HTTP/1.1 Accept: application/xml
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
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
GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1
Accept: application/xml
このクエリーにより、コレクション一覧内の第 2 ページが選択した要素の順に表示されます。
重要
REST API はステートレスです。要求はすべて 1 つずつ独立しているため、別の要求との間で状態を保持することはできません。そのため、要求と要求の間でステータスが変更されると、ページの結果に整合性がなくなります。
たとえば、仮想マシンの一覧から特定のページを要求し、次のページを要求する前にステータスが変更された場合は、出力される結果でエントリーが足りないか、重複エントリーが含まれている可能性があります。
7.3.10. コレクション内のリソース作成 リンクのコピーリンクがクリップボードにコピーされました!
リンクのコピーリンクがクリップボードにコピーされました!
新規リソースの表現を含むコレクション URI に対して
POST
要求を実行して、新規リソースを作成します。
POST
要求には、Content-Type
ヘッダーが必要です。このヘッダーは、要求の一部として、本文コンテンツ内の表現の MIME タイプを API に通知します。
Accept
HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。
各リソースタイプには、それぞれ固有の必須プロパティーがあります。これらのプロパティーは、新規リソース作成時にクライアントから提供されます。詳細については、各リソースタイプの説明を参照してください。
必須プロパティーが存在しない場合には、作成が失敗し、表現に不足している要素が示されます。
POST /api/[collection] HTTP/1.1 Accept: [MIME type] Content-Type: [MIME type] [body]
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
要素と作成ステータス更新用リンクも含まれます。以下が例となります。
creation_status
リンクに対して GET
要求を実行すると、作成ステータスの更新が提供されます。
非同期リソースの作成をオーバーライドするには
Expect: 201-created
ヘッダーが必要です。