Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

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
複数のサブコレクションを追加するには 2 つの方法があります。第 1 の方法では、以下に示したように、複数の detail パラメーターを区切って記述します。 
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
API は、以下のメインコレクションで、拡張サブコレクションをサポートしています。
Expand
表7.4 拡張サブコレクションを使用するコレクション
コレクション拡張サブコレクションのサポート
hostsstatistics
vmsstatistics、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 以降のバージョンでは、SearchResultsLimit パラメーターは REST API に効果がないため、max パラメーターを指定せずに API 検索クエリーを実行すると、すべての値が返されてしまいます。API 検索クエリーによる UI のパフォーマンス低下を防ぐためには、max パラメーターを指定することを推奨します。 
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 テンプレートを使用して GET 要求による検索 query を実行します。 
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 句はオプションです。結果をソートする場合にのみ必要となります。
Expand
表7.5 検索クエリーの例
コレクション条件結果
hostsvms.status=upup 状態の仮想マシンを実行中の全ホストの一覧を表示します。
vmsdomain=qa.company.com指定したドメインで稼働中の全仮想マシンの一覧を表示します。
vmsusers.name=maryユーザー名が mary のユーザーに属する全仮想マシンの一覧を表示します。
eventsseverity>normal sortby time重大度が normal を超えるすべての events の一覧を表示し、time 要素値でソートします。
eventsseverity>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

7.3.8. ワイルドカード
リンクのコピー

検索クエリーで、値の一部の代わりに、アスタリスクをワイルドカードとして使用します。

例7.4 ワイルドカードを使用した name=vm* の検索クエリー

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
このクエリーは、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
次の結果ページを表示させる場合は 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 はステートレスです。要求はすべて 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]

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>
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hatトップに戻る